Merge branch 'deepmap:master' into 970-strict-response-type-alias

.github/workflows/ci.yml

@@ -8,24 +8,24 @@ jobs:
       fail-fast: false
       # perform matrix testing to give us an earlier insight into issues with different versions of supported major versions of Go
       matrix:
-        # strategy is used to allow us to pin to a specific Go version, or use the version available in our `go.mod`
-        strategy: ['go-version']
-        version: [1.21]
-        include:
-          # pick up the Go version from the `go.mod`
-          - strategy: 'go-version-file'
-            version: 'go.mod'
+        version:
+        - "1.20"
+        - "1.21"
+        - "1.22"
     steps:
       - name: Check out source code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Set up Go
-        uses: actions/setup-go@v3
+        uses: actions/setup-go@v5
         with:
-          ${{ matrix.strategy }}: ${{ matrix.version }}
+          go-version: ${{ matrix.version }}
 
       - name: Test
         run: make test
+        env:
+          # A combination of our GitHub Actions setup, with the Go toolchain, leads to inconsistencies in calling `go env`, in particular with Go 1.21, where having (the default) `GOTOOLCHAIN=auto` results in build failures
+          GOTOOLCHAIN: local
 
       - name: Build
         run: go build ./cmd/oapi-codegen

.github/workflows/generate.yml

@@ -8,24 +8,24 @@ jobs:
       fail-fast: false
       # perform matrix testing to give us an earlier insight into issues with different versions of supported major versions of Go
       matrix:
-        # strategy is used to allow us to pin to a specific Go version, or use the version available in our `go.mod`
-        strategy: ['go-version']
-        version: [1.21]
-        include:
-          # pick up the Go version from the `go.mod`
-          - strategy: 'go-version-file'
-            version: 'go.mod'
+        version:
+        - "1.20"
+        - "1.21"
+        - "1.22"
     steps:
       - name: Check out source code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Set up Go
-        uses: actions/setup-go@v3
+        uses: actions/setup-go@v5
         with:
-          ${{ matrix.strategy }}: ${{ matrix.version }}
+          go-version: ${{ matrix.version }}
 
       - name: Run `make generate`
         run: make generate
+        env:
+          # A combination of our GitHub Actions setup, with the Go toolchain, leads to inconsistencies in calling `go env`, in particular with Go 1.21, where having (the default) `GOTOOLCHAIN=auto` results in build failures
+          GOTOOLCHAIN: local
 
       - name: Check for no untracked files
         run: git status && git diff-index --exit-code -p HEAD --

.github/workflows/lint.yml

@@ -8,21 +8,21 @@ jobs:
       fail-fast: false
       # perform matrix testing to give us an earlier insight into issues with different versions of supported major versions of Go
       matrix:
-        # strategy is used to allow us to pin to a specific Go version, or use the version available in our `go.mod`
-        strategy: ['go-version']
-        version: [1.21]
-        include:
-          # pick up the Go version from the `go.mod`
-          - strategy: 'go-version-file'
-            version: 'go.mod'
+        version:
+        - "1.20"
+        - "1.21"
+        - "1.22"
     steps:
       - name: Check out source code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Set up Go
-        uses: actions/setup-go@v3
+        uses: actions/setup-go@v5
         with:
-          ${{ matrix.strategy }}: ${{ matrix.version }}
+          go-version: ${{ matrix.version }}
 
       - name: Run `make lint-ci`
         run: make lint-ci
+        env:
+          # A combination of our GitHub Actions setup, with the Go toolchain, leads to inconsistencies in calling `go env`, in particular with Go 1.21, where having (the default) `GOTOOLCHAIN=auto` results in build failures
+          GOTOOLCHAIN: local

.github/workflows/release-drafter.yml

@@ -16,7 +16,7 @@ jobs:
       pull-requests: write
     runs-on: ubuntu-latest
     steps:
-      - uses: release-drafter/release-drafter@v5
+      - uses: release-drafter/release-drafter@v6
         with:
           name: next
           tag: next

.github/workflows/tidy.yml

@@ -8,24 +8,24 @@ jobs:
       fail-fast: false
       # perform matrix testing to give us an earlier insight into issues with different versions of supported major versions of Go
       matrix:
-        # strategy is used to allow us to pin to a specific Go version, or use the version available in our `go.mod`
-        strategy: ['go-version']
-        version: [1.21]
-        include:
-          # pick up the Go version from the `go.mod`
-          - strategy: 'go-version-file'
-            version: 'go.mod'
+        version:
+        - "1.20"
+        - "1.21"
+        - "1.22"
     steps:
       - name: Check out source code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Set up Go
