diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 03e0ead208..f9187e4eda 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -63,6 +63,12 @@ repos: hooks: - id: yamllint + - repo: https://github.com/thlorenz/doctoc + rev: v2.2.0 + hooks: + - id: doctoc + args: [--update-only, --title, '## Table of Contents'] + ci: skip: [golangci-lint-full, prettier, markdownlint-cli2, yamllint] autofix_prs: false diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 506706ddc5..dc5b5c44ed 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,20 +3,23 @@ The following is a set of guidelines for contributing to NGINX Gateway Fabric. We really appreciate that you are considering contributing! -## Table Of Contents - -[Ask a Question](#ask-a-question) - -[Getting Started](#getting-started) - -[Contributing](#contributing) - -- [Issues and Discussions](#issues-and-discussions) -- [Development Guide](#development-guide) - -[Code of Conduct](CODE_OF_CONDUCT.md) - -[Contributor License Agreement](#contributor-license-agreement) + + +## Table of Contents + +- [Ask a Question](#ask-a-question) +- [Getting Started](#getting-started) + - [Project Structure](#project-structure) +- [Contributing](#contributing) + - [Issues and Discussions](#issues-and-discussions) + - [Open a Discussion](#open-a-discussion) + - [Report a Bug](#report-a-bug) + - [Suggest an Enhancement](#suggest-an-enhancement) + - [Issue lifecycle](#issue-lifecycle) + - [Development Guide](#development-guide) +- [Contributor License Agreement](#contributor-license-agreement) + + ## Ask a Question diff --git a/docs/developer/go-style-guide.md b/docs/developer/go-style-guide.md index 57955c205c..14aea3436f 100644 --- a/docs/developer/go-style-guide.md +++ b/docs/developer/go-style-guide.md @@ -10,13 +10,37 @@ Once you have a good grasp of these general best practices, you can then explore These guidelines will often build upon the foundation set by the general best practices and provide additional recommendations tailored to the project's specific requirements and coding style. + + ## Table of Contents -1. [General Guidelines](#general-guidelines) -2. [Error Handling](#error-handling) -3. [Logging](#logging) -4. [Concurrency](#concurrency) -5. [Recommended/Situational Guidelines](#recommended--situational) +- [General Guidelines](#general-guidelines) + - [Use the empty struct `struct{}` for sentinel values](#use-the-empty-struct-struct-for-sentinel-values) + - [Consistent Line Breaks](#consistent-line-breaks) + - [Do not copy sync entities](#do-not-copy-sync-entities) + - [Construct slices with known capacity](#construct-slices-with-known-capacity) + - [Accept interfaces and return structs](#accept-interfaces-and-return-structs) + - [Use contexts in a viral fashion](#use-contexts-in-a-viral-fashion) + - [Do not use templates to replace interface types](#do-not-use-templates-to-replace-interface-types) + - [Do not use booleans as function parameters](#do-not-use-booleans-as-function-parameters) + - [Use dependency injection to separate concerns](#use-dependency-injection-to-separate-concerns) + - [Required arguments should be provided via parameters and optional arguments provided functionally or with structs](#required-arguments-should-be-provided-via-parameters-and-optional-arguments-provided-functionally-or-with-structs) +- [Error Handling](#error-handling) + - [Prefer inline error handling](#prefer-inline-error-handling) + - [Do not filter context when returning errors](#do-not-filter-context-when-returning-errors) + - [Only handle errors once](#only-handle-errors-once) + - [Libraries should return errors for callers to handle](#libraries-should-return-errors-for-callers-to-handle) + - [Callers should handle errors and pass them up the stack for notification](#callers-should-handle-errors-and-pass-them-up-the-stack-for-notification) + - [Use panics for unrecoverable errors or programming errors](#use-panics-for-unrecoverable-errors-or-programming-errors) +- [Logging](#logging) +- [Concurrency](#concurrency) +- [Recommended / Situational](#recommended--situational) + - [Use golang benchmark tests and pprof tools for profiling and identifying hot spots](#use-golang-benchmark-tests-and-pprof-tools-for-profiling-and-identifying-hot-spots) + - [Reduce the number of stored pointers. Structures should store instances whenever possible](#reduce-the-number-of-stored-pointers-structures-should-store-instances-whenever-possible) + - [Pass pointers down the stack not up](#pass-pointers-down-the-stack-not-up) + - [Using interface types will cause unavoidable heap allocations](#using-interface-types-will-cause-unavoidable-heap-allocations) + + ## General Guidelines diff --git a/docs/developer/logging-guidelines.md b/docs/developer/logging-guidelines.md index 9948011b5e..ae15642c24 100644 --- a/docs/developer/logging-guidelines.md +++ b/docs/developer/logging-guidelines.md @@ -5,39 +5,37 @@ This document describes the logging guidelines for the control plane of NGINX Ga > The data plane logging is not covered here: such a concern is owned by NGINX developers, and NGF developers > don't have control over it. + + ## Table of Contents - - -- [Logging Guidelines](#logging-guidelines) - - [Table of Contents](#table-of-contents) - - [Requirements](#requirements) - - [User Stories](#user-stories) - - [Common Stories](#common-stories) - - [Stories For User](#stories-for-user) - - [Stories For Developers](#stories-for-developers) - - [Logging Library Choice](#logging-library-choice) - - [Guidelines](#guidelines) - - [How to Log](#how-to-log) - - [Log Levels](#log-levels) - - [Log Messages](#log-messages) - - [Context in Messages](#context-in-messages) - - [Examples of Log Messages](#examples-of-log-messages) - - [Message Guidelines](#message-guidelines) - - [Log Formatting](#log-formatting) - - [When to Log](#when-to-log) - - [What not to Log](#what-not-to-log) - - [Performance](#performance) - - [Logger Dependency in Code](#logger-dependency-in-code) - - [Logger Initialization](#logger-initialization) - - [Logger Injection](#logger-injection) - - [Special Case - Reconciler](#special-case---reconciler) - - [Unit Tests](#unit-tests) - - [External Libraries](#external-libraries) - - [Evolution](#evolution) - - [External Resources](#external-resources) - - +- [Requirements](#requirements) + - [User Stories](#user-stories) + - [Common Stories](#common-stories) + - [Stories For User](#stories-for-user) + - [Stories For Developers](#stories-for-developers) +- [Logging Library Choice](#logging-library-choice) +- [Guidelines](#guidelines) + - [How to Log](#how-to-log) + - [Log Levels](#log-levels) + - [Log Messages](#log-messages) + - [Context in Messages](#context-in-messages) + - [Examples of Log Messages](#examples-of-log-messages) + - [Message Guidelines](#message-guidelines) + - [Log Formatting](#log-formatting) + - [When to Log](#when-to-log) + - [What not to Log](#what-not-to-log) + - [Performance](#performance) + - [Logger Dependency in Code](#logger-dependency-in-code) + - [Logger Initialization](#logger-initialization) + - [Logger Injection](#logger-injection) + - [Special Case - Reconciler](#special-case---reconciler) + - [Unit Tests](#unit-tests) + - [External Libraries](#external-libraries) + - [Evolution](#evolution) +- [External Resources](#external-resources) + + ## Requirements diff --git a/docs/developer/quickstart.md b/docs/developer/quickstart.md index 0b0a7a8845..448123a973 100644 --- a/docs/developer/quickstart.md +++ b/docs/developer/quickstart.md @@ -4,6 +4,26 @@ This guide will assist you in setting up your development environment for NGINX to build, install, and execute tasks necessary for submitting pull requests. By following this guide, you'll have a fully prepared development environment that allows you to contribute to the project effectively. + + +## Table of Contents + +- [Setup Your Development Environment](#setup-your-development-environment) +- [Build the Binary and Images](#build-the-binary-and-images) + - [Setting GOARCH](#setting-goarch) + - [Build the Binary](#build-the-binary) + - [Build the Images](#build-the-images) + - [Build the Images with NGINX Plus](#build-the-images-with-nginx-plus) +- [Deploy on Kind](#deploy-on-kind) + - [Run Examples](#run-examples) +- [Run the Unit Tests](#run-the-unit-tests) +- [Gateway API Conformance Testing](#gateway-api-conformance-testing) +- [Run the Linter](#run-the-linter) +- [Run the Helm Linter](#run-the-helm-linter) +- [Update all the generated files](#update-all-the-generated-files) + + + ## Setup Your Development Environment Follow these steps to set up your development environment. diff --git a/docs/developer/release-process.md b/docs/developer/release-process.md index 9601e21b4d..b458982959 100644 --- a/docs/developer/release-process.md +++ b/docs/developer/release-process.md @@ -2,6 +2,18 @@ This document outlines the release process for NGINX Gateway Fabric (NGF). + + +## Table of Contents + +- [Versioning](#versioning) +- [Release Planning and Development](#release-planning-and-development) +- [Releasing](#releasing) + - [Major or Minor Release](#major-or-minor-release) + - [Patch Release](#patch-release) + + + ## Versioning NGF uses semantic versioning for its releases. For more information, see https://semver.org. diff --git a/docs/proposals/nginx-extensions.md b/docs/proposals/nginx-extensions.md index 5a77e0140e..e5faec5922 100644 --- a/docs/proposals/nginx-extensions.md +++ b/docs/proposals/nginx-extensions.md @@ -8,61 +8,61 @@ NGINX is highly configurable and offers rich features that can benefit our users. We want to expose this native NGINX configuration to our users through Gateway API extension points -- such as Policies and Filters. This Enhancement Proposal aims to identify the set of NGINX directives and parameters we will expose first, group them according to Gateway API role(s), NGINX contexts, and use cases, and propose the type of extension point for each group. + + ## Table of Contents - -- [Extensions for NGINX Features](#extensions-for-nginx-features) - - [Summary](#summary) - - [Table of Contents](#table-of-contents) - - [Goals](#goals) - - [Non-Goals](#non-goals) - - [Gateway API Extensions](#gateway-api-extensions) - - [GatewayClass Parameters Ref](#gatewayclass-parameters-ref) - - [Issues with `parametersRef`](#issues-with-parametersref) - - [Infrastructure API](#infrastructure-api) - - [TLS Options](#tls-options) - - [Filters](#filters) - - [BackendRef](#backendref) - - [Policy](#policy) - - [Direct Policy Attachment](#direct-policy-attachment) - - [Inherited Policy Attachment](#inherited-policy-attachment) - - [Hierarchy](#hierarchy) - - [Challenges of Policy Attachment](#challenges-of-policy-attachment) - - [Prioritized NGINX Features](#prioritized-nginx-features) - - [High-Priority Features](#high-priority-features) - - [Medium-Priority Features](#medium-priority-features) - - [Low-Priority Features](#low-priority-features) - - [Features with Active Gateway API Enhancement Proposals](#features-with-active-gateway-api-enhancement-proposals) - - [Grouping the Features](#grouping-the-features) - - [API](#api) - - [Gateway Settings](#gateway-settings) - - [Future Work](#future-work) - - [Alternatives](#alternatives) - - [Response Modification](#response-modification) - - [Future Work](#future-work-1) - - [Alternatives](#alternatives-1) - - [TLS Settings](#tls-settings) - - [Future Work](#future-work-2) - - [Alternatives](#alternatives-2) - - [Client Settings](#client-settings) - - [Future Work](#future-work-3) - - [Alternatives](#alternatives-3) - - [Upstream Settings](#upstream-settings) - - [Alternatives](#alternatives-4) - - [Authentication](#authentication) - - [Future Work](#future-work-4) - - [Alternatives](#alternatives-5) - - [Observability](#observability) - - [Future Work](#future-work-5) - - [Alternatives](#alternatives-6) - - [Proxy Settings](#proxy-settings) - - [Future Work](#future-work-6) - - [Alternatives](#alternatives-7) - - [Testing](#testing) - - [Security Considerations](#security-considerations) - - [Alternatives Considered](#alternatives-considered) - - [References](#references) - +- [Goals](#goals) +- [Non-Goals](#non-goals) +- [Gateway API Extensions](#gateway-api-extensions) + - [GatewayClass Parameters Ref](#gatewayclass-parameters-ref) + - [Issues with `parametersRef`](#issues-with-parametersref) + - [Infrastructure API](#infrastructure-api) + - [TLS Options](#tls-options) + - [Filters](#filters) + - [BackendRef](#backendref) + - [Policy](#policy) + - [Direct Policy Attachment](#direct-policy-attachment) + - [Inherited Policy Attachment](#inherited-policy-attachment) + - [Hierarchy](#hierarchy) + - [Direct or Indirect?](#direct-or-indirect) + - [Challenges of Policy Attachment](#challenges-of-policy-attachment) +- [Prioritized NGINX Features](#prioritized-nginx-features) + - [High-Priority Features](#high-priority-features) + - [Medium-Priority Features](#medium-priority-features) + - [Low-Priority Features](#low-priority-features) + - [Features with Active Gateway API Enhancement Proposals](#features-with-active-gateway-api-enhancement-proposals) +- [Grouping the Features](#grouping-the-features) +- [API](#api) + - [Gateway Settings](#gateway-settings) + - [Future Work](#future-work) + - [Alternatives](#alternatives) + - [Response Modification](#response-modification) + - [Future Work](#future-work-1) + - [Alternatives](#alternatives-1) + - [TLS Settings](#tls-settings) + - [Future Work](#future-work-2) + - [Alternatives](#alternatives-2) + - [Client Settings](#client-settings) + - [Future Work](#future-work-3) + - [Alternatives](#alternatives-3) + - [Upstream Settings](#upstream-settings) + - [Alternatives](#alternatives-4) + - [Authentication](#authentication) + - [Future Work](#future-work-4) + - [Alternatives](#alternatives-5) + - [Observability](#observability) + - [Future Work](#future-work-5) + - [Alternatives](#alternatives-6) + - [Proxy Settings](#proxy-settings) + - [Future Work](#future-work-6) + - [Alternatives](#alternatives-7) +- [Testing](#testing) +- [Security Considerations](#security-considerations) +- [Alternatives Considered](#alternatives-considered) +- [References](#references) + + ## Goals diff --git a/tests/README.md b/tests/README.md index c53a66edfc..8d58a7adb2 100644 --- a/tests/README.md +++ b/tests/README.md @@ -7,6 +7,8 @@ This directory contains the tests for NGINX Gateway Fabric. The tests are divide 1. Conformance Testing. This is to ensure that the NGINX Gateway Fabric conforms to the Gateway API specification. 2. System Testing. This is to ensure that the NGINX Gateway Fabric works as expected in a real system. + + ## Table of Contents - [Prerequisites](#prerequisites) @@ -15,24 +17,27 @@ This directory contains the tests for NGINX Gateway Fabric. The tests are divide - [Step 2 - Build and Load Images](#step-2---build-and-load-images) - [Conformance Testing](#conformance-testing) - [Step 1 - Install NGINX Gateway Fabric to configured kind cluster](#step-1---install-nginx-gateway-fabric-to-configured-kind-cluster) - - [_Option 1_ Build and install NGINX Gateway Fabric from local to configured kind cluster](#option-1-build-and-install-nginx-gateway-fabric-from-local-to-configured-kind-cluster) - - [_Option 2_ Install NGINX Gateway Fabric from local already built image to configured kind cluster](#option-2-install-nginx-gateway-fabric-from-local-already-built-image-to-configured-kind-cluster) - - [_Option 3_ Install NGINX Gateway Fabric from edge to configured kind cluster](#option-3-install-nginx-gateway-fabric-from-edge-to-configured-kind-cluster) + - [Option 1 - Build and install NGINX Gateway Fabric from local to configured kind cluster](#option-1---build-and-install-nginx-gateway-fabric-from-local-to-configured-kind-cluster) + - [Option 2 - Install NGINX Gateway Fabric from local already built image to configured kind cluster](#option-2---install-nginx-gateway-fabric-from-local-already-built-image-to-configured-kind-cluster) + - [Option 3 - Install NGINX Gateway Fabric from edge to configured kind cluster](#option-3---install-nginx-gateway-fabric-from-edge-to-configured-kind-cluster) - [Step 2 - Build conformance test runner image](#step-2---build-conformance-test-runner-image) - [Step 3 - Run Gateway conformance tests](#step-3---run-gateway-conformance-tests) - [Step 4 - Cleanup the conformance test fixtures and uninstall NGINX Gateway Fabric](#step-4---cleanup-the-conformance-test-fixtures-and-uninstall-nginx-gateway-fabric) - [Step 5 - Revert changes to Go modules](#step-5---revert-changes-to-go-modules) - [Step 6 - Delete kind cluster](#step-6---delete-kind-cluster) - [System Testing](#system-testing) + - [Logging in tests](#logging-in-tests) - [Step 1 - Run the tests](#step-1---run-the-tests) - [1a - Run the functional tests locally](#1a---run-the-functional-tests-locally) - [1b - Run the tests on a GKE cluster from a GCP VM](#1b---run-the-tests-on-a-gke-cluster-from-a-gcp-vm) - - [Functional Tests](#functional-tests) - - [NFR tests](#nfr-tests) - - [Longevity testing](#longevity-testing) + - [Functional Tests](#functional-tests) + - [NFR tests](#nfr-tests) + - [Longevity testing](#longevity-testing) - [Common test amendments](#common-test-amendments) - [Step 2 - Cleanup](#step-2---cleanup) + + ## Prerequisites - Kubernetes cluster. @@ -131,7 +136,7 @@ TELEMETRY_ENDPOINT=otel-collector-opentelemetry-collector.collector.svc.cluster. export ENABLE_EXPERIMENTAL=true ``` -#### _Option 1_ Build and install NGINX Gateway Fabric from local to configured kind cluster +#### Option 1 - Build and install NGINX Gateway Fabric from local to configured kind cluster ```makefile make install-ngf-local-build @@ -143,7 +148,7 @@ Or, to install NGF with NGINX Plus enabled (NGINX Plus cert and key must exist i make install-ngf-local-build-with-plus ``` -#### _Option 2_ Install NGINX Gateway Fabric from local already built image to configured kind cluster +#### Option 2 - Install NGINX Gateway Fabric from local already built image to configured kind cluster You can optionally skip the actual _build_ step. @@ -169,7 +174,7 @@ Or, if you are building the NGINX Plus image: make update-ngf-manifest-with-plus PREFIX= TAG= ``` -#### _Option 3_ Install NGINX Gateway Fabric from edge to configured kind cluster +#### Option 3 - Install NGINX Gateway Fabric from edge to configured kind cluster You can also skip the build NGF image step and prepare the environment to instead use the `edge` image. Note that this option does not currently support installing with NGINX Plus enabled. @@ -424,7 +429,7 @@ XIt("runs some test", func(){ For more information of filtering specs, see [the docs here](https://onsi.github.io/ginkgo/#filtering-specs). -## Step 2 - Cleanup +### Step 2 - Cleanup 1. Delete kind cluster, if required