-        uses: actions/setup-go@v3
+        uses: actions/setup-go@v5
         with:
-          ${{ matrix.strategy }}: ${{ matrix.version }}
+          go-version: ${{ matrix.version }}
 
       - name: Install `tidied`
         run: go install gitlab.com/jamietanna/tidied@latest
 
       - name: Check for no untracked files
-        run: git ls-files go.mod '**/*go.mod' -z | xargs -0 -I{} bash -xc 'cd $(dirname {}) && tidied -verbose'
+        run: make tidy-ci
+        env:
+          # A combination of our GitHub Actions setup, with the Go toolchain, leads to inconsistencies in calling `go env`, in particular with Go 1.21, where having (the default) `GOTOOLCHAIN=auto` results in build failures
+          GOTOOLCHAIN: local

CONTRIBUTING.md

@@ -0,0 +1,96 @@
+## Contributing
+
+If you're interested in contributing to `oapi-codegen`, the first thing we have to say is thank you! We'd like to extend our gratitude to anyone who takes the time to improve this project.
+
+`oapi-codegen` is being actively maintained, however the two people who do so are very busy, and can only set aside time for this project every once in a while, so our release cadence is slow and conservative.
+
+> [!NOTE]
+> We're actively considering what needs to change to make `oapi-codegen` more sustainable, and hope that we can share soon some options.
+
+This guide is a starting point, and we'll absolutely improve it on an ongoing basis. We've managed to go ~4 years without a substantial guide like this - sometimes to the detriment of contributors - and would love to keep improving this guide, and the project, for the best of the community.
+
+### When may we not change things?
+
+Generating code which others depend on, which is based on something as complex as OpenAPI is fraught with many edge cases, and we prefer to leave things as they are if there is a reasonable workaround.
+
+We'll try to avoid adding too much noise into generated code, or introduce breaking changes (as per SemVer). See also "Backwards compatibility" in the README.
+
+### Raising a bug
+
+If you believe you have encountered a bug, please raise an issue.
+
+> [!TIP]
+> Please follow the [minimal reproductions](#minimal-reproductions) documentation to improve our ability to support triaging
+
+This may get converted into a feature request if we don't deem it a bug, but a missing feature.
+
+### Asking a question
+
+We'd prefer that questions about "how do I use (this feature)?" or "what do the community think about ...?" get asked using [GitHub Discussions](https://github.com/deepmap/oapi-codegen/discussions) which allow the community to answer them more easily.
+
+### Making changes that tweak generated code
+
+If you are making changes to the codebase that affects the code that gets generated, you will need to make sure that you have regenerated any generated test cases in the codebase using `make generate`.
+
+These generated test cases and examples provide a means to not only validate the functionality, but as they are checked in to source code, allow us to see if there are any subtle issues or breaking changes.
+
+> [!NOTE]
+> Significant changes to generated code are likely to be merged, especially in cases where there would be a breaking change that all consumers would have to respond to i.e. renaming a function or changing the function signature.
+>
+> However, if we can make this an opt-in feature (using the `output-options` configuration object) then that would be our preference.
+
+### Feature enhancements
+
+It's great that you would like to improve `oapi-codegen` and add new futures.
+
+We would prefer there be an issue raised for a feature request first, especially if it may be a duplicate of existing requests. However, sometimes that isn't possible - or takes longer than the code changes required - so it can be excused.
+
+Features that amend the way existing codegen works should - ideally - be behind an opt-in feature flag using the `output-options` configuration object.
+
+### Minimal reproductions
+
+> [!TIP]
+> The minimal reproductions for bugs may get taken into the codebase (licensed under `Apache-2.0`) as a test-case for future regression testing
+
+When raising a bug report, or asking a question about functionality, it's super helpful if you can share:
+
+- The version of `oapi-codegen` you're using
+  - You _may_ get asked to update to a later - or latest - version, to see if the issue persists
+- The YAML configuration file you're using
+- The OpenAPI spec you're using
+  - However, we would prefer it only be the _absolute minimum_ specification, to limit the noise while trying to debug the issue, and to reduce information exposure from internal API development
+- What problem you're seeing
+- What the expected behaviour is
+- What version of Go you're using
+
+> [!CAUTION]
+> When sharing a minimal reproduction, please be aware of sharing any internal information about the APIs you're developing, or any sensitive Intellectual Property.
+
+### Before you raise a PR
+
+> [!NOTE]
+> Please raise PRs from a branch that isn't the `master` or `main` branch on your repo. This generally means that as maintainers, we can't push changes to the branch directly.
+
+Before you send the PR, please run the following commands locally:
+
+```sh
+make tidy
+make test
+make generate
+make lint
+```
+
+It is important to use the `make` tasks due to the way we're (ab)using the Go module system to split the project into multiple modules to reduce our dependency bloat in the main module.
+
+These are also run in GitHub Actions, across a number of Go releases.
+
+It's recommended to raise a draft PR first, so you can get feedback on the PR from GitHub, and review your own changes, before getting the attention of a maintainer.
+
+### "Should I @-mention the maintainers on an issue"
+
+Please try to avoid pinging the maintainers in an issue, Pull Request, or discussion.
+
+> [!NOTE]
+> We're actively considering what needs to change to make `oapi-codegen` more sustainable, and hope that we can share soon some options.
+
+The project is run on a volunteer basis, and as such, tagging us on issues - especially if you've just raised them - is largely unhelpful. We monitor the issues and work to triage them as best we can with the time we have allocated for it.

Makefile

@@ -6,27 +6,47 @@ help:
 	@echo "Targets:"
 	@echo "    generate:    regenerate all generated files"
 	@echo "    test:        run all tests"
-	@echo "    gin_example  generate gin example server code"
 	@echo "    tidy         tidy go mod"
+	@echo "    lint         lint the project"
 
 $(GOBIN)/golangci-lint:
-	curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(GOBIN) v1.54.0
+	curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(GOBIN) v1.58.0
 
 .PHONY: tools
 tools: $(GOBIN)/golangci-lint
 
 lint: tools
-	git ls-files go.mod '**/*go.mod' -z | xargs -0 -I{} bash -xc 'cd $$(dirname {}) && $(GOBIN)/golangci-lint run ./...'
+	# run the root module explicitly, to prevent recursive calls by re-invoking `make ...` top-level
+	$(GOBIN)/golangci-lint run ./...
+	# then, for all child modules, use a module-managed `Makefile`
+	git ls-files '**/*go.mod' -z | xargs -0 -I{} bash -xc 'cd $$(dirname {}) && env GOBIN=$(GOBIN) make lint'
 
 lint-ci: tools
-	git ls-files go.mod '**/*go.mod' -z | xargs -0 -I{} bash -xc 'cd $$(dirname {}) && $(GOBIN)/golangci-lint run ./... --out-format=github-actions --timeout=5m'
+	# for the root module, explicitly run the step, to prevent recursive calls
+	$(GOBIN)/golangci-lint run ./... --out-format=github-actions --timeout=5m
+	# then, for all child modules, use a module-managed `Makefile`
+	git ls-files '**/*go.mod' -z | xargs -0 -I{} bash -xc 'cd $$(dirname {}) && env GOBIN=$(GOBIN) make lint-ci'
 
 generate:
-	git ls-files go.mod '**/*go.mod' -z | xargs -0 -I{} bash -xc 'cd $$(dirname {}) && go generate ./...'
+	# for the root module, explicitly run the step, to prevent recursive calls
+	go generate ./...
+	# then, for all child modules, use a module-managed `Makefile`
+	git ls-files '**/*go.mod' -z | xargs -0 -I{} bash -xc 'cd $$(dirname {}) && make generate'
 
 test:
-	git ls-files go.mod '**/*go.mod' -z | xargs -0 -I{} bash -xc 'cd $$(dirname {}) && go test -cover ./...'
+	# for the root module, explicitly run the step, to prevent recursive calls
+	go test -cover ./...
+	# then, for all child modules, use a module-managed `Makefile`
+	git ls-files '**/*go.mod' -z | xargs -0 -I{} bash -xc 'cd $$(dirname {}) && make test'
 
 tidy:
-	@echo "tidy..."
-	git ls-files go.mod '**/*go.mod' -z | xargs -0 -I{} bash -xc 'cd $$(dirname {}) && go mod tidy'
+	# for the root module, explicitly run the step, to prevent recursive calls
+	go mod tidy
+	# then, for all child modules, use a module-managed `Makefile`
+	git ls-files '**/*go.mod' -z | xargs -0 -I{} bash -xc 'cd $$(dirname {}) && make tidy'
+
+tidy-ci:
+	# for the root module, explicitly run the step, to prevent recursive calls
+	tidied -verbose
+	# then, for all child modules, use a module-managed `Makefile`
+	git ls-files '**/*go.mod' -z | xargs -0 -I{} bash -xc 'cd $$(dirname {}) && make tidy-ci'