From 4b8213d8950a3fa29f01045b62c4ea958be28292 Mon Sep 17 00:00:00 2001 From: Frederic BIDON Date: Sat, 23 Aug 2025 19:50:39 +0200 Subject: [PATCH 01/28] initialized standard github actions workflows Signed-off-by: Frederic BIDON --- .github/CONTRIBUTING.md | 117 +++++++++++++++++++++++++++++++ .github/dependabot.yaml | 52 ++++++++++++++ .github/workflows/auto-merge.yml | 45 ++++++++++++ .github/workflows/go-test.yml | 51 ++++++++++++++ CODE_OF_CONDUCT.md | 74 +++++++++++++++++++ README.md | 8 ++- 6 files changed, 346 insertions(+), 1 deletion(-) create mode 100644 .github/CONTRIBUTING.md create mode 100644 .github/dependabot.yaml create mode 100644 .github/workflows/auto-merge.yml create mode 100644 .github/workflows/go-test.yml create mode 100644 CODE_OF_CONDUCT.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..7dea424 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,117 @@ +## Contribution Guidelines + +### Pull requests are always welcome + +We are always thrilled to receive pull requests, and do our best to +process them as fast as possible. Not sure if that typo is worth a pull +request? Do it! We will appreciate it. + +If your pull request is not accepted on the first try, don't be +discouraged! If there's a problem with the implementation, hopefully you +received feedback on what to improve. + +We're trying very hard to keep go-swagger lean and focused. We don't want it +to do everything for everybody. This means that we might decide against +incorporating a new feature. However, there might be a way to implement +that feature *on top of* go-swagger. + + +### Conventions + +Fork the repo and make changes on your fork in a feature branch: + +- If it's a bugfix branch, name it XXX-something where XXX is the number of the + issue +- If it's a feature branch, create an enhancement issue to announce your + intentions, and name it XXX-something where XXX is the number of the issue. + +Submit unit tests for your changes. Go has a great test framework built in; use +it! Take a look at existing tests for inspiration. Run the full test suite on +your branch before submitting a pull request. + +Update the documentation when creating or modifying features. Test +your documentation changes for clarity, concision, and correctness, as +well as a clean documentation build. See ``docs/README.md`` for more +information on building the docs and how docs get released. + +Write clean code. Universally formatted code promotes ease of writing, reading, +and maintenance. Always run `gofmt -s -w file.go` on each changed file before +committing your changes. Most editors have plugins that do this automatically. + +Pull requests descriptions should be as clear as possible and include a +reference to all the issues that they address. + +Pull requests must not contain commits from other users or branches. + +Commit messages must start with a capitalized and short summary (max. 50 +chars) written in the imperative, followed by an optional, more detailed +explanatory text which is separated from the summary by an empty line. + +Code review comments may be added to your pull request. Discuss, then make the +suggested modifications and push additional commits to your feature branch. Be +sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you +comment. + +Before the pull request is merged, make sure that you squash your commits into +logical units of work using `git rebase -i` and `git push -f`. After every +commit the test suite should be passing. Include documentation changes in the +same commit so that a revert would remove all traces of the feature or fix. + +Commits that fix or close an issue should include a reference like `Closes #XXX` +or `Fixes #XXX`, which will automatically close the issue when merged. + +### Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](http://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign off when creating the git commit via `git commit -s`. diff --git a/.github/dependabot.yaml b/.github/dependabot.yaml new file mode 100644 index 0000000..9ce426e --- /dev/null +++ b/.github/dependabot.yaml @@ -0,0 +1,52 @@ +version: 2 +updates: + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + day: "friday" + open-pull-requests-limit: 2 # <- default is 5 + groups: # <- group all github actions updates in a single PR + # 1. development-dependencies are auto-merged + development-dependencies: + patterns: + - '*' + + - package-ecosystem: "gomod" + # We define 4 groups of dependencies to regroup update pull requests: + # - development (e.g. test dependencies) + # - go-openapi updates + # - golang.org (e.g. golang.org/x/... packages) + # - other dependencies (direct or indirect) + # + # * All groups are checked once a week and each produce at most 1 PR. + # * All dependabot PRs are auto-approved + # + # Auto-merging policy, when requirements are met: + # 1. development-dependencies are auto-merged + # 2. golang.org-dependencies are auto-merged + # 3. go-openapi patch updates are auto-merged. Minor/major version updates require a manual merge. + # 4. other dependencies require a manual merge + directory: "/" + schedule: + interval: "weekly" + day: "friday" + open-pull-requests-limit: 4 + groups: + development-dependencies: + patterns: + - "github.com/stretchr/testify" + + golang-org-dependencies: + patterns: + - "golang.org/*" + + go-openapi-dependencies: + patterns: + - "github.com/go-openapi/*" + + other-dependencies: + exclude-patterns: + - "github.com/go-openapi/*" + - "github.com/stretchr/testify" + - "golang.org/*" diff --git a/.github/workflows/auto-merge.yml b/.github/workflows/auto-merge.yml new file mode 100644 index 0000000..d1b2d9c --- /dev/null +++ b/.github/workflows/auto-merge.yml @@ -0,0 +1,45 @@ +name: Dependabot auto-merge + +on: + workflow_call: + +permissions: + contents: write + pull-requests: write + +jobs: + dependabot: + runs-on: ubuntu-latest + if: github.event.pull_request.user.login == 'dependabot[bot]' + steps: + - name: Dependabot metadata + id: metadata + uses: dependabot/fetch-metadata@v2 + + - name: Auto-approve all dependabot PRs + run: gh pr review --approve "$PR_URL" + env: + PR_URL: ${{github.event.pull_request.html_url}} + GH_TOKEN: ${{secrets.GITHUB_TOKEN}} + + - name: Auto-merge dependabot PRs for development dependencies + if: contains(steps.metadata.outputs.dependency-group, 'development-dependencies') + run: gh pr merge --auto --rebase "$PR_URL" + env: + PR_URL: ${{github.event.pull_request.html_url}} + GH_TOKEN: ${{secrets.GITHUB_TOKEN}} + + - name: Auto-merge dependabot PRs for go-openapi patches + if: contains(steps.metadata.outputs.dependency-group, 'go-openapi-dependencies') && (steps.metadata.outputs.update-type == 'version-update:semver-minor' || steps.metadata.outputs.update-type == 'version-update:semver-patch') + run: gh pr merge --auto --rebase "$PR_URL" + env: + PR_URL: ${{github.event.pull_request.html_url}} + GH_TOKEN: ${{secrets.GITHUB_TOKEN}} + + - name: Auto-merge dependabot PRs for golang.org updates + if: contains(steps.metadata.outputs.dependency-group, 'golang-org-dependencies') + run: gh pr merge --auto --rebase "$PR_URL" + env: + PR_URL: ${{github.event.pull_request.html_url}} + GH_TOKEN: ${{secrets.GITHUB_TOKEN}} + diff --git a/.github/workflows/go-test.yml b/.github/workflows/go-test.yml new file mode 100644 index 0000000..570ccc4 --- /dev/null +++ b/.github/workflows/go-test.yml @@ -0,0 +1,51 @@ +name: go test + +on: + workflow_call: + +jobs: + lint: + name: Lint + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v5 + - uses: actions/setup-go@v5 + with: + go-version: stable + check-latest: true + cache: true + - name: golangci-lint + uses: golangci/golangci-lint-action@v8 + with: + version: latest + only-new-issues: true + skip-cache: true + + test: + name: Unit tests + runs-on: ${{ matrix.os }} + + strategy: + matrix: + os: [ ubuntu-latest, macos-latest, windows-latest ] + go_version: ['oldstable', 'stable' ] + + steps: + - uses: actions/setup-go@v5 + with: + go-version: '${{ matrix.go_version }}' + check-latest: true + cache: true + + - uses: actions/checkout@v5 + - name: Run unit tests + shell: bash + run: go test -v -race -coverprofile="coverage-${{ matrix.os }}.${{ matrix.go_version }}.out" -covermode=atomic -coverpkg=$(go list)/... ./... + + - name: Upload coverage to codecov + uses: codecov/codecov-action@v5 + with: + files: './coverage-${{ matrix.os }}.${{ matrix.go_version }}.out' + flags: '${{ matrix.go_version }}-${{ matrix.os }}' + fail_ci_if_error: false + verbose: true diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..9322b06 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,74 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at ivan+abuse@flanders.co.nz. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ diff --git a/README.md b/README.md index 91b6f26..52aec57 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,8 @@ # ci-workflows -Common CI workflows and setup for go-openapi repos + +Common CI workflows and setup for go-openapi repos. + +* shared github action workflows +* shared dependabot config + +NOTE: at this moment, it is difficult to share the golangci-lint config, so that one is not shared yet. From 2f8a2645e1726ac19884bb53713ad206170f5ea8 Mon Sep 17 00:00:00 2001 From: Frederic BIDON Date: Sat, 23 Aug 2025 22:08:49 +0200 Subject: [PATCH 02/28] renamed jobs Signed-off-by: Frederic BIDON --- .github/workflows/go-test.yml | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/.github/workflows/go-test.yml b/.github/workflows/go-test.yml index 570ccc4..b806c4e 100644 --- a/.github/workflows/go-test.yml +++ b/.github/workflows/go-test.yml @@ -21,7 +21,7 @@ jobs: only-new-issues: true skip-cache: true - test: + unit_test: name: Unit tests runs-on: ${{ matrix.os }} @@ -49,3 +49,12 @@ jobs: flags: '${{ matrix.go_version }}-${{ matrix.os }}' fail_ci_if_error: false verbose: true + + all_tests: + needs: [ test ] + name: All tests + runs-on: ubuntu-latest + steps: + - name: Tests complete + run: | + echo "All tests completed" From bac60e175f8fb5444cfef1178cee34e6fc53a629 Mon Sep 17 00:00:00 2001 From: Frederic BIDON Date: Sat, 23 Aug 2025 22:15:59 +0200 Subject: [PATCH 03/28] fixup job dependencies Signed-off-by: Frederic BIDON --- .github/workflows/go-test.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/go-test.yml b/.github/workflows/go-test.yml index b806c4e..4fba194 100644 --- a/.github/workflows/go-test.yml +++ b/.github/workflows/go-test.yml @@ -21,7 +21,7 @@ jobs: only-new-issues: true skip-cache: true - unit_test: + unit_tests: name: Unit tests runs-on: ${{ matrix.os }} @@ -51,7 +51,7 @@ jobs: verbose: true all_tests: - needs: [ test ] + needs: [ unit_tests ] name: All tests runs-on: ubuntu-latest steps: From 2ec60ace72cd7a52e8d84e9823bc537778e52151 Mon Sep 17 00:00:00 2001 From: fredbi Date: Sun, 24 Aug 2025 15:43:11 +0200 Subject: [PATCH 04/28] ci: added sample packages to exercice CI pipelines (#1) * added local workflows that call the shared ones to test evolutions * added job summary to display in github action UI. * added sample app to run test * added future workplan to README Signed-off-by: Frederic BIDON --- .github/workflows/go-test.yml | 100 +++++++++++++++++++++++-- .github/workflows/local-auto-merge.yml | 15 ++++ .github/workflows/local-go-test.yml | 17 +++++ .golangci.yml | 75 +++++++++++++++++++ README.md | 27 +++++++ audit/README.md | 3 + doc/README.md | 3 + go.mod | 11 +++ go.sum | 10 +++ sample/pkg/pkg.go | 6 ++ sample/pkg/pkg_test.go | 11 +++ sample/sample.go | 6 ++ sample/sample_test.go | 19 +++++ 13 files changed, 297 insertions(+), 6 deletions(-) create mode 100644 .github/workflows/local-auto-merge.yml create mode 100644 .github/workflows/local-go-test.yml create mode 100644 .golangci.yml create mode 100644 audit/README.md create mode 100644 doc/README.md create mode 100644 go.mod create mode 100644 go.sum create mode 100644 sample/pkg/pkg.go create mode 100644 sample/pkg/pkg_test.go create mode 100644 sample/sample.go create mode 100644 sample/sample_test.go diff --git a/.github/workflows/go-test.yml b/.github/workflows/go-test.yml index 4fba194..2e3071a 100644 --- a/.github/workflows/go-test.yml +++ b/.github/workflows/go-test.yml @@ -6,6 +6,15 @@ on: jobs: lint: name: Lint + # description: | + # Lint uses golangci-lint github action and lints only changes from master. + # + # It will run on the latest go version. + # + # We rely on golangci-lint to automatically disable linters that do not apply to the minimum required go version + # currently defined in go.mod. + # + # At this moment, .golangci.yml configuration files are not shared: each repository must have its configuration. runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 @@ -19,11 +28,31 @@ jobs: with: version: latest only-new-issues: true - skip-cache: true + skip-cache: false + - name: Linting complete # <- report summary when we have good news to report + run: | + echo "### Your changes to the go code look good. 👍" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "> ℹī¸ INFO: we use [golangci-lint action](https://github.com/golangci/golangci-lint-action)" >> $GITHUB_STEP_SUMMARY + echo "> to lint any change to go code from master" >> $GITHUB_STEP_SUMMARY unit_tests: name: Unit tests + # description: | + # Run go unit tests run x6: linux, mac & windows on the 2 latest go versions. + # + # Run tests with the -race flag. + # + # Captures test coverage and uploads it to codecov.com. runs-on: ${{ matrix.os }} + outputs: + # NOTE(fredbi): as of Aug. 2025, there is no way to have github actions declare outputs dynamically + test_result_oldstable_ubuntu_latest: "${{ steps.goreport.outputs.test_result_oldstable_ubuntu_latest }}" + test_result_oldstable_macos_latest: "${{ steps.goreport.outputs.test_result_oldstable_macos_latest }}" + test_result_oldstable_windows_latest: "${{ steps.goreport.outputs.test_result_oldstable_windows_latest }}" + test_result_stable_ubuntu_latest: "${{ steps.goreport.outputs.test_result_stable_ubuntu_latest }}" + test_result_stable_macos_latest: "${{ steps.goreport.outputs.test_result_stable_macos_latest }}" + test_result_stable_windows_latest: "${{ steps.goreport.outputs.test_result_stable_windows_latest }}" strategy: matrix: @@ -35,12 +64,34 @@ jobs: with: go-version: '${{ matrix.go_version }}' check-latest: true - cache: true + cache: true # <- cache key is go.sum - uses: actions/checkout@v5 + - name: Run unit tests + # description: | + # runs unit tests with test coverage assuming that this repository contains only one module, + # with a go.mod located at the root. + id: gotest + shell: bash + run: | + go test -v \ + -race \ + -coverprofile="coverage-${{ matrix.os }}.${{ matrix.go_version }}.out" \ + -covermode=atomic \ + -coverpkg=$(go list ./... |paste -sd ",") \ + ./... + + - name: Report test + if: ${{ success() || failure() }} + id: goreport shell: bash - run: go test -v -race -coverprofile="coverage-${{ matrix.os }}.${{ matrix.go_version }}.out" -covermode=atomic -coverpkg=$(go list)/... ./... + run: | + icon="✅" + if [[ "${{ steps.gotest.outcome }}" != "success" ]] ; then + icon="đŸšĢ" + fi + echo "test_result_${{ matrix.go_version }}_$(echo "${{ matrix.os }}"|tr '-' '_')='| ${{ matrix.go_version }} | ${{ matrix.os }} | ${icon} ${{ steps.gotest.outcome }} |'" >> "$GITHUB_OUTPUT" - name: Upload coverage to codecov uses: codecov/codecov-action@v5 @@ -48,13 +99,50 @@ jobs: files: './coverage-${{ matrix.os }}.${{ matrix.go_version }}.out' flags: '${{ matrix.go_version }}-${{ matrix.os }}' fail_ci_if_error: false - verbose: true + verbose: false all_tests: - needs: [ unit_tests ] name: All tests + # description: | + # This job regroups all tests launched as a matrix, so we may define a branch protection rule + # just on that job rather than each matrix job independently. + needs: [ unit_tests ] # <- requires all unit_tests jobs to be successful. + env: + test_result: '${{ join(needs.unit_tests.outputs.*) }}' # <- this is a comma-separated list of quoted strings runs-on: ubuntu-latest steps: - name: Tests complete run: | - echo "All tests completed" + echo "### All tests completed. 👍" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "> ℹī¸ INFO: we run unit tests in 6 different configurations of OS and go version." >> $GITHUB_STEP_SUMMARY + echo "> At this moment, we don't run architecture-specific test runs" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "| go version | OS | Result |" >> $GITHUB_STEP_SUMMARY + echo "|------------|----|--------|" >> $GITHUB_STEP_SUMMARY + declare -a lines + eval "lines=($(echo $test_result|tr ',' ' '))" + for line in "${lines[@]}";do echo "${line}" ; done >> $GITHUB_STEP_SUMMARY + + some_failed_tests: + name: Some tests have failed + # description: | + # This job is only here to report a summary of failed tests in the github actions UI. + needs: [ unit_tests ] # <- requires all unit_tests jobs to be completed, but not all where successfull. + if: ${{ failure() }} + env: + test_result: '${{ join(needs.unit_tests.outputs.*) }}' + runs-on: ubuntu-latest + steps: + - name: Tests failed + run: | + echo "### Some tests have failed. đŸšĢ" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "> ℹī¸ INFO: testing halted on first encountered failure." >> $GITHUB_STEP_SUMMARY + echo "> Some configurations may not have been tested yet." >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "| go version | OS | Result |" >> $GITHUB_STEP_SUMMARY + echo "|------------|----|--------|" >> $GITHUB_STEP_SUMMARY + declare -a lines + eval "lines=($(echo $test_result|tr ',' ' '))" + for line in "${lines[@]}";do echo "${line}" ; done >> $GITHUB_STEP_SUMMARY diff --git a/.github/workflows/local-auto-merge.yml b/.github/workflows/local-auto-merge.yml new file mode 100644 index 0000000..4cbf332 --- /dev/null +++ b/.github/workflows/local-auto-merge.yml @@ -0,0 +1,15 @@ +name: Dependabot auto-merge + +# This workflow mimics how a go-openapi repo would typically invoke the common workflow. + +on: pull_request + + +permissions: + contents: write + pull-requests: write + +jobs: + dependabot: + uses: ./.github/workflows/auto-merge.yml + secrets: inherit diff --git a/.github/workflows/local-go-test.yml b/.github/workflows/local-go-test.yml new file mode 100644 index 0000000..259a504 --- /dev/null +++ b/.github/workflows/local-go-test.yml @@ -0,0 +1,17 @@ +name: go test + +# This workflow mimics how a go-openapi repo would typically invoke the common workflow. + +on: + push: + tags: + - v* + branches: + - master + + pull_request: + +jobs: + test: + uses: ./.github/workflows/go-test.yml + secrets: inherit diff --git a/.golangci.yml b/.golangci.yml new file mode 100644 index 0000000..568ce16 --- /dev/null +++ b/.golangci.yml @@ -0,0 +1,75 @@ +version: "2" +linters: + default: all + disable: + - cyclop + - depguard + - errchkjson + - errorlint + - exhaustruct + - forcetypeassert + - funlen + - gochecknoglobals + - gochecknoinits + - gocognit + - godot + - godox + - gosmopolitan + - inamedparam + - intrange # disabled while < go1.22 + - ireturn + - lll + - musttag + - nestif + - nlreturn + - nonamedreturns + - noinlineerr + - paralleltest + - recvcheck + - testpackage + - thelper + - tparallel + - unparam + - varnamelen + - whitespace + - wrapcheck + - wsl + - wsl_v5 + settings: + dupl: + threshold: 200 + goconst: + min-len: 2 + min-occurrences: 3 + gocyclo: + min-complexity: 45 + exclusions: + generated: lax + presets: + - comments + - common-false-positives + - legacy + - std-error-handling + paths: + - third_party$ + - builtin$ + - examples$ +formatters: + enable: + - gofmt + - goimports + exclusions: + generated: lax + paths: + - third_party$ + - builtin$ + - examples$ +issues: + # Maximum issues count per one linter. + # Set to 0 to disable. + # Default: 50 + max-issues-per-linter: 0 + # Maximum count of issues with the same text. + # Set to 0 to disable. + # Default: 3 + max-same-issues: 0 diff --git a/README.md b/README.md index 52aec57..0d268cd 100644 --- a/README.md +++ b/README.md @@ -6,3 +6,30 @@ Common CI workflows and setup for go-openapi repos. * shared dependabot config NOTE: at this moment, it is difficult to share the golangci-lint config, so that one is not shared yet. + +## Motivation + +It took a while, but we eventually managed to align all checks, tests and dependabot rules declared in the +family of go-openapi repos. + +Now we'd like to be able to maintain, enrich and improve these checks without worrying too much about +the burden to replicate it about a dozen times. + +## Contemplated enhancements + +* [x] enrich github actions UI with a job summary +* [] version common workflows, so we can limit the impact of a change +* [] verify that go.sum cache for tests works (should be enabled) +* [] share mono repo workflows (see github.com/go-openapi/swag/.github/workflows) +* [] manage somehow to share golangci config (with local merge) +* [] manage somehow to share / replicate dependabot config +* [] add markdown linting for docs +* [] golangci-lint: check valid PR comments etc +* [] add spellcheck for docs (and code?) +* [] use non-blocking, scheduled, proactive full linting to check for the impact of new linters, new go versions etc +* [] (possibility) take over hugo & doc gen part from go-swagger +* [] (possibility) take over release part from go-swagger +* [] produce hugo github page with all latest tagged versions (incl. mono repo) +* [] add bot to filter PRs, issues +* [] check with github API that all repo settings (branch protection rules, etc) are identical +* [] comment PRs and issues diff --git a/audit/README.md b/audit/README.md new file mode 100644 index 0000000..eb5eadf --- /dev/null +++ b/audit/README.md @@ -0,0 +1,3 @@ +# Audit + +Audit of github repos to check for inconsistencies. diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 0000000..19577ee --- /dev/null +++ b/doc/README.md @@ -0,0 +1,3 @@ +# doc + +Documentation check and generation tools. diff --git a/go.mod b/go.mod new file mode 100644 index 0000000..51c159d --- /dev/null +++ b/go.mod @@ -0,0 +1,11 @@ +module github.com/go-openapi/ci-workflows + +go 1.24.2 + +require github.com/stretchr/testify v1.10.0 + +require ( + github.com/davecgh/go-spew v1.1.1 // indirect + github.com/pmezard/go-difflib v1.0.0 // indirect + gopkg.in/yaml.v3 v3.0.1 // indirect +) diff --git a/go.sum b/go.sum new file mode 100644 index 0000000..713a0b4 --- /dev/null +++ b/go.sum @@ -0,0 +1,10 @@ +github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= +github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= +github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= +github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA= +github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY= +gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM= +gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= +gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= +gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= diff --git a/sample/pkg/pkg.go b/sample/pkg/pkg.go new file mode 100644 index 0000000..6a54077 --- /dev/null +++ b/sample/pkg/pkg.go @@ -0,0 +1,6 @@ +// Package pkg exercises CI pipelines. +package pkg + +func Pkg() string { + return "" +} diff --git a/sample/pkg/pkg_test.go b/sample/pkg/pkg_test.go new file mode 100644 index 0000000..6979d22 --- /dev/null +++ b/sample/pkg/pkg_test.go @@ -0,0 +1,11 @@ +package pkg + +import ( + "testing" + + "github.com/stretchr/testify/assert" +) + +func TestPkg(t *testing.T) { + assert.Empty(t, Pkg()) +} diff --git a/sample/sample.go b/sample/sample.go new file mode 100644 index 0000000..d38e9a3 --- /dev/null +++ b/sample/sample.go @@ -0,0 +1,6 @@ +// Package sample is used to exercise CI pipelines. +package sample + +func Sample() int { + return 1 +} diff --git a/sample/sample_test.go b/sample/sample_test.go new file mode 100644 index 0000000..b4f2063 --- /dev/null +++ b/sample/sample_test.go @@ -0,0 +1,19 @@ +package sample + +import ( + "testing" + + "github.com/stretchr/testify/require" +) + +func TestSample(t *testing.T) { + /* + if runtime.GOOS == "windows" { + require.Equal(t, 0, Sample()) // make the test fail on windows + + return + } + + */ + require.Equal(t, 1, Sample()) +} From 5dea777a350171a5d1b044fa91ff1f0868c29315 Mon Sep 17 00:00:00 2001 From: fredbi Date: Sun, 24 Aug 2025 19:01:03 +0200 Subject: [PATCH 05/28] feat(doc): added markdown linting (#4) Signed-off-by: Frederic BIDON --- .github/workflows/doc-update.yml | 159 +++++++++++++++++++++++++ .github/workflows/go-test.yml | 4 +- .github/workflows/local-doc-update.yml | 17 +++ README.md | 36 +++--- 4 files changed, 197 insertions(+), 19 deletions(-) create mode 100644 .github/workflows/doc-update.yml create mode 100644 .github/workflows/local-doc-update.yml diff --git a/.github/workflows/doc-update.yml b/.github/workflows/doc-update.yml new file mode 100644 index 0000000..f51d5c7 --- /dev/null +++ b/.github/workflows/doc-update.yml @@ -0,0 +1,159 @@ +name: doc update check + +on: + workflow_call: + +# TODO: +# * [] markdown lint +# * [] spell checker + +permissions: + pull-requests: write + contents: read + +env: + comment-title: Markdown linter + +jobs: + markdown-changed: + # description: | + # This performs a markdown lint whenever documentation files change + runs-on: ubuntu-latest + outputs: + proceed: ${{ steps.changed-markdown-files.outputs.any_changed }} + all_changed_files: ${{ steps.changed-markdown-files.outputs.all_changed_files }} + steps: + - uses: actions/checkout@v5 + with: + ref: ${{ github.event.pull_request.head.sha }} + + - name: Get changed markdown files + uses: tj-actions/changed-files@v46 + id: changed-markdown-files + with: + files: '**/*.md' + + - name: Notify + run: | + echo "::notice::Detected some changed markdown files" + echo "${{ steps.changed-markdown-files.outputs.all_changed_files }}" + + lint-markdown: + needs: markdown-changed + if: needs.markdown-changed.outputs.proceed == 'true' + runs-on: ubuntu-latest + env: + lintreport: './markdownlint-report.txt' + outputs: + proceed: ${{ steps.report-exists.outputs.proceed }} + report: ${{ steps.report-exists.outputs.report }} + + steps: + - name: Checkout Repo + uses: actions/checkout@v5 + with: + ref: ${{ github.event.pull_request.head.sha }} + #ref: "refs/pull/${{ github.event.number }}/merge" # it's okay to pull the user's changes: we just scan md's + + - name: Run markdown linter + continue-on-error: true + id: markdownlint + uses: docker://avtodev/markdown-lint:v1.5 + with: + config: ./.github/.markdownlint.yml + args: '${{ needs.markdown-changed.outputs.all_changed_files }}' + output: '${{ env.lintreport }}' + + - name: Find previous PR comment + if: steps.markdownlint.outcome == 'success' + uses: peter-evans/find-comment@v3 + id: findcomment + with: + issue-number: ${{ github.event.pull_request.number }} + body-includes: ${{ env.comment-title }} + direction: last + + - name: Comment on success + if: steps.markdownlint.outcome == 'success' + id: congrats + uses: peter-evans/create-or-update-comment@v4 + with: + issue-number: ${{ github.event.pull_request.number }} + comment-id: ${{ steps.findcomment.outputs.comment-id }} + reactions: hooray + reactions-edit-mode: replace + body: | + ### ${{ env.comment-title }} + + Markdown looks good to me. Congrats! + + - name: Check lint report exists + if: ${{ steps.markdownlint.outcome != 'success' && hashFiles(env.lintreport) != '' }} + id: report-exists + run: | + echo 'report<> $GITHUB_OUTPUT + cat ${{ env.lintreport }}|sed -e '$a\' >> $GITHUB_OUTPUT + echo 'EOF' >> $GITHUB_OUTPUT + + if [[ "$(cat ${{ env.lintreport }}|wc -l)" != "0" ]] ; then + echo "proceed=true" >> $GITHUB_OUTPUT + echo "::notice::Detected some linting issues with changed markdown" + cat ${{ env.lintreport }}|sed -e '$a\' + else + echo "proceed=false" >> $GITHUB_OUTPUT + echo "::notice::No linting issues with changed markdown" + fi + + - name: Other linter errors + if: ${{ steps.markdownlint.outcome != 'success' && hashFiles(env.lintreport) == '' }} + run: | + echo "::error::markdown linter encountered an error" + exit 1 + + pr-comment: + needs: lint-markdown + if: needs.lint-markdown.outputs.proceed == 'true' + runs-on: ubuntu-latest + + steps: + - name: Format PR comment + id: commentformatter + uses: skills/action-text-variables@v1 + with: + template-vars: | + text='${{ needs.lint-markdown.outputs.report }}' + template-text: | + ### ${{ env.comment-title }} + + Some markdown linting issues were detected in the modified .md files. + + Perhaps they were already there before your changes. + + This check is advisory only and not blocking. Please help us adopt a nice markdown style. + + Markdown formatting rules are documented [here](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md). +
+ {{ text }} + + - name: Find previous PR comment + uses: peter-evans/find-comment@v3 + id: findcomment + with: + issue-number: ${{ github.event.pull_request.number }} + body-includes: ${{ env.comment-title }} + direction: last + + - name: Create or update PR comment + uses: peter-evans/create-or-update-comment@v4 + with: + issue-number: ${{ github.event.pull_request.number }} + comment-id: ${{ steps.findcomment.outputs.comment-id }} + reactions: confused + reactions-edit-mode: replace + body: ${{ steps.commentformatter.outputs.updated-text }} + edit-mode: replace + + - name: Notify + run: | + echo "::notice::Commented pull request ${{ github.event.pull_request.number }}" + echo "::debug::${{ steps.commentformatter.outputs.updated-text }}" diff --git a/.github/workflows/go-test.yml b/.github/workflows/go-test.yml index 2e3071a..93b4a50 100644 --- a/.github/workflows/go-test.yml +++ b/.github/workflows/go-test.yml @@ -34,7 +34,7 @@ jobs: echo "### Your changes to the go code look good. 👍" >> $GITHUB_STEP_SUMMARY echo "" >> $GITHUB_STEP_SUMMARY echo "> ℹī¸ INFO: we use [golangci-lint action](https://github.com/golangci/golangci-lint-action)" >> $GITHUB_STEP_SUMMARY - echo "> to lint any change to go code from master" >> $GITHUB_STEP_SUMMARY + echo "> to lint any change to go code from master." >> $GITHUB_STEP_SUMMARY unit_tests: name: Unit tests @@ -116,7 +116,7 @@ jobs: echo "### All tests completed. 👍" >> $GITHUB_STEP_SUMMARY echo "" >> $GITHUB_STEP_SUMMARY echo "> ℹī¸ INFO: we run unit tests in 6 different configurations of OS and go version." >> $GITHUB_STEP_SUMMARY - echo "> At this moment, we don't run architecture-specific test runs" >> $GITHUB_STEP_SUMMARY + echo "> At this moment, we don't run architecture-specific tests." >> $GITHUB_STEP_SUMMARY echo "" >> $GITHUB_STEP_SUMMARY echo "| go version | OS | Result |" >> $GITHUB_STEP_SUMMARY echo "|------------|----|--------|" >> $GITHUB_STEP_SUMMARY diff --git a/.github/workflows/local-doc-update.yml b/.github/workflows/local-doc-update.yml new file mode 100644 index 0000000..b178b42 --- /dev/null +++ b/.github/workflows/local-doc-update.yml @@ -0,0 +1,17 @@ +name: doc update check + +# This workflow mimics how a go-openapi repo would typically invoke the common workflow. + +on: + pull_request_target: + paths: + - '**/*.md' + +permissions: + pull-requests: write + contents: read + +jobs: + test: + uses: ./.github/workflows/doc-update.yml + secrets: inherit diff --git a/README.md b/README.md index 0d268cd..5e45a29 100644 --- a/README.md +++ b/README.md @@ -10,26 +10,28 @@ NOTE: at this moment, it is difficult to share the golangci-lint config, so that ## Motivation It took a while, but we eventually managed to align all checks, tests and dependabot rules declared in the -family of go-openapi repos. +family of go-openapi repos. Now we'd like to be able to maintain, enrich and improve these checks without worrying too much about the burden to replicate it about a dozen times. ## Contemplated enhancements -* [x] enrich github actions UI with a job summary -* [] version common workflows, so we can limit the impact of a change -* [] verify that go.sum cache for tests works (should be enabled) -* [] share mono repo workflows (see github.com/go-openapi/swag/.github/workflows) -* [] manage somehow to share golangci config (with local merge) -* [] manage somehow to share / replicate dependabot config -* [] add markdown linting for docs -* [] golangci-lint: check valid PR comments etc -* [] add spellcheck for docs (and code?) -* [] use non-blocking, scheduled, proactive full linting to check for the impact of new linters, new go versions etc -* [] (possibility) take over hugo & doc gen part from go-swagger -* [] (possibility) take over release part from go-swagger -* [] produce hugo github page with all latest tagged versions (incl. mono repo) -* [] add bot to filter PRs, issues -* [] check with github API that all repo settings (branch protection rules, etc) are identical -* [] comment PRs and issues +In no particular order: + +* [x] ui: enrich github actions UI with a job summary +* [x] doc: add markdown linting for docs +* [ ] doc: add spellcheck for docs (and code?) +* [ ] version common workflows, so we can limit the impact of a change +* [ ] build: verify that go.sum cache for tests works (should be enabled) +* [ ] share mono repo workflows (see github.com/go-openapi/swag/.github/workflows) +* [ ] lint: manage somehow to share golangci config (with local merge) +* [ ] deps: manage somehow to share / replicate dependabot config +* [ ] lint: golangci-lint: check valid PR comments etc +* [ ] lint: use non-blocking, scheduled, proactive full linting to check for the impact of new linters, new go versions etc +* [ ] doc: (possibility) take over hugo & doc gen part from go-swagger +* [ ] (possibility) take over release part from go-swagger +* [ ] doc: produce hugo github page with all latest tagged versions (incl. mono repo) +* [ ] add bot to filter PRs, issues +* [ ] check with github API that all repo settings (branch protection rules, etc) are identical +* [ ] comment PRs and issues From 3fecb39f8cd290635dfbad122309825cb0b08ed6 Mon Sep 17 00:00:00 2001 From: fredbi Date: Sun, 24 Aug 2025 19:34:58 +0200 Subject: [PATCH 06/28] doc(lint): experiment markdown linting (#5) * added custom rule set, disabling a few of the default rules (too strict) Signed-off-by: Frederic BIDON --- .github/.markdownlint.yml | 30 ++++++++++++++++++++++++++++++ .github/workflows/doc-update.yml | 1 - README.md | 30 ++++++++++++++++++++---------- 3 files changed, 50 insertions(+), 11 deletions(-) create mode 100644 .github/.markdownlint.yml diff --git a/.github/.markdownlint.yml b/.github/.markdownlint.yml new file mode 100644 index 0000000..b25be39 --- /dev/null +++ b/.github/.markdownlint.yml @@ -0,0 +1,30 @@ +# See rules documentation: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md + +# Default state for all rules +default: true + +# ul-style # default: consistent +MD004: consistent + +# hard-tabs +MD010: false + +# line-length +MD013: false + +# no-duplicate-header +MD024: + siblings_only: true + +#single-title +MD025: true + +# ol-prefix +MD029: + style: one_or_ordered + +# no-inline-html +MD033: false + +# fenced-code-language +MD040: false diff --git a/.github/workflows/doc-update.yml b/.github/workflows/doc-update.yml index f51d5c7..eba98ae 100644 --- a/.github/workflows/doc-update.yml +++ b/.github/workflows/doc-update.yml @@ -4,7 +4,6 @@ on: workflow_call: # TODO: -# * [] markdown lint # * [] spell checker permissions: diff --git a/README.md b/README.md index 5e45a29..e469436 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,26 @@ -# ci-workflows +# ci-workflows[![Build Status](https://github.com/go-openapi/ci-workflows/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/ci-workflows/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/ci-workflows/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/ci-workflows) + +[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) +[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/ci-workflows/master/LICENSE) +[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/ci-workflows.svg)](https://pkg.go.dev/github.com/go-openapi/ci-workflows) +[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/ci-workflows)](https://goreportcard.com/report/github.com/go-openapi/ci-workflows) Common CI workflows and setup for go-openapi repos. * shared github action workflows -* shared dependabot config +* shared dependabot config (TODO) +* shared golangci config (**BLOCKED**) -NOTE: at this moment, it is difficult to share the golangci-lint config, so that one is not shared yet. +> NOTE: at this moment, it is difficult to share the golangci-lint config, +> so that one is not shared yet. ## Motivation -It took a while, but we eventually managed to align all checks, tests and dependabot rules declared in the -family of go-openapi repos. +It took a while, but we eventually managed to align all checks, tests and +dependabot rules declared in the family of go-openapi repos. -Now we'd like to be able to maintain, enrich and improve these checks without worrying too much about -the burden to replicate it about a dozen times. +Now we'd like to be able to maintain, enrich and improve these checks without +worrying too much about the burden to replicate it about a dozen times. ## Contemplated enhancements @@ -28,10 +35,13 @@ In no particular order: * [ ] lint: manage somehow to share golangci config (with local merge) * [ ] deps: manage somehow to share / replicate dependabot config * [ ] lint: golangci-lint: check valid PR comments etc -* [ ] lint: use non-blocking, scheduled, proactive full linting to check for the impact of new linters, new go versions etc +* [ ] lint: use non-blocking, scheduled, proactive full linting to check for + the impact of new linters, new go versions etc * [ ] doc: (possibility) take over hugo & doc gen part from go-swagger * [ ] (possibility) take over release part from go-swagger -* [ ] doc: produce hugo github page with all latest tagged versions (incl. mono repo) +* [ ] doc: produce hugo github page with all latest tagged versions + (incl. mono repo) * [ ] add bot to filter PRs, issues -* [ ] check with github API that all repo settings (branch protection rules, etc) are identical +* [ ] check with github API that all repo settings (branch protection rules, etc) + are identical * [ ] comment PRs and issues From 0edae5203b9ea107ae4fe73c630b5bdf07e5b194 Mon Sep 17 00:00:00 2001 From: Frederic BIDON Date: Tue, 26 Aug 2025 07:59:27 +0200 Subject: [PATCH 07/28] added spellcheck config separately Signed-off-by: Frederic BIDON --- .github/.spellcheck.yml | 32 ++++++++++++++++++++++++++ .github/.wordlist.txt | 51 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 83 insertions(+) create mode 100644 .github/.spellcheck.yml create mode 100644 .github/.wordlist.txt diff --git a/.github/.spellcheck.yml b/.github/.spellcheck.yml new file mode 100644 index 0000000..3906aed --- /dev/null +++ b/.github/.spellcheck.yml @@ -0,0 +1,32 @@ +spellchecker: hunspell +matrix: + - name: markdown + hunspell: + d: en_us + ignore-case: true + pipeline: + - pyspelling.filters.url: + urls: true + emails: true + - pyspelling.filters.markdown: + markdown_extensions: + - pymdownx.superfences + - pymdownx.arithmatex + - md_in_html + - markdown.extensions.extra: + - pyspelling.filters.html: + comments: false + attributes: + - alt + ignores: + - ':matches(code, pre)' + - 'code' + - 'pre' + - 'blockquote' + dictionary: + wordlists: + - .github/.wordlist.txt + output: .github/spellcheck.dic + default_encoding: utf-8 + sources: + - '**.md' diff --git a/.github/.wordlist.txt b/.github/.wordlist.txt new file mode 100644 index 0000000..54a72c0 --- /dev/null +++ b/.github/.wordlist.txt @@ -0,0 +1,51 @@ +API +CI +DCO +DockerHub +FAQ +HUGO +ID +IDs +Markdown +OAI +OpenAPI +PR +PRs +TODO +UI +USD +api +assignees +bash +bitmask +ci +codecov +config +dependabot +docker +faq +fuzzying +github +go-openapi +golang +golangci +html +http +https +hugo +id +json +jsonschema +linter +linters +markdown +oai +openapi +repo +repos +schema +swagger +toolchain +ui +utf-8 +yaml From 0ac18fdba747826cde5e042bdd3c69320177d951 Mon Sep 17 00:00:00 2001 From: Frederic BIDON Date: Tue, 26 Aug 2025 08:58:58 +0200 Subject: [PATCH 08/28] added trusted shared workflow separately Signed-off-by: Frederic BIDON --- .github/workflows/pr-comment.yml | 151 +++++++++++++++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 .github/workflows/pr-comment.yml diff --git a/.github/workflows/pr-comment.yml b/.github/workflows/pr-comment.yml new file mode 100644 index 0000000..9d70c36 --- /dev/null +++ b/.github/workflows/pr-comment.yml @@ -0,0 +1,151 @@ +name: pr-comment +# description: | +# This workflow is a trusted workflow that creates or updates comments in PRs. +# +# It may be called by other workflows executing on pull_requests against the go-openapi repos. +# +# The principle is to communicate the content of a comment between workflows using an uploaded artifact. + +on: + workflow_call: + inputs: + run_id: + description: | + The run ID of the calling workflow that has emitted the message artifact, e.g. ${{ github.event.workflow_run.id }} + required: true + target_repo: + description: | + The target repository of the PR, e.g. ${{ github.repository }} + required: true + pr_number: + description: | + The pull request number, e.g. ${{ github.event.pull_request.number }} + required: true + pr_sha: + description: | + The commit sha for the originating pull request, e.g. ${{github.event.pull_request.head.sha}} + required: true + artifact_name: + description: | + The reference to the artifact containing the text of the comment. + + At this moment, only supports "markdown_comment.txt" and "spelling_comment.txt" + required: true + comment_title: + description: | + Title is a text string used to uniquely identify a comment that will be upaded on subsequent commits. + required: true + reactions: + description: | + Optional emoji reaction added to the comment. + required: false + +permissions: + pull-requests: read # <- job will exchange token as-needed when it comes to writing. + contents: read + +env: + GITHUB_API: "https://api.github.com" + MAX_MESSAGE_SIZE: 4096 + +jobs: + pr-comment: + runs-on: ubuntu-latest + env: + MESSAGE_FILE: "artifacts/${{ inputs.artifact_name}}" + TARGET: "${{ inputs.target_repo }}" + steps: + - name: Validate inputs + run: | + if [[ "${{ env.TARGET }}" !~ /github.com\/go-openapi/ ]] ; then + echo "This workflow only applies to target repos in github.com/go-openapi." + exit 1 + fi + if [[ "${{ inputs.artifact_name }}" != "markdown_comment.txt" && "${{ inputs.artifact_name }}" != "spelling_comment.txt" && ]] ; then + echo "This workflow only applies to artifacts named markdown_comment.txt or spelling_comment.txt" + exit 1 + fi + + - name: Check originating PR + # description: | + # This check verifies that the originating PR has not been already modified + # by the time this workflow executes. If this is the case, the job is skipped + # and no comment is issued. + id: check_pr + env: + PRN: "${{ inputs.pr_number }}" + run: | + LAST_COMMIT=$(\ + curl -s \ + -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \ + "${GITHUB_API}/repos/${TARGET}/pulls/${PRN}/commits" | \ + jq -r '.[-1].sha'\ + ) + + if [[ "${LAST_COMMIT}" != "${{ inputs.pr_sha }}" ]] ; then + echo "The PR has changed while we were about to commit it. Skip." + echo "proceed=false" >> "${{GITHUB_OUTPUT}}" + + echo "::warning:: pull request comment skipped because ${{ github.event.pull_request.number }} has changed" + exit 0 + fi + echo "proceed=true" >> "${{GITHUB_ENV}}" + + - name: Download message artifact + if: ${{ steps.check_pr.outputs.proceed == "true"}} + uses: actions/download-artifact@v5 + with: + run_id: "${{ inputs.run_id }}" + repository: "${{ env.TARGET }}" + name: "${{ inputs.artifact_name }}" + path: artifacts/ + github_token: ${{secrets.GITHUB_TOKEN}} + + - name: Check message artifact size + if: ${{ steps.check_pr.outputs.proceed == "true"}} + id: load_artifact + run: | + SIZE=$(wc -c "${MESSAGE_FILE}" + if [[ "${SIZE}" -gt "${{ env.MAX_MESSAGE_SIZE }}" ]] ; then + # truncate the message up to MAX_MESSAGE_SIZE + head -c ${{ env.MAX_MESSAGE_SIZE }} "${MESSAGE_FILE}" > /tmp/truncated + mv /tmp/truncated "${MESSAGE_FILE}" + echo "::warning:: comment message with size ${SIZE} has been truncated to ${{ env.MAX_MESSAGE_SIZE }} bytes." + fi + echo "message=$(cat ${MESSAGE_FILE})" >> "${GITHUB_OUTPUT}" + + - name: Find previous PR comment + if: ${{ steps.check_pr.outputs.proceed == "true"}} + uses: peter-evans/find-comment@v3 + id: find_comment + with: + repository: ${{ inputs.target_repo }} + issue-number: ${{ inputs.pr_number }} + body-includes: ${{ inputs.comment_title }} + direction: last + token: ${{ secrets.GITHUB_TOKEN }} + + - name: Acquire write access to PR + if: ${{ steps.check_pr.outputs.proceed == "true"}} + id: acquire_write_token + uses: actions/create-github-app-token@v2 + with: + app-id: ${{ secrets.CI_WORKFLOWS_PR_APP_ID }} + private-key: ${{ secrets.CI_WORKFLOWS_PR_APP_PRIVATE_KEY }} + + - name: Create or update PR comment + if: ${{ steps.check_pr.outputs.proceed == "true"}} + uses: peter-evans/create-or-update-comment@v4 + with: + issue-number: ${{ inputs.pr_number }} + comment-id: ${{ steps.find_comment.outputs.comment-id }} + reactions: ${{ inputs.reactions }} + reactions-edit-mode: replace + body-path: ${{ env.MESSAGE_FILE }} + edit-mode: replace + token: ${{ steps.acquire_write_token.outputs.token }} + + - name: Notify + run: | + echo "::notice::Commented pull request ${{ inputs.pr_number }}" + echo "::debug::${{ steps.load_artifacts.outputs.message }}" From 64323acd0129ac1c92f6cbad4db5723232d09fd7 Mon Sep 17 00:00:00 2001 From: Frederic BIDON Date: Tue, 26 Aug 2025 21:35:54 +0200 Subject: [PATCH 09/28] fixed trusted workflow Signed-off-by: Frederic BIDON --- .github/workflows/pr-comment.yml | 33 +++++++++++++++++++------------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/.github/workflows/pr-comment.yml b/.github/workflows/pr-comment.yml index 9d70c36..71b538c 100644 --- a/.github/workflows/pr-comment.yml +++ b/.github/workflows/pr-comment.yml @@ -11,33 +11,40 @@ on: inputs: run_id: description: | - The run ID of the calling workflow that has emitted the message artifact, e.g. ${{ github.event.workflow_run.id }} + The run ID of the calling workflow that has emitted the message artifact, e.g. {{ github.event.workflow_run.id }} + type: string required: true target_repo: description: | - The target repository of the PR, e.g. ${{ github.repository }} + The target repository of the PR, e.g. {{ github.repository }} + type: string required: true pr_number: description: | - The pull request number, e.g. ${{ github.event.pull_request.number }} + The pull request number, e.g. {{ github.event.pull_request.number }} + type: string required: true pr_sha: description: | - The commit sha for the originating pull request, e.g. ${{github.event.pull_request.head.sha}} + The commit sha for the originating pull request, e.g. {{github.event.pull_request.head.sha}} + type: string required: true artifact_name: description: | The reference to the artifact containing the text of the comment. At this moment, only supports "markdown_comment.txt" and "spelling_comment.txt" + type: string required: true comment_title: description: | Title is a text string used to uniquely identify a comment that will be upaded on subsequent commits. + type: string required: true reactions: description: | Optional emoji reaction added to the comment. + type: string required: false permissions: @@ -57,11 +64,11 @@ jobs: steps: - name: Validate inputs run: | - if [[ "${{ env.TARGET }}" !~ /github.com\/go-openapi/ ]] ; then + if ! [[ "${{ env.TARGET }}" =~ "^go-openapi\/.*$" ]] ; then echo "This workflow only applies to target repos in github.com/go-openapi." exit 1 fi - if [[ "${{ inputs.artifact_name }}" != "markdown_comment.txt" && "${{ inputs.artifact_name }}" != "spelling_comment.txt" && ]] ; then + if [[ "${{ inputs.artifact_name }}" != "markdown_comment.txt" && "${{ inputs.artifact_name }}" != "spelling_comment.txt" ]] ; then echo "This workflow only applies to artifacts named markdown_comment.txt or spelling_comment.txt" exit 1 fi @@ -84,15 +91,15 @@ jobs: if [[ "${LAST_COMMIT}" != "${{ inputs.pr_sha }}" ]] ; then echo "The PR has changed while we were about to commit it. Skip." - echo "proceed=false" >> "${{GITHUB_OUTPUT}}" + echo "proceed=false" >> "${GITHUB_OUTPUT}" echo "::warning:: pull request comment skipped because ${{ github.event.pull_request.number }} has changed" exit 0 fi - echo "proceed=true" >> "${{GITHUB_ENV}}" + echo "proceed=true" >> "${GITHUB_OUTPUT}" - name: Download message artifact - if: ${{ steps.check_pr.outputs.proceed == "true"}} + if: ${{ steps.check_pr.outputs.proceed == 'true'}} uses: actions/download-artifact@v5 with: run_id: "${{ inputs.run_id }}" @@ -102,7 +109,7 @@ jobs: github_token: ${{secrets.GITHUB_TOKEN}} - name: Check message artifact size - if: ${{ steps.check_pr.outputs.proceed == "true"}} + if: ${{ steps.check_pr.outputs.proceed == 'true'}} id: load_artifact run: | SIZE=$(wc -c "${MESSAGE_FILE}" @@ -115,7 +122,7 @@ jobs: echo "message=$(cat ${MESSAGE_FILE})" >> "${GITHUB_OUTPUT}" - name: Find previous PR comment - if: ${{ steps.check_pr.outputs.proceed == "true"}} + if: ${{ steps.check_pr.outputs.proceed == 'true'}} uses: peter-evans/find-comment@v3 id: find_comment with: @@ -126,7 +133,7 @@ jobs: token: ${{ secrets.GITHUB_TOKEN }} - name: Acquire write access to PR - if: ${{ steps.check_pr.outputs.proceed == "true"}} + if: ${{ steps.check_pr.outputs.proceed == 'true'}} id: acquire_write_token uses: actions/create-github-app-token@v2 with: @@ -134,7 +141,7 @@ jobs: private-key: ${{ secrets.CI_WORKFLOWS_PR_APP_PRIVATE_KEY }} - name: Create or update PR comment - if: ${{ steps.check_pr.outputs.proceed == "true"}} + if: ${{ steps.check_pr.outputs.proceed == 'true'}} uses: peter-evans/create-or-update-comment@v4 with: issue-number: ${{ inputs.pr_number }} From 2f1bdfe40232bee6e5c225f6697a7d0e1f49ab9c Mon Sep 17 00:00:00 2001 From: Frederic BIDON Date: Wed, 27 Aug 2025 08:49:25 +0200 Subject: [PATCH 10/28] fixup again pr-comment Signed-off-by: Frederic BIDON --- .github/workflows/pr-comment.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/pr-comment.yml b/.github/workflows/pr-comment.yml index 71b538c..d5fb827 100644 --- a/.github/workflows/pr-comment.yml +++ b/.github/workflows/pr-comment.yml @@ -64,7 +64,8 @@ jobs: steps: - name: Validate inputs run: | - if ! [[ "${{ env.TARGET }}" =~ "^go-openapi\/.*$" ]] ; then + rex='^go-openapi\/.*$' + if ! [[ "${{ env.TARGET }}" =~ $rex ]] ; then echo "This workflow only applies to target repos in github.com/go-openapi." exit 1 fi From 018d05acab5465f0485d06e1774351959ec9fbcd Mon Sep 17 00:00:00 2001 From: Frederic BIDON Date: Wed, 27 Aug 2025 09:16:38 +0200 Subject: [PATCH 11/28] fixup again pr-comment Signed-off-by: Frederic BIDON --- .github/workflows/pr-comment.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/pr-comment.yml b/.github/workflows/pr-comment.yml index d5fb827..8bb7e24 100644 --- a/.github/workflows/pr-comment.yml +++ b/.github/workflows/pr-comment.yml @@ -113,7 +113,7 @@ jobs: if: ${{ steps.check_pr.outputs.proceed == 'true'}} id: load_artifact run: | - SIZE=$(wc -c "${MESSAGE_FILE}" + SIZE=$(wc -c "${MESSAGE_FILE}") if [[ "${SIZE}" -gt "${{ env.MAX_MESSAGE_SIZE }}" ]] ; then # truncate the message up to MAX_MESSAGE_SIZE head -c ${{ env.MAX_MESSAGE_SIZE }} "${MESSAGE_FILE}" > /tmp/truncated From 5d6e32880807decba5c97ad5cc3d924bf0595195 Mon Sep 17 00:00:00 2001 From: Frederic BIDON Date: Wed, 27 Aug 2025 19:06:14 +0200 Subject: [PATCH 12/28] fixup again pr-comment Signed-off-by: Frederic BIDON --- .github/workflows/pr-comment.yml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/.github/workflows/pr-comment.yml b/.github/workflows/pr-comment.yml index 8bb7e24..0a36dd4 100644 --- a/.github/workflows/pr-comment.yml +++ b/.github/workflows/pr-comment.yml @@ -59,7 +59,6 @@ jobs: pr-comment: runs-on: ubuntu-latest env: - MESSAGE_FILE: "artifacts/${{ inputs.artifact_name}}" TARGET: "${{ inputs.target_repo }}" steps: - name: Validate inputs @@ -101,26 +100,28 @@ jobs: - name: Download message artifact if: ${{ steps.check_pr.outputs.proceed == 'true'}} + id: download uses: actions/download-artifact@v5 with: - run_id: "${{ inputs.run_id }}" + run-id: "${{ inputs.run_id }}" repository: "${{ env.TARGET }}" name: "${{ inputs.artifact_name }}" path: artifacts/ - github_token: ${{secrets.GITHUB_TOKEN}} + github-token: ${{secrets.GITHUB_TOKEN}} - name: Check message artifact size if: ${{ steps.check_pr.outputs.proceed == 'true'}} - id: load_artifact run: | + MESSAGE_FILE="${{ steps.download.outputs.download-path }}/${{ inputs.artifact_name }}" SIZE=$(wc -c "${MESSAGE_FILE}") if [[ "${SIZE}" -gt "${{ env.MAX_MESSAGE_SIZE }}" ]] ; then # truncate the message up to MAX_MESSAGE_SIZE head -c ${{ env.MAX_MESSAGE_SIZE }} "${MESSAGE_FILE}" > /tmp/truncated + echo > /tmp/truncated + echo "... (truncated)" > /tmp/truncated mv /tmp/truncated "${MESSAGE_FILE}" echo "::warning:: comment message with size ${SIZE} has been truncated to ${{ env.MAX_MESSAGE_SIZE }} bytes." fi - echo "message=$(cat ${MESSAGE_FILE})" >> "${GITHUB_OUTPUT}" - name: Find previous PR comment if: ${{ steps.check_pr.outputs.proceed == 'true'}} @@ -149,11 +150,10 @@ jobs: comment-id: ${{ steps.find_comment.outputs.comment-id }} reactions: ${{ inputs.reactions }} reactions-edit-mode: replace - body-path: ${{ env.MESSAGE_FILE }} + body-path: ${{ steps.download.outputs.download-path }}/${{ inputs.artifact_name }} edit-mode: replace token: ${{ steps.acquire_write_token.outputs.token }} - name: Notify run: | echo "::notice::Commented pull request ${{ inputs.pr_number }}" - echo "::debug::${{ steps.load_artifacts.outputs.message }}" From e56ebbf39a8aa59ab27abb38ea3b3ff7787edb1a Mon Sep 17 00:00:00 2001 From: fredbi Date: Sat, 30 Aug 2025 22:37:20 +0200 Subject: [PATCH 13/28] fixed trusted workflow (#6) Signed-off-by: Frederic BIDON --- .github/all-mispelled.txt | 93 + .github/workflows/doc-update.yml | 479 +- .github/workflows/go-test.yml | 53 +- .github/workflows/local-auto-merge.yml | 3 +- .github/workflows/local-doc-update.yml | 3 +- .github/workflows/local-go-test.yml | 3 +- ALL.md | 7258 ++++++++++++++++++++++++ README.md | 17 +- 8 files changed, 7810 insertions(+), 99 deletions(-) create mode 100644 .github/all-mispelled.txt create mode 100644 ALL.md diff --git a/.github/all-mispelled.txt b/.github/all-mispelled.txt new file mode 100644 index 0000000..af64690 --- /dev/null +++ b/.github/all-mispelled.txt @@ -0,0 +1,93 @@ +AllOf +Args +AutoSeed +DCO +ERGGLGKLK +Formated +Fuzzying +GenerateMode +GeneratorOpts +GoDoc +JSON +README +Schemas +SetSeed +Severa +StubMode +Stubmode +USD +UnitTest +additionalItems +additionalProperties +appsawg +args +assignees +benchmarking +birthdate +bitmask +bsonobjectid +bugfix +codegen +customizable +datagen +datagenerator +datagenerators +datastructures +datetime +dco +definevalue +dev +developercertificate +eg +enum +everyhing +flanders +formated +fuzzying +gh +githubusercontent +godoc +gofmt +gojsonpointer +goreportcard +goswagger +html +ietf +img +ints +io +ipsums +ivan +json +jsonpointer +jsonschema +lang +loren +md +multipleOf +nz +patternProperties +preconfigured +rebase +rebased +schemas +sexualized +skipFuzzying +skipTilting +slackin +strfmt +stubmode +svg +th +tiltDefault +tiltExample +travis +unitTest +withAllValidationChecks +withDefault +withEdgeCase +withExample +withTilting +withValidation +withValidationCheck +yml diff --git a/.github/workflows/doc-update.yml b/.github/workflows/doc-update.yml index eba98ae..2385cff 100644 --- a/.github/workflows/doc-update.yml +++ b/.github/workflows/doc-update.yml @@ -1,92 +1,124 @@ name: doc update check +# description: | +# This workflow is designed to help improve documentation quality. +# +# It proceeds with markdown linting and checks spelling in markdown files every time a markdown file is changed +# in a pull request. +# +# > NOTE: this workflow is only concerned with markdown documentation, not documentation in code (e.g. godoc). +# +# ## Usage of github action features +# +# * shared workflow +# * temporary token exchange using github app to elevate privileges within a trusted workflow +# * job summary (on actions UI) +# +# ## Limitations of github action features +# +# * [ ] did not find a way yet to retrieve the repo repo specified by the caller of this workflow. +# Had to resort to `master` to retrieve extra config files. +# +# ## TODO +# +# * [ ] to refactor repeated jobs as a matrix job? as separate workflow +# * [ ] should make an adapted version that runs on schedule and analyzes all markdown. +# * [ ] in this case, instead of commenting pull requests, it should raise issues. +# * [ ] should be able to retrieve config files and dictionary from the called ref, not master. +# * [ ] should be able to merge config files and dictionary with local definitions on target repo. on: workflow_call: -# TODO: -# * [] spell checker - permissions: - pull-requests: write + pull-requests: read contents: read env: - comment-title: Markdown linter + artifacts_dir: artifacts + + markdown_comment_title: Markdown linter + markdown_config: '.github/.markdownlint.yml' + markdown_artifact: markdown_comment.txt + + spellcheck_comment_title: Markdown spelling check + spellcheck_config: .github/.spellcheck.yml + spellcheck_dict: .github/.wordlist.txt + spellcheck_artifact: spellcheck_comment.txt jobs: markdown-changed: # description: | - # This performs a markdown lint whenever documentation files change + # This triggers a markdown and spellcheck lint whenever documentation files change. runs-on: ubuntu-latest outputs: proceed: ${{ steps.changed-markdown-files.outputs.any_changed }} all_changed_files: ${{ steps.changed-markdown-files.outputs.all_changed_files }} steps: - - uses: actions/checkout@v5 - with: - ref: ${{ github.event.pull_request.head.sha }} - - - name: Get changed markdown files - uses: tj-actions/changed-files@v46 - id: changed-markdown-files - with: - files: '**/*.md' - - - name: Notify - run: | - echo "::notice::Detected some changed markdown files" - echo "${{ steps.changed-markdown-files.outputs.all_changed_files }}" - - lint-markdown: + - name: Originating repo checkout (e.g. public fork) + uses: actions/checkout@v5 + with: + ref: ${{ github.event.pull_request.head.sha }} + + - name: Get changed markdown files + uses: tj-actions/changed-files@v46 + id: changed-markdown-files + with: + files: '**/*.md' + + - name: Notify + run: | + echo "::notice::Detected some changed markdown files" + echo "${{ steps.changed-markdown-files.outputs.all_changed_files }}" + + markdown-lint: needs: markdown-changed - if: needs.markdown-changed.outputs.proceed == 'true' + if: ${{ needs.markdown-changed.outputs.proceed == 'true' }} runs-on: ubuntu-latest env: lintreport: './markdownlint-report.txt' outputs: proceed: ${{ steps.report-exists.outputs.proceed }} + congrats: ${{ steps.congrats.outputs.proceed }} report: ${{ steps.report-exists.outputs.report }} steps: - - name: Checkout Repo + - name: Originating repo checkout (e.g. public fork) uses: actions/checkout@v5 with: ref: ${{ github.event.pull_request.head.sha }} - #ref: "refs/pull/${{ github.event.number }}/merge" # it's okay to pull the user's changes: we just scan md's + + - name: Checkout markdown config + uses: actions/checkout@v5 + with: + repository: go-openapi/ci-workflows + ref: master # TODO: retrieve workflow ref + sparse-checkout: | + ${{ env.markdown_config }} + sparse-checkout-cone-mode: false + path: ci-tools + + - name: Copy markdown config + # TODO: merge with local if present + run: | + cp ci-tools/"${{ env.markdown_config}}" "${{ env.markdown_config }}" - name: Run markdown linter continue-on-error: true id: markdownlint uses: docker://avtodev/markdown-lint:v1.5 with: - config: ./.github/.markdownlint.yml + config: ./${{ env.markdown_config }} args: '${{ needs.markdown-changed.outputs.all_changed_files }}' output: '${{ env.lintreport }}' - - name: Find previous PR comment - if: steps.markdownlint.outcome == 'success' - uses: peter-evans/find-comment@v3 - id: findcomment - with: - issue-number: ${{ github.event.pull_request.number }} - body-includes: ${{ env.comment-title }} - direction: last - - name: Comment on success - if: steps.markdownlint.outcome == 'success' + if: ${{ steps.markdownlint.outcome == 'success' }} id: congrats - uses: peter-evans/create-or-update-comment@v4 - with: - issue-number: ${{ github.event.pull_request.number }} - comment-id: ${{ steps.findcomment.outputs.comment-id }} - reactions: hooray - reactions-edit-mode: replace - body: | - ### ${{ env.comment-title }} - - Markdown looks good to me. Congrats! + run: | + echo "::notice:: no linting issue with changed markdown" + echo "proceed=true" >> $GITHUB_OUTPUT - - name: Check lint report exists + - name: Comment on markdown lint complaining if: ${{ steps.markdownlint.outcome != 'success' && hashFiles(env.lintreport) != '' }} id: report-exists run: | @@ -109,50 +141,345 @@ jobs: echo "::error::markdown linter encountered an error" exit 1 - pr-comment: - needs: lint-markdown - if: needs.lint-markdown.outputs.proceed == 'true' + markdown-spelling: + needs: markdown-changed + if: ${{ needs.markdown-changed.outputs.proceed == 'true' }} runs-on: ubuntu-latest + env: + spellcheckreport: './spellcheck-report.txt' + outputs: + proceed: ${{ steps.report-exists.outputs.proceed }} + congrats: ${{ steps.congrats.outputs.proceed }} + report: ${{ steps.report-exists.outputs.report }} + steps: + - uses: actions/checkout@v5 + + - name: Checkout spellcheck config + uses: actions/checkout@v5 + with: + repository: go-openapi/ci-workflows + ref: master # TODO: retrieve workflow ref + sparse-checkout: | + ${{ env.spellcheck_config }} + ${{ env.spellcheck_dict }} + sparse-checkout-cone-mode: false + path: ci-tools + + - name: Copy spellcheck config + # TODO: merge with local if present + run: | + cp ci-tools/${{ env.spellcheck_config }} ${{ env.spellcheck_config }} + cp ci-tools/${{ env.spellcheck_dict }} ${{ env.spellcheck_dict }} + + - name: Spellcheck + uses: rojopolis/spellcheck-github-actions@0.51.0 + continue-on-error: true + id: spellcheck + with: + config_path: ${{ env.spellcheck_config }} + source_files: '${{ needs.markdown-changed.outputs.all_changed_files }}' + task_name: markdown + output_file: ${{ env.spellcheckreport }} + + - name: Comment on success + if: ${{ steps.spellcheck.outcome == 'success' }} + id: congrats + run: | + echo "::notice:: no spelling issue with changed markdown" + echo "proceed=true" >> $GITHUB_OUTPUT + echo "### Your changes to markdown docs show impeccable spelling. 👍" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "> ℹī¸ INFO: we use [rojopolis/spellcheck-github-actions](https://github.com/rojopolis/spellcheck-github-actions)" >> $GITHUB_STEP_SUMMARY + + - name: Comment on spellcheck complaining + if: ${{ steps.spellcheck.outcome != 'success' && hashFiles(env.spellcheckreport) != '' }} + id: report-exists + run: | + echo 'report<> $GITHUB_OUTPUT + cat ${{ env.spellcheckreport }}|sed -e '$a\' >> $GITHUB_OUTPUT + echo 'EOF' >> $GITHUB_OUTPUT + + if [[ "$(cat ${{ env.spellcheckreport }}|wc -l)" != "0" ]] ; then + echo "proceed=true" >> $GITHUB_OUTPUT + echo "::notice::Detected some spelling issues with changed markdown" + cat ${{ env.lintreport }}|sed -e '$a\' + else + echo "proceed=false" >> $GITHUB_OUTPUT + echo "::notice::No spelling issues with changed markdown" + fi + + - name: Other linter errors + if: ${{ steps.spellcheck.outcome != 'success' && hashFiles(env.spellcheckreport) == '' }} + run: | + echo "::error::spellcheck encountered an error" + exit 1 + + pr-markdown-congrats: + needs: markdown-lint + if: ${{ needs.markdown-lint.outputs.congrats == 'true' }} + runs-on: ubuntu-latest + outputs: + run_id: ${{ steps.notify_markdown_congrats.outputs.run_id }} + target_repo: ${{ steps.notify_markdown_congrats.outputs.target_repo }} + pr_number: ${{ steps.notify_markdown_congrats.outputs.pr_number }} + pr_sha: ${{ steps.notify_markdown_congrats.outputs.pr_sha }} + artifact_name: ${{ steps.notify_markdown_congrats.outputs.artifact_name }} + comment_title: ${{ steps.notify_markdown_congrats.outputs.comment_title }} + reactions: ${{ steps.notify_markdown_congrats.outputs.reactions }} + steps: + - name: Congrats + id: notify_markdown_congrats + run: | + mkdir -p "${{ env.artifacts_dir }}" + read -d '' MSG< "${{ env.artifacts_dir}}/${{ env.markdown_artifact }}" + + echo "### Your changes to markdown docs look good. 👍" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "> ℹī¸ INFO: we use [avtodev/markdown-lint action](https://github.com/avto-dev/markdown-lint)" >> $GITHUB_STEP_SUMMARY + + echo "run_id=${{ github.run_id }}" >> "$GITHUB_OUTPUT" + echo "target_repo=${{ github.repository }}" >> "$GITHUB_OUTPUT" + echo "pr_number=${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT" + echo "pr_sha=${{ github.event.pull_request.head.sha }}" >> "$GITHUB_OUTPUT" + echo "artifact_name=${{ env.markdown_artifact }}" >> "$GITHUB_OUTPUT" + echo "comment_title=${{ env.markdown_comment_title }}" >> "$GITHUB_OUTPUT" + echo "reactions=hooray" >> "$GITHUB_OUTPUT" + + - name: Upload comment as artifact + uses: actions/upload-artifact@v4 + with: + path: ${{ env.artifacts_dir }}/${{ env.markdown_artifact }} + name: ${{ env.markdown_artifact }} + + pr-comment-markdown-congrats: + name: Create or update congrats comment + needs: pr-markdown-congrats + uses: go-openapi/ci-workflows/.github/workflows/pr-comment.yml@master # <- TODO: caller's ref + secrets: inherit + with: + run_id: ${{ needs.pr-markdown-congrats.outputs.run_id }} + target_repo: ${{ needs.pr-markdown-congrats.outputs.target_repo }} + pr_number: ${{ needs.pr-markdown-congrats.outputs.pr_number }} + pr_sha: ${{ needs.pr-markdown-congrats.outputs.pr_sha }} + artifact_name: ${{ needs.pr-markdown-congrats.outputs.artifact_name }} + comment_title: ${{ needs.pr-markdown-congrats.outputs.comment_title }} + reactions: ${{ needs.pr-markdown-congrats.outputs.reactions }} + + pr-markdown-report: + needs: markdown-lint + if: ${{ needs.markdown-lint.outputs.proceed == 'true' }} + outputs: + run_id: ${{ steps.notify_markdown_report.outputs.run_id }} + target_repo: ${{ steps.notify_markdown_report.outputs.target_repo }} + pr_number: ${{ steps.notify_markdown_report.outputs.pr_number }} + pr_sha: ${{ steps.notify_markdown_report.outputs.pr_sha }} + artifact_name: ${{ steps.notify_markdown_report.outputs.artifact_name }} + comment_title: ${{ steps.notify_markdown_report.outputs.comment_title }} + reactions: ${{ steps.notify_markdown_report.outputs.reactions }} + runs-on: ubuntu-latest steps: - name: Format PR comment - id: commentformatter - uses: skills/action-text-variables@v1 + id: comment_formatter + uses: skills/action-text-variables@v3 with: - template-vars: | - text='${{ needs.lint-markdown.outputs.report }}' + template-vars: > + { + "text": ${{ toJSON(needs.markdown-lint.outputs.report) }} + } template-text: | - ### ${{ env.comment-title }} + ### ${{ env.markdown_comment_title }} - Some markdown linting issues were detected in the modified .md files. + Some markdown linting issues were detected in the modified .md files. ⚠ī¸ + + Perhaps they were already there before your changes. + + This check is advisory only and not blocking. Please help us adopt a nice markdown style. + + Markdown formatting rules are documented [here](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md). +
+ {{ text }} + + - name: Slap on the wrist + env: + OUTPUT: "${{ steps.comment_formatter.outputs.updated-text }}" + run: | + mkdir -p "${{ env.artifacts_dir }}" + printenv OUTPUT > "${{ env.artifacts_dir}}/${{ env.markdown_artifact }}" + + echo "### Changed markdown docs need some formatting. ⚠ī¸" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "> ℹī¸ INFO: we use [avtodev/markdown-lint action](https://github.com/avto-dev/markdown-lint)" >> $GITHUB_STEP_SUMMARY + + - name: Upload comment as artifact + uses: actions/upload-artifact@v4 + with: + path: ${{ env.artifacts_dir }}/${{ env.markdown_artifact }} + name: ${{ env.markdown_artifact }} + + - name: Notify + id: notify_markdown_report + run: | + echo "::notice::Commented pull request ${{ github.event.pull_request.number }}" + + echo "run_id=${{ github.run_id }}" >> "$GITHUB_OUTPUT" + echo "target_repo=${{ github.repository }}" >> "$GITHUB_OUTPUT" + echo "pr_number=${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT" + echo "pr_sha=${{ github.event.pull_request.head.sha }}" >> "$GITHUB_OUTPUT" + echo "artifact_name=${{ env.markdown_artifact }}" >> "$GITHUB_OUTPUT" + echo "comment_title=${{ env.markdown_comment_title }}" >> "$GITHUB_OUTPUT" + echo "reactions=confused" >> "$GITHUB_OUTPUT" - Perhaps they were already there before your changes. + pr-comment-markdown-report: + name: Create or update comment with report + needs: pr-markdown-report + uses: go-openapi/ci-workflows/.github/workflows/pr-comment.yml@master # <- TODO: caller's ref + secrets: inherit + with: + run_id: ${{ needs.pr-markdown-report.outputs.run_id }} + target_repo: ${{ needs.pr-markdown-report.outputs.target_repo }} + pr_number: ${{ needs.pr-markdown-report.outputs.pr_number }} + pr_sha: ${{ needs.pr-markdown-report.outputs.pr_sha }} + artifact_name: ${{ needs.pr-markdown-report.outputs.artifact_name }} + comment_title: ${{ needs.pr-markdown-report.outputs.comment_title }} + reactions: ${{ needs.pr-markdown-report.outputs.reactions }} - This check is advisory only and not blocking. Please help us adopt a nice markdown style. + pr-markdown-spelling-congrats: + needs: markdown-spelling + if: ${{ needs.markdown-spelling.outputs.congrats == 'true' }} + outputs: + run_id: ${{ steps.notify_spelling_congrats.outputs.run_id }} + target_repo: ${{ steps.notify_spelling_congrats.outputs.target_repo }} + pr_number: ${{ steps.notify_spelling_congrats.outputs.pr_number }} + pr_sha: ${{ steps.notify_spelling_congrats.outputs.pr_sha }} + artifact_name: ${{ steps.notify_spelling_congrats.outputs.artifact_name }} + comment_title: ${{ steps.notify_spelling_congrats.outputs.comment_title }} + reactions: ${{ steps.notify_spelling_congrats.outputs.reactions }} + runs-on: ubuntu-latest + steps: + - name: Congrats + id: notify_spelling_congrats + run: | + mkdir -p artifacts + read -d '' MSG< "${{ env.artifacts_dir }}/${{ env.spellcheck_artifact }}" + + echo "run_id=${{ github.run_id }}" >> "$GITHUB_OUTPUT" + echo "target_repo=${{ github.repository }}" >> "$GITHUB_OUTPUT" + echo "pr_number=${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT" + echo "pr_sha=${{ github.event.pull_request.head.sha }}" >> "$GITHUB_OUTPUT" + echo "artifact_name=${{ env.spellcheck_artifact }}" >> "$GITHUB_OUTPUT" + echo "comment_title=${{ env.spellcheck_comment_title }}" >> "$GITHUB_OUTPUT" + echo "reactions=hooray" >> "$GITHUB_OUTPUT" + + - name: Upload comment as artifact + uses: actions/upload-artifact@v4 + with: + path: ${{ env.artifacts_dir }}/${{ env.spellcheck_artifact }} + name: ${{ env.spellcheck_artifact }} - Markdown formatting rules are documented [here](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md). -
- {{ text }} + pr-comment-spelling-congrats: + name: Create or update comment + needs: pr-markdown-spelling-congrats + uses: go-openapi/ci-workflows/.github/workflows/pr-comment.yml@master # <- TODO: caller's ref + secrets: inherit + with: + run_id: ${{ needs.pr-markdown-spelling-congrats.outputs.run_id }} + target_repo: ${{ needs.pr-markdown-spelling-congrats.outputs.target_repo }} + pr_number: ${{ needs.pr-markdown-spelling-congrats.outputs.pr_number }} + pr_sha: ${{ needs.pr-markdown-spelling-congrats.outputs.pr_sha }} + artifact_name: ${{ needs.pr-markdown-spelling-congrats.outputs.artifact_name }} + comment_title: ${{ needs.pr-markdown-spelling-congrats.outputs.comment_title }} + reactions: ${{ needs.pr-markdown-spelling-congrats.outputs.reactions }} - - name: Find previous PR comment - uses: peter-evans/find-comment@v3 - id: findcomment + pr-markdown-spelling-report: + needs: markdown-spelling + if: ${{ needs.markdown-spelling.outputs.proceed == 'true' }} + outputs: + run_id: ${{ steps.notify_spelling_report.outputs.run_id }} + target_repo: ${{ steps.notify_spelling_report.outputs.target_repo }} + pr_number: ${{ steps.notify_spelling_report.outputs.pr_number }} + pr_sha: ${{ steps.notify_spelling_report.outputs.pr_sha }} + artifact_name: ${{ steps.notify_spelling_report.outputs.artifact_name }} + comment_title: ${{ steps.notify_spelling_report.outputs.comment_title }} + reactions: ${{ steps.notify_spelling_report.outputs.reactions }} + runs-on: ubuntu-latest + steps: + - name: Format PR comment + id: comment_formatter + uses: skills/action-text-variables@v3 with: - issue-number: ${{ github.event.pull_request.number }} - body-includes: ${{ env.comment-title }} - direction: last + template-vars: > + { + "text": ${{ toJSON(needs.markdown-spelling.outputs.report) }} + } + template-text: | + ### ${{ env.spelling_comment_title }} + + Some mispelled words were detected in the modified .md files. ⚠ī¸ + + Perhaps they were already there before your changes. - - name: Create or update PR comment - uses: peter-evans/create-or-update-comment@v4 + This check is advisory only and not blocking. Please help us improve our documentation. +
+ {{ text }} + + - name: Slap on the wrist + env: + OUTPUT: "${{ steps.comment_formatter.outputs.updated-text }}" + run: | + mkdir -p "${{ env.artifacts_dir }}" + printenv OUTPUT > "${{ env.artifacts_dir}}/${{ env.spellcheck_artifact }}" + + echo "### Changed markdown docs show some mispelled words. ⚠ī¸" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "> ℹī¸ INFO: we use [rojopolis/spellcheck-github-actions](https://github.com/rojopolis/spellcheck-github-actions)" >> $GITHUB_STEP_SUMMARY + + - name: Upload comment as artifact + # description: | + # Calls a trusted shared workflow that temporarily elevates the caller's privileges + # to write a comment in the PR. + uses: actions/upload-artifact@v4 with: - issue-number: ${{ github.event.pull_request.number }} - comment-id: ${{ steps.findcomment.outputs.comment-id }} - reactions: confused - reactions-edit-mode: replace - body: ${{ steps.commentformatter.outputs.updated-text }} - edit-mode: replace + path: ${{ env.artifacts_dir }}/${{ env.spellcheck_artifact }} + name: ${{ env.spellcheck_artifact }} - name: Notify + id: notify_spelling_report run: | echo "::notice::Commented pull request ${{ github.event.pull_request.number }}" - echo "::debug::${{ steps.commentformatter.outputs.updated-text }}" + + echo "run_id=${{ github.run_id }}" >> "$GITHUB_OUTPUT" + echo "target_repo=${{ github.repository }}" >> "$GITHUB_OUTPUT" + echo "pr_number=${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT" + echo "pr_sha=${{ github.event.pull_request.head.sha }}" >> "$GITHUB_OUTPUT" + echo "artifact_name=${{ env.spelling_artifact }}" >> "$GITHUB_OUTPUT" + echo "comment_title=${{ env.spelling_comment_title }}" >> "$GITHUB_OUTPUT" + echo "reactions=confused" >> "$GITHUB_OUTPUT" + + pr-comment-spelling-report: + name: Create or update comment + needs: pr-markdown-spelling-report + secrets: inherit + uses: ./.github/workflows/pr-comment.yml + with: + run_id: ${{ needs.pr-markdown-spelling-report.outputs.run_id }} + target_repo: ${{ needs.pr-markdown-spelling-report.outputs.target_repo }} + pr_number: ${{ needs.pr-markdown-spelling-report.outputs.pr_number }} + pr_sha: ${{ needs.pr-markdown-spelling-report.outputs.pr_sha }} + artifact_name: ${{ needs.pr-markdown-spelling-report.outputs.artifact_name }} + comment_title: ${{ needs.pr-markdown-spelling-report.outputs.comment_title }} + reactions: ${{ needs.pr-markdown-spelling-report.outputs.reactions }} diff --git a/.github/workflows/go-test.yml b/.github/workflows/go-test.yml index 93b4a50..a949b61 100644 --- a/.github/workflows/go-test.yml +++ b/.github/workflows/go-test.yml @@ -1,4 +1,24 @@ name: go test +# description: | +# This workflow to run unit tests on a repo that contains a single go module. +# +# ## Usage of github action features +# +# * shared workflow +# * matrix job +# * job summary (on actions UI) +# +# ## Limitations of github action features +# +# * [ ] needed to hardcode all matrix job entries as outputs. No way to make this dynamic. +# +# ## TODO +# +# * [ ] perhaps implement in golangci-lint the "extends" or "include" functionality to merge +# config files from a remote location. We don't want to push configs from CI as we'd +# like all repos to allow users to fork, lint and run just like they were independent, +# and not impose some "invisible linter" check. +# * [ ] we need to make a specific version for mono-repos. For now, only go-openapi swag is a mono-repo. on: workflow_call: @@ -7,14 +27,14 @@ jobs: lint: name: Lint # description: | - # Lint uses golangci-lint github action and lints only changes from master. + # Lint uses golangci-lint github action and lints only changes from master. # - # It will run on the latest go version. + # It will run on the latest go version. # - # We rely on golangci-lint to automatically disable linters that do not apply to the minimum required go version - # currently defined in go.mod. + # We rely on golangci-lint to automatically disable linters that do not apply to the minimum required go version + # currently defined in go.mod. # - # At this moment, .golangci.yml configuration files are not shared: each repository must have its configuration. + # At this moment, .golangci.yml configuration files are not shared: each repository must have its configuration. runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 @@ -39,11 +59,13 @@ jobs: unit_tests: name: Unit tests # description: | - # Run go unit tests run x6: linux, mac & windows on the 2 latest go versions. + # Run go unit tests x6 on linux, mac & windows for the 2 latest go versions. # - # Run tests with the -race flag. + # * Run tests with the -race flag. + # * Captures test coverage and uploads it to codecov.com. # - # Captures test coverage and uploads it to codecov.com. + # > NOTE: coverage uploads to codecov are authorized thanks to an organization token that is + # > managed on [codecov admin console](https://app.codecov.io/account/gh/go-openapi). runs-on: ${{ matrix.os }} outputs: # NOTE(fredbi): as of Aug. 2025, there is no way to have github actions declare outputs dynamically @@ -70,8 +92,13 @@ jobs: - name: Run unit tests # description: | - # runs unit tests with test coverage assuming that this repository contains only one module, - # with a go.mod located at the root. + # Runs unit tests with test coverage assuming that this repository contains only one module, + # with a go.mod located at the root. + # + # > NOTE + # > The -coverpkg option is important to have all coverage files containing + # > an appropriate reference to source files, so coverage may be followed accuratelt + # > on codecov UI. id: gotest shell: bash run: | @@ -83,6 +110,8 @@ jobs: ./... - name: Report test + # description: | + # This is reporting the job summary (github UI). if: ${{ success() || failure() }} id: goreport shell: bash @@ -104,8 +133,8 @@ jobs: all_tests: name: All tests # description: | - # This job regroups all tests launched as a matrix, so we may define a branch protection rule - # just on that job rather than each matrix job independently. + # This job regroups all tests launched as a matrix, so we may define a branch protection rule + # just on that job rather than each matrix job independently. needs: [ unit_tests ] # <- requires all unit_tests jobs to be successful. env: test_result: '${{ join(needs.unit_tests.outputs.*) }}' # <- this is a comma-separated list of quoted strings diff --git a/.github/workflows/local-auto-merge.yml b/.github/workflows/local-auto-merge.yml index 4cbf332..8cd8751 100644 --- a/.github/workflows/local-auto-merge.yml +++ b/.github/workflows/local-auto-merge.yml @@ -1,6 +1,5 @@ name: Dependabot auto-merge - -# This workflow mimics how a go-openapi repo would typically invoke the common workflow. +# description: This workflow mimics how a go-openapi repo would typically invoke the common workflow. on: pull_request diff --git a/.github/workflows/local-doc-update.yml b/.github/workflows/local-doc-update.yml index b178b42..6e507c0 100644 --- a/.github/workflows/local-doc-update.yml +++ b/.github/workflows/local-doc-update.yml @@ -1,6 +1,5 @@ name: doc update check - -# This workflow mimics how a go-openapi repo would typically invoke the common workflow. +# description: This workflow mimics how a go-openapi repo would typically invoke the common workflow. on: pull_request_target: diff --git a/.github/workflows/local-go-test.yml b/.github/workflows/local-go-test.yml index 259a504..d96d250 100644 --- a/.github/workflows/local-go-test.yml +++ b/.github/workflows/local-go-test.yml @@ -1,6 +1,5 @@ name: go test - -# This workflow mimics how a go-openapi repo would typically invoke the common workflow. +# description: This workflow mimics how a go-openapi repo would typically invoke the common workflow. on: push: diff --git a/ALL.md b/ALL.md new file mode 100644 index 0000000..2a01e42 --- /dev/null +++ b/ALL.md @@ -0,0 +1,7258 @@ +# Swagger 2.0 specification schema + +This folder contains the Swagger 2.0 specification schema files maintained here: + +https://github.com/reverb/swagger-spec/blob/master/schemas/v2.0# OpenAPI v2 object model [![Build Status](https://github.com/go-openapi/spec/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/spec/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/spec/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/spec) + +[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) +[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/spec/master/LICENSE) +[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/spec.svg)](https://pkg.go.dev/github.com/go-openapi/spec) +[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/spec)](https://goreportcard.com/report/github.com/go-openapi/spec) + +The object model for OpenAPI specification documents. + +### FAQ + +* What does this do? + +> 1. This package knows how to marshal and unmarshal Swagger API specifications into a golang object model +> 2. It knows how to resolve $ref and expand them to make a single root document + +* How does it play with the rest of the go-openapi packages ? + +> 1. This package is at the core of the go-openapi suite of packages and [code generator](https://github.com/go-swagger/go-swagger) +> 2. There is a [spec loading package](https://github.com/go-openapi/loads) to fetch specs as JSON or YAML from local or remote locations +> 3. There is a [spec validation package](https://github.com/go-openapi/validate) built on top of it +> 4. There is a [spec analysis package](https://github.com/go-openapi/analysis) built on top of it, to analyze, flatten, fix and merge spec documents + +* Does this library support OpenAPI 3? + +> No. +> This package currently only supports OpenAPI 2.0 (aka Swagger 2.0). +> There is no plan to make it evolve toward supporting OpenAPI 3.x. +> This [discussion thread](https://github.com/go-openapi/spec/issues/21) relates the full story. +> +> An early attempt to support Swagger 3 may be found at: https://github.com/go-openapi/spec3 + +* Does the unmarshaling support YAML? + +> Not directly. The exposed types know only how to unmarshal from JSON. +> +> In order to load a YAML document as a Swagger spec, you need to use the loaders provided by +> github.com/go-openapi/loads +> +> Take a look at the example there: https://pkg.go.dev/github.com/go-openapi/loads#example-Spec +> +> See also https://github.com/go-openapi/spec/issues/164 + +* How can I validate a spec? + +> Validation is provided by [the validate package](http://github.com/go-openapi/validate) + +* Why do we have an `ID` field for `Schema` which is not part of the swagger spec? + +> We found jsonschema compatibility more important: since `id` in jsonschema influences +> how `$ref` are resolved. +> This `id` does not conflict with any property named `id`. +> +> See also https://github.com/go-openapi/spec/issues/23 +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at ivan+abuse@flanders.co.nz. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ +## Contribution Guidelines + +### Pull requests are always welcome + +We are always thrilled to receive pull requests, and do our best to +process them as fast as possible. Not sure if that typo is worth a pull +request? Do it! We will appreciate it. + +If your pull request is not accepted on the first try, don't be +discouraged! If there's a problem with the implementation, hopefully you +received feedback on what to improve. + +We're trying very hard to keep go-swagger lean and focused. We don't want it +to do everything for everybody. This means that we might decide against +incorporating a new feature. However, there might be a way to implement +that feature *on top of* go-swagger. + + +### Conventions + +Fork the repo and make changes on your fork in a feature branch: + +- If it's a bugfix branch, name it XXX-something where XXX is the number of the + issue +- If it's a feature branch, create an enhancement issue to announce your + intentions, and name it XXX-something where XXX is the number of the issue. + +Submit unit tests for your changes. Go has a great test framework built in; use +it! Take a look at existing tests for inspiration. Run the full test suite on +your branch before submitting a pull request. + +Update the documentation when creating or modifying features. Test +your documentation changes for clarity, concision, and correctness, as +well as a clean documentation build. See ``docs/README.md`` for more +information on building the docs and how docs get released. + +Write clean code. Universally formatted code promotes ease of writing, reading, +and maintenance. Always run `gofmt -s -w file.go` on each changed file before +committing your changes. Most editors have plugins that do this automatically. + +Pull requests descriptions should be as clear as possible and include a +reference to all the issues that they address. + +Pull requests must not contain commits from other users or branches. + +Commit messages must start with a capitalized and short summary (max. 50 +chars) written in the imperative, followed by an optional, more detailed +explanatory text which is separated from the summary by an empty line. + +Code review comments may be added to your pull request. Discuss, then make the +suggested modifications and push additional commits to your feature branch. Be +sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you +comment. + +Before the pull request is merged, make sure that you squash your commits into +logical units of work using `git rebase -i` and `git push -f`. After every +commit the test suite should be passing. Include documentation changes in the +same commit so that a revert would remove all traces of the feature or fix. + +Commits that fix or close an issue should include a reference like `Closes #XXX` +or `Fixes #XXX`, which will automatically close the issue when merged. + +### Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](http://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign off when creating the git commit via `git commit -s`. +# gojsonreference [![Build Status](https://github.com/go-openapi/jsonreference/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/jsonreference/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/jsonreference/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/jsonreference) + +[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) +[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/jsonreference/master/LICENSE) +[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/jsonreference.svg)](https://pkg.go.dev/github.com/go-openapi/jsonreference) +[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/jsonreference)](https://goreportcard.com/report/github.com/go-openapi/jsonreference) + +An implementation of JSON Reference - Go language + +## Status +Feature complete. Stable API + +## Dependencies +* https://github.com/go-openapi/jsonpointer + +## References + +* http://tools.ietf.org/html/draft-ietf-appsawg-json-pointer-07 +* http://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03 +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at ivan+abuse@flanders.co.nz. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ +## Contribution Guidelines + +### Pull requests are always welcome + +We are always thrilled to receive pull requests, and do our best to +process them as fast as possible. Not sure if that typo is worth a pull +request? Do it! We will appreciate it. + +If your pull request is not accepted on the first try, don't be +discouraged! If there's a problem with the implementation, hopefully you +received feedback on what to improve. + +We're trying very hard to keep go-swagger lean and focused. We don't want it +to do everything for everybody. This means that we might decide against +incorporating a new feature. However, there might be a way to implement +that feature *on top of* go-swagger. + + +### Conventions + +Fork the repo and make changes on your fork in a feature branch: + +- If it's a bugfix branch, name it XXX-something where XXX is the number of the + issue +- If it's a feature branch, create an enhancement issue to announce your + intentions, and name it XXX-something where XXX is the number of the issue. + +Submit unit tests for your changes. Go has a great test framework built in; use +it! Take a look at existing tests for inspiration. Run the full test suite on +your branch before submitting a pull request. + +Update the documentation when creating or modifying features. Test +your documentation changes for clarity, concision, and correctness, as +well as a clean documentation build. See ``docs/README.md`` for more +information on building the docs and how docs get released. + +Write clean code. Universally formatted code promotes ease of writing, reading, +and maintenance. Always run `gofmt -s -w file.go` on each changed file before +committing your changes. Most editors have plugins that do this automatically. + +Pull requests descriptions should be as clear as possible and include a +reference to all the issues that they address. + +Pull requests must not contain commits from other users or branches. + +Commit messages must start with a capitalized and short summary (max. 50 +chars) written in the imperative, followed by an optional, more detailed +explanatory text which is separated from the summary by an empty line. + +Code review comments may be added to your pull request. Discuss, then make the +suggested modifications and push additional commits to your feature branch. Be +sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you +comment. + +Before the pull request is merged, make sure that you squash your commits into +logical units of work using `git rebase -i` and `git push -f`. After every +commit the test suite should be passing. Include documentation changes in the +same commit so that a revert would remove all traces of the feature or fix. + +Commits that fix or close an issue should include a reference like `Closes #XXX` +or `Fixes #XXX`, which will automatically close the issue when merged. + +### Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](http://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign off when creating the git commit via `git commit -s`. +# doc + +Documentation check and generation tools. +# ci-workflows[![Build Status](https://github.com/go-openapi/ci-workflows/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/ci-workflows/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/ci-workflows/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/ci-workflows) + +[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) +[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/ci-workflows/master/LICENSE) +[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/ci-workflows.svg)](https://pkg.go.dev/github.com/go-openapi/ci-workflows) +[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/ci-workflows)](https://goreportcard.com/report/github.com/go-openapi/ci-workflows) + +Common Continuous Integration (`CI`) workflows and setup for go-openapi repos. + +* shared github action workflows +* shared `dependabot` configuration (TODO) +* shared `golangci-lint` configuration (**BLOCKED**) + +> NOTE: at this moment, it is difficult to share the golangci-lint config, +> so that one is not shared yet. + +## Motivation + +It took a while, but we eventually managed to align all checks, tests and +dependabot rules declared in the family of go-openapi repos. + +Now we'd like to be able to maintain, enrich and improve these checks without +worrying too much about the burden to replicate it about a dozen times. + +## Contemplated enhancements + +In no particular order: + +* [x] ui: enrich github actions UI with a job summary +* [x] doc: add markdown linting for docs +* [x] doc: add spellcheck for docs (and code?) +* [ ] version common workflows, so we can limit the impact of a change +* [ ] build: verify that go.sum cache for tests works (should be enabled) +* [ ] share mono repo workflows (see github.com/go-openapi/swag/.github/workflows) +* [ ] lint: manage somehow to share golangci config (with local merge) +* [ ] dependencies: manage somehow to share / replicate dependabot config +* [ ] lint: golangci-lint: check valid PR comments etc +* [ ] lint: use non-blocking, scheduled, proactive full linting to check for + the impact of new linters, new go versions etc +* [ ] doc: (possibility) take over hugo & doc gen part from go-swagger +* [ ] (possibility) take over release part from go-swagger +* [ ] doc: produce hugo github page with all latest tagged versions + (incl. mono repo) +* [ ] add bot to filter PRs, issues +* [ ] check with github API that all repo settings (branch protection rules, etc) + are identical +* [ ] comment PRs and issues +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at ivan+abuse@flanders.co.nz. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ +## Contribution Guidelines + +### Pull requests are always welcome + +We are always thrilled to receive pull requests, and do our best to +process them as fast as possible. Not sure if that typo is worth a pull +request? Do it! We will appreciate it. + +If your pull request is not accepted on the first try, don't be +discouraged! If there's a problem with the implementation, hopefully you +received feedback on what to improve. + +We're trying very hard to keep go-swagger lean and focused. We don't want it +to do everything for everybody. This means that we might decide against +incorporating a new feature. However, there might be a way to implement +that feature *on top of* go-swagger. + + +### Conventions + +Fork the repo and make changes on your fork in a feature branch: + +- If it's a bugfix branch, name it XXX-something where XXX is the number of the + issue +- If it's a feature branch, create an enhancement issue to announce your + intentions, and name it XXX-something where XXX is the number of the issue. + +Submit unit tests for your changes. Go has a great test framework built in; use +it! Take a look at existing tests for inspiration. Run the full test suite on +your branch before submitting a pull request. + +Update the documentation when creating or modifying features. Test +your documentation changes for clarity, concision, and correctness, as +well as a clean documentation build. See ``docs/README.md`` for more +information on building the docs and how docs get released. + +Write clean code. Universally formatted code promotes ease of writing, reading, +and maintenance. Always run `gofmt -s -w file.go` on each changed file before +committing your changes. Most editors have plugins that do this automatically. + +Pull requests descriptions should be as clear as possible and include a +reference to all the issues that they address. + +Pull requests must not contain commits from other users or branches. + +Commit messages must start with a capitalized and short summary (max. 50 +chars) written in the imperative, followed by an optional, more detailed +explanatory text which is separated from the summary by an empty line. + +Code review comments may be added to your pull request. Discuss, then make the +suggested modifications and push additional commits to your feature branch. Be +sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you +comment. + +Before the pull request is merged, make sure that you squash your commits into +logical units of work using `git rebase -i` and `git push -f`. After every +commit the test suite should be passing. Include documentation changes in the +same commit so that a revert would remove all traces of the feature or fix. + +Commits that fix or close an issue should include a reference like `Closes #XXX` +or `Fixes #XXX`, which will automatically close the issue when merged. + +### Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](http://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign off when creating the git commit via `git commit -s`. +# Audit + +Audit of github repos to check for inconsistencies. +# inflect [![Build Status](https://github.com/go-openapi/inflect/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/inflect/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/inflect/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/inflect) + +[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) +[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/inflect/master/LICENSE) +[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/inflect.svg)](https://pkg.go.dev/github.com/go-openapi/inflect) +[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/inflect)](https://goreportcard.com/report/github.com/go-openapi/inflect) + +A package to pluralize words. + +Originally forked from fork of https://bitbucket.org/pkg/inflect under a MIT License. + +A golang library applying grammar rules to English words. + +> This package provides a basic set of functions applying +> grammar rules to inflect English words, modify case style +> (Capitalize, camelCase, snake_case, etc.). +> +> Acronyms are properly handled. A common use case is word pluralization. + + +This library is not used at all by other go-openapi packages and is somewhat redundant with +go-openapi/swag/mangling (for camelcase etc). + +Currently we have one single dependency in one place in a go-swagger template (used as a funcmap). + +## Note to maintainers + +* Aug. 2025: CI workflows have now moved to a shared repository go-openapi/ci-workflows +## Contribution Guidelines + +### Pull requests are always welcome + +We are always thrilled to receive pull requests, and do our best to +process them as fast as possible. Not sure if that typo is worth a pull +request? Do it! We will appreciate it. + +If your pull request is not accepted on the first try, don't be +discouraged! If there's a problem with the implementation, hopefully you +received feedback on what to improve. + +We're trying very hard to keep go-swagger lean and focused. We don't want it +to do everything for everybody. This means that we might decide against +incorporating a new feature. However, there might be a way to implement +that feature *on top of* go-swagger. + + +### Conventions + +Fork the repo and make changes on your fork in a feature branch: + +- If it's a bugfix branch, name it XXX-something where XXX is the number of the + issue +- If it's a feature branch, create an enhancement issue to announce your + intentions, and name it XXX-something where XXX is the number of the issue. + +Submit unit tests for your changes. Go has a great test framework built in; use +it! Take a look at existing tests for inspiration. Run the full test suite on +your branch before submitting a pull request. + +Update the documentation when creating or modifying features. Test +your documentation changes for clarity, concision, and correctness, as +well as a clean documentation build. See ``docs/README.md`` for more +information on building the docs and how docs get released. + +Write clean code. Universally formatted code promotes ease of writing, reading, +and maintenance. Always run `gofmt -s -w file.go` on each changed file before +committing your changes. Most editors have plugins that do this automatically. + +Pull requests descriptions should be as clear as possible and include a +reference to all the issues that they address. + +Pull requests must not contain commits from other users or branches. + +Commit messages must start with a capitalized and short summary (max. 50 +chars) written in the imperative, followed by an optional, more detailed +explanatory text which is separated from the summary by an empty line. + +Code review comments may be added to your pull request. Discuss, then make the +suggested modifications and push additional commits to your feature branch. Be +sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you +comment. + +Before the pull request is merged, make sure that you squash your commits into +logical units of work using `git rebase -i` and `git push -f`. After every +commit the test suite should be passing. Include documentation changes in the +same commit so that a revert would remove all traces of the feature or fix. + +Commits that fix or close an issue should include a reference like `Closes #XXX` +or `Fixes #XXX`, which will automatically close the issue when merged. + +### Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](http://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign off when creating the git commit via `git commit -s`. +# Validation helpers [![Build Status](https://github.com/go-openapi/validate/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/validate/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/validate/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/validate) + +[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) +[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/validate/master/LICENSE) +[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/validate.svg)](https://pkg.go.dev/github.com/go-openapi/validate) +[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/validate)](https://goreportcard.com/report/github.com/go-openapi/validate) + +This package provides helpers to validate Swagger 2.0. specification (aka OpenAPI 2.0). + +Reference can be found here: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md. + +## What's inside? + +* A validator for Swagger specifications +* A validator for JSON schemas draft4 +* Helper functions to validate individual values (used by code generated by [go-swagger](https://github.com/go-swagger/go-swagger)). + * Required, RequiredNumber, RequiredString + * ReadOnly + * UniqueItems, MaxItems, MinItems + * Enum, EnumCase + * Pattern, MinLength, MaxLength + * Minimum, Maximum, MultipleOf + * FormatOf + +[Documentation](https://pkg.go.dev/github.com/go-openapi/validate) + +## FAQ + +* Does this library support OpenAPI 3? + +> No. +> This package currently only supports OpenAPI 2.0 (aka Swagger 2.0). +> There is no plan to make it evolve toward supporting OpenAPI 3.x. +> This [discussion thread](https://github.com/go-openapi/spec/issues/21) relates the full story. +> +> An early attempt to support Swagger 3 may be found at: https://github.com/go-openapi/spec3 +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at ivan+abuse@flanders.co.nz. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ +## Contribution Guidelines + +### Pull requests are always welcome + +We are always thrilled to receive pull requests, and do our best to +process them as fast as possible. Not sure if that typo is worth a pull +request? Do it! We will appreciate it. + +If your pull request is not accepted on the first try, don't be +discouraged! If there's a problem with the implementation, hopefully you +received feedback on what to improve. + +We're trying very hard to keep go-swagger lean and focused. We don't want it +to do everything for everybody. This means that we might decide against +incorporating a new feature. However, there might be a way to implement +that feature *on top of* go-swagger. + + +### Conventions + +Fork the repo and make changes on your fork in a feature branch: + +- If it's a bugfix branch, name it XXX-something where XXX is the number of the + issue +- If it's a feature branch, create an enhancement issue to announce your + intentions, and name it XXX-something where XXX is the number of the issue. + +Submit unit tests for your changes. Go has a great test framework built in; use +it! Take a look at existing tests for inspiration. Run the full test suite on +your branch before submitting a pull request. + +Update the documentation when creating or modifying features. Test +your documentation changes for clarity, concision, and correctness, as +well as a clean documentation build. See ``docs/README.md`` for more +information on building the docs and how docs get released. + +Write clean code. Universally formatted code promotes ease of writing, reading, +and maintenance. Always run `gofmt -s -w file.go` on each changed file before +committing your changes. Most editors have plugins that do this automatically. + +Pull requests descriptions should be as clear as possible and include a +reference to all the issues that they address. + +Pull requests must not contain commits from other users or branches. + +Commit messages must start with a capitalized and short summary (max. 50 +chars) written in the imperative, followed by an optional, more detailed +explanatory text which is separated from the summary by an empty line. + +Code review comments may be added to your pull request. Discuss, then make the +suggested modifications and push additional commits to your feature branch. Be +sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you +comment. + +Before the pull request is merged, make sure that you squash your commits into +logical units of work using `git rebase -i` and `git push -f`. After every +commit the test suite should be passing. Include documentation changes in the +same commit so that a revert would remove all traces of the feature or fix. + +Commits that fix or close an issue should include a reference like `Closes #XXX` +or `Fixes #XXX`, which will automatically close the issue when merged. + +### Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](http://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign off when creating the git commit via `git commit -s`. +# Benchmark + +Validating the Kubernetes Swagger API + +## v0.22.6: 60,000,000 allocs +``` +goos: linux +goarch: amd64 +pkg: github.com/go-openapi/validate +cpu: AMD Ryzen 7 5800X 8-Core Processor +Benchmark_KubernetesSpec/validating_kubernetes_API-16 1 8549863982 ns/op 7067424936 B/op 59583275 allocs/op +``` + +## After refact PR: minor but noticable improvements: 25,000,000 allocs +``` +go test -bench Spec +goos: linux +goarch: amd64 +pkg: github.com/go-openapi/validate +cpu: AMD Ryzen 7 5800X 8-Core Processor +Benchmark_KubernetesSpec/validating_kubernetes_API-16 1 4064535557 ns/op 3379715592 B/op 25320330 allocs/op +``` + +## After reduce GC pressure PR: 17,000,000 allocs +``` +goos: linux +goarch: amd64 +pkg: github.com/go-openapi/validate +cpu: AMD Ryzen 7 5800X 8-Core Processor +Benchmark_KubernetesSpec/validating_kubernetes_API-16 1 3758414145 ns/op 2593881496 B/op 17111373 allocs/op +``` +# Denco [![Build Status](https://travis-ci.org/naoina/denco.png?branch=master)](https://travis-ci.org/naoina/denco) + +The fast and flexible HTTP request router for [Go](http://golang.org). + +Denco is based on Double-Array implementation of [Kocha-urlrouter](https://github.com/naoina/kocha-urlrouter). +However, Denco is optimized and some features added. + +## Features + +* Fast (See [go-http-routing-benchmark](https://github.com/naoina/go-http-routing-benchmark)) +* [URL patterns](#url-patterns) (`/foo/:bar` and `/foo/*wildcard`) +* Small (but enough) URL router API +* HTTP request multiplexer like `http.ServeMux` + +## Installation + + go get -u github.com/go-openapi/runtime/middleware/denco + +## Using as HTTP request multiplexer + +```go +package main + +import ( + "fmt" + "log" + "net/http" + + "github.com/go-openapi/runtime/middleware/denco" +) + +func Index(w http.ResponseWriter, r *http.Request, params denco.Params) { + fmt.Fprintf(w, "Welcome to Denco!\n") +} + +func User(w http.ResponseWriter, r *http.Request, params denco.Params) { + fmt.Fprintf(w, "Hello %s!\n", params.Get("name")) +} + +func main() { + mux := denco.NewMux() + handler, err := mux.Build([]denco.Handler{ + mux.GET("/", Index), + mux.GET("/user/:name", User), + mux.POST("/user/:name", User), + }) + if err != nil { + panic(err) + } + log.Fatal(http.ListenAndServe(":8080", handler)) +} +``` + +## Using as URL router + +```go +package main + +import ( + "fmt" + + "github.com/go-openapi/runtime/middleware/denco" +) + +type route struct { + name string +} + +func main() { + router := denco.New() + router.Build([]denco.Record{ + {"/", &route{"root"}}, + {"/user/:id", &route{"user"}}, + {"/user/:name/:id", &route{"username"}}, + {"/static/*filepath", &route{"static"}}, + }) + + data, params, found := router.Lookup("/") + // print `&main.route{name:"root"}, denco.Params(nil), true`. + fmt.Printf("%#v, %#v, %#v\n", data, params, found) + + data, params, found = router.Lookup("/user/hoge") + // print `&main.route{name:"user"}, denco.Params{denco.Param{Name:"id", Value:"hoge"}}, true`. + fmt.Printf("%#v, %#v, %#v\n", data, params, found) + + data, params, found = router.Lookup("/user/hoge/7") + // print `&main.route{name:"username"}, denco.Params{denco.Param{Name:"name", Value:"hoge"}, denco.Param{Name:"id", Value:"7"}}, true`. + fmt.Printf("%#v, %#v, %#v\n", data, params, found) + + data, params, found = router.Lookup("/static/path/to/file") + // print `&main.route{name:"static"}, denco.Params{denco.Param{Name:"filepath", Value:"path/to/file"}}, true`. + fmt.Printf("%#v, %#v, %#v\n", data, params, found) +} +``` + +See [Godoc](http://godoc.org/github.com/go-openapi/runtime/middleware/denco) for more details. + +## Getting the value of path parameter + +You can get the value of path parameter by 2 ways. + +1. Using [`denco.Params.Get`](http://godoc.org/github.com/go-openapi/runtime/middleware/denco#Params.Get) method +2. Find by loop + +```go +package main + +import ( + "fmt" + + "github.com/go-openapi/runtime/middleware/denco" +) + +func main() { + router := denco.New() + if err := router.Build([]denco.Record{ + {"/user/:name/:id", "route1"}, + }); err != nil { + panic(err) + } + + // 1. Using denco.Params.Get method. + _, params, _ := router.Lookup("/user/alice/1") + name := params.Get("name") + if name != "" { + fmt.Printf("Hello %s.\n", name) // prints "Hello alice.". + } + + // 2. Find by loop. + for _, param := range params { + if param.Name == "name" { + fmt.Printf("Hello %s.\n", name) // prints "Hello alice.". + } + } +} +``` + +## URL patterns + +Denco's route matching strategy is "most nearly matching". + +When routes `/:name` and `/alice` have been built, URI `/alice` matches the route `/alice`, not `/:name`. +Because URI `/alice` is more match with the route `/alice` than `/:name`. + +For more example, when routes below have been built: + +``` +/user/alice +/user/:name +/user/:name/:id +/user/alice/:id +/user/:id/bob +``` + +Routes matching are: + +``` +/user/alice => "/user/alice" (no match with "/user/:name") +/user/bob => "/user/:name" +/user/naoina/1 => "/user/:name/1" +/user/alice/1 => "/user/alice/:id" (no match with "/user/:name/:id") +/user/1/bob => "/user/:id/bob" (no match with "/user/:name/:id") +/user/alice/bob => "/user/alice/:id" (no match with "/user/:name/:id" and "/user/:id/bob") +``` + +## Limitation + +Denco has some limitations below. + +* Number of param records (such as `/:name`) must be less than 2^22 +* Number of elements of internal slice must be less than 2^22 + +## Benchmarks + + cd $GOPATH/github.com/go-openapi/runtime/middleware/denco + go test -bench . -benchmem + +## License + +Denco is licensed under the MIT License. +# runtime [![Build Status](https://github.com/go-openapi/runtime/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/runtime/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/runtime/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/runtime) + +[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) +[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/runtime/master/LICENSE) +[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/runtime.svg)](https://pkg.go.dev/github.com/go-openapi/runtime) +[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/runtime)](https://goreportcard.com/report/github.com/go-openapi/runtime) + +# go OpenAPI toolkit runtime + +The runtime component for use in code generation or as untyped usage. +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at ivan+abuse@flanders.co.nz. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ +## Contribution Guidelines + +### Pull requests are always welcome + +We are always thrilled to receive pull requests, and do our best to +process them as fast as possible. Not sure if that typo is worth a pull +request? Do it! We will appreciate it. + +If your pull request is not accepted on the first try, don't be +discouraged! If there's a problem with the implementation, hopefully you +received feedback on what to improve. + +We're trying very hard to keep go-swagger lean and focused. We don't want it +to do everything for everybody. This means that we might decide against +incorporating a new feature. However, there might be a way to implement +that feature *on top of* go-swagger. + + +### Conventions + +Fork the repo and make changes on your fork in a feature branch: + +- If it's a bugfix branch, name it XXX-something where XXX is the number of the + issue +- If it's a feature branch, create an enhancement issue to announce your + intentions, and name it XXX-something where XXX is the number of the issue. + +Submit unit tests for your changes. Go has a great test framework built in; use +it! Take a look at existing tests for inspiration. Run the full test suite on +your branch before submitting a pull request. + +Update the documentation when creating or modifying features. Test +your documentation changes for clarity, concision, and correctness, as +well as a clean documentation build. See ``docs/README.md`` for more +information on building the docs and how docs get released. + +Write clean code. Universally formatted code promotes ease of writing, reading, +and maintenance. Always run `gofmt -s -w file.go` on each changed file before +committing your changes. Most editors have plugins that do this automatically. + +Pull requests descriptions should be as clear as possible and include a +reference to all the issues that they address. + +Pull requests must not contain commits from other users or branches. + +Commit messages must start with a capitalized and short summary (max. 50 +chars) written in the imperative, followed by an optional, more detailed +explanatory text which is separated from the summary by an empty line. + +Code review comments may be added to your pull request. Discuss, then make the +suggested modifications and push additional commits to your feature branch. Be +sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you +comment. + +Before the pull request is merged, make sure that you squash your commits into +logical units of work using `git rebase -i` and `git push -f`. After every +commit the test suite should be passing. Include documentation changes in the +same commit so that a revert would remove all traces of the feature or fix. + +Commits that fix or close an issue should include a reference like `Closes #XXX` +or `Fixes #XXX`, which will automatically close the issue when merged. + +### Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](http://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign off when creating the git commit via `git commit -s`. +# Loads OAI specs [![Build Status](https://github.com/go-openapi/loads/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/loads/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/loads/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/loads) + +[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/loads/master/LICENSE) [![GoDoc](https://godoc.org/github.com/go-openapi/loads?status.svg)](http://godoc.org/github.com/go-openapi/loads) +[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/loads)](https://goreportcard.com/report/github.com/go-openapi/loads) + +Loading of OAI specification documents from local or remote locations. Supports JSON and YAML documents. +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at ivan+abuse@flanders.co.nz. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ +## Contribution Guidelines + +### Pull requests are always welcome + +We are always thrilled to receive pull requests, and do our best to +process them as fast as possible. Not sure if that typo is worth a pull +request? Do it! We will appreciate it. + +If your pull request is not accepted on the first try, don't be +discouraged! If there's a problem with the implementation, hopefully you +received feedback on what to improve. + +We're trying very hard to keep go-swagger lean and focused. We don't want it +to do everything for everybody. This means that we might decide against +incorporating a new feature. However, there might be a way to implement +that feature *on top of* go-swagger. + + +### Conventions + +Fork the repo and make changes on your fork in a feature branch: + +- If it's a bugfix branch, name it XXX-something where XXX is the number of the + issue +- If it's a feature branch, create an enhancement issue to announce your + intentions, and name it XXX-something where XXX is the number of the issue. + +Submit unit tests for your changes. Go has a great test framework built in; use +it! Take a look at existing tests for inspiration. Run the full test suite on +your branch before submitting a pull request. + +Update the documentation when creating or modifying features. Test +your documentation changes for clarity, concision, and correctness, as +well as a clean documentation build. See ``docs/README.md`` for more +information on building the docs and how docs get released. + +Write clean code. Universally formatted code promotes ease of writing, reading, +and maintenance. Always run `gofmt -s -w file.go` on each changed file before +committing your changes. Most editors have plugins that do this automatically. + +Pull requests descriptions should be as clear as possible and include a +reference to all the issues that they address. + +Pull requests must not contain commits from other users or branches. + +Commit messages must start with a capitalized and short summary (max. 50 +chars) written in the imperative, followed by an optional, more detailed +explanatory text which is separated from the summary by an empty line. + +Code review comments may be added to your pull request. Discuss, then make the +suggested modifications and push additional commits to your feature branch. Be +sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you +comment. + +Before the pull request is merged, make sure that you squash your commits into +logical units of work using `git rebase -i` and `git push -f`. After every +commit the test suite should be passing. Include documentation changes in the +same commit so that a revert would remove all traces of the feature or fix. + +Commits that fix or close an issue should include a reference like `Closes #XXX` +or `Fixes #XXX`, which will automatically close the issue when merged. + +### Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](http://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign off when creating the git commit via `git commit -s`. +# OpenAPI analysis [![Build Status](https://github.com/go-openapi/analysis/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/analysis/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/analysis/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/analysis) + +[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) +[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/analysis/master/LICENSE) +[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/analysis.svg)](https://pkg.go.dev/github.com/go-openapi/analysis) +[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/analysis)](https://goreportcard.com/report/github.com/go-openapi/analysis) + + +A foundational library to analyze an OAI specification document for easier reasoning about the content. + +## What's inside? + +* An analyzer providing methods to walk the functional content of a specification +* A spec flattener producing a self-contained document bundle, while preserving `$ref`s +* A spec merger ("mixin") to merge several spec documents into a primary spec +* A spec "fixer" ensuring that response descriptions are non empty + +[Documentation](https://pkg.go.dev/github.com/go-openapi/analysis) + +## FAQ + +* Does this library support OpenAPI 3? + +> No. +> This package currently only supports OpenAPI 2.0 (aka Swagger 2.0). +> There is no plan to make it evolve toward supporting OpenAPI 3.x. +> This [discussion thread](https://github.com/go-openapi/spec/issues/21) relates the full story. +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at ivan+abuse@flanders.co.nz. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ +## Contribution Guidelines + +### Pull requests are always welcome + +We are always thrilled to receive pull requests, and do our best to +process them as fast as possible. Not sure if that typo is worth a pull +request? Do it! We will appreciate it. + +If your pull request is not accepted on the first try, don't be +discouraged! If there's a problem with the implementation, hopefully you +received feedback on what to improve. + +We're trying very hard to keep go-swagger lean and focused. We don't want it +to do everything for everybody. This means that we might decide against +incorporating a new feature. However, there might be a way to implement +that feature *on top of* go-swagger. + + +### Conventions + +Fork the repo and make changes on your fork in a feature branch: + +- If it's a bugfix branch, name it XXX-something where XXX is the number of the + issue +- If it's a feature branch, create an enhancement issue to announce your + intentions, and name it XXX-something where XXX is the number of the issue. + +Submit unit tests for your changes. Go has a great test framework built in; use +it! Take a look at existing tests for inspiration. Run the full test suite on +your branch before submitting a pull request. + +Update the documentation when creating or modifying features. Test +your documentation changes for clarity, concision, and correctness, as +well as a clean documentation build. See ``docs/README.md`` for more +information on building the docs and how docs get released. + +Write clean code. Universally formatted code promotes ease of writing, reading, +and maintenance. Always run `gofmt -s -w file.go` on each changed file before +committing your changes. Most editors have plugins that do this automatically. + +Pull requests descriptions should be as clear as possible and include a +reference to all the issues that they address. + +Pull requests must not contain commits from other users or branches. + +Commit messages must start with a capitalized and short summary (max. 50 +chars) written in the imperative, followed by an optional, more detailed +explanatory text which is separated from the summary by an empty line. + +Code review comments may be added to your pull request. Discuss, then make the +suggested modifications and push additional commits to your feature branch. Be +sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you +comment. + +Before the pull request is merged, make sure that you squash your commits into +logical units of work using `git rebase -i` and `git push -f`. After every +commit the test suite should be passing. Include documentation changes in the +same commit so that a revert would remove all traces of the feature or fix. + +Commits that fix or close an issue should include a reference like `Closes #XXX` +or `Fixes #XXX`, which will automatically close the issue when merged. + +### Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](http://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign off when creating the git commit via `git commit -s`. +# Benchmarking name mangling utilities + +```bash +go test -bench XXX -run XXX -benchtime 30s +``` + +## Benchmarks at b3e7a5386f996177e4808f11acb2aa93a0f660df + +``` +goos: linux +goarch: amd64 +pkg: github.com/go-openapi/swag +cpu: Intel(R) Core(TM) i5-6200U CPU @ 2.30GHz +BenchmarkToXXXName/ToGoName-4 862623 44101 ns/op 10450 B/op 732 allocs/op +BenchmarkToXXXName/ToVarName-4 853656 40728 ns/op 10468 B/op 734 allocs/op +BenchmarkToXXXName/ToFileName-4 1268312 27813 ns/op 9785 B/op 617 allocs/op +BenchmarkToXXXName/ToCommandName-4 1276322 27903 ns/op 9785 B/op 617 allocs/op +BenchmarkToXXXName/ToHumanNameLower-4 895334 40354 ns/op 10472 B/op 731 allocs/op +BenchmarkToXXXName/ToHumanNameTitle-4 882441 40678 ns/op 10566 B/op 749 allocs/op +``` + +## Benchmarks after PR #79 + +~ x10 performance improvement and ~ /100 memory allocations. + +``` +goos: linux +goarch: amd64 +pkg: github.com/go-openapi/swag +cpu: Intel(R) Core(TM) i5-6200U CPU @ 2.30GHz +BenchmarkToXXXName/ToGoName-4 9595830 3991 ns/op 42 B/op 5 allocs/op +BenchmarkToXXXName/ToVarName-4 9194276 3984 ns/op 62 B/op 7 allocs/op +BenchmarkToXXXName/ToFileName-4 17002711 2123 ns/op 147 B/op 7 allocs/op +BenchmarkToXXXName/ToCommandName-4 16772926 2111 ns/op 147 B/op 7 allocs/op +BenchmarkToXXXName/ToHumanNameLower-4 9788331 3749 ns/op 92 B/op 6 allocs/op +BenchmarkToXXXName/ToHumanNameTitle-4 9188260 3941 ns/op 104 B/op 6 allocs/op +``` + +``` +goos: linux +goarch: amd64 +pkg: github.com/go-openapi/swag +cpu: AMD Ryzen 7 5800X 8-Core Processor +BenchmarkToXXXName/ToGoName-16 18527378 1972 ns/op 42 B/op 5 allocs/op +BenchmarkToXXXName/ToVarName-16 15552692 2093 ns/op 62 B/op 7 allocs/op +BenchmarkToXXXName/ToFileName-16 32161176 1117 ns/op 147 B/op 7 allocs/op +BenchmarkToXXXName/ToCommandName-16 32256634 1137 ns/op 147 B/op 7 allocs/op +BenchmarkToXXXName/ToHumanNameLower-16 18599661 1946 ns/op 92 B/op 6 allocs/op +BenchmarkToXXXName/ToHumanNameTitle-16 17581353 2054 ns/op 105 B/op 6 allocs/op +``` + +## Benchmarks at d7d2d1b895f5b6747afaff312dd2a402e69e818b + +go1.24 + +``` +goos: linux +goarch: amd64 +pkg: github.com/go-openapi/swag +cpu: AMD Ryzen 7 5800X 8-Core Processor +BenchmarkToXXXName/ToGoName-16 19757858 1881 ns/op 42 B/op 5 allocs/op +BenchmarkToXXXName/ToVarName-16 17494111 2094 ns/op 74 B/op 7 allocs/op +BenchmarkToXXXName/ToFileName-16 28161226 1492 ns/op 158 B/op 7 allocs/op +BenchmarkToXXXName/ToCommandName-16 23787333 1489 ns/op 158 B/op 7 allocs/op +BenchmarkToXXXName/ToHumanNameLower-16 17537257 2030 ns/op 103 B/op 6 allocs/op +BenchmarkToXXXName/ToHumanNameTitle-16 16977453 2156 ns/op 105 B/op 6 allocs/op +``` + +## Benchmarks after PR #106 + +Moving the scope of everything down to a struct allowed to reduce a bit garbage and pooling. + +On top of that, ToGoName (and thus ToVarName) have been subject to a minor optimization, removing a few allocations. + +Overall timings improve by ~ -10%. + +go1.24 + +``` +goos: linux +goarch: amd64 +pkg: github.com/go-openapi/swag/mangling +cpu: AMD Ryzen 7 5800X 8-Core Processor +BenchmarkToXXXName/ToGoName-16 22496130 1618 ns/op 31 B/op 3 allocs/op +BenchmarkToXXXName/ToVarName-16 22538068 1618 ns/op 33 B/op 3 allocs/op +BenchmarkToXXXName/ToFileName-16 27722977 1236 ns/op 105 B/op 6 allocs/op +BenchmarkToXXXName/ToCommandName-16 27967395 1258 ns/op 105 B/op 6 allocs/op +BenchmarkToXXXName/ToHumanNameLower-16 18587901 1917 ns/op 103 B/op 6 allocs/op +BenchmarkToXXXName/ToHumanNameTitle-16 17193208 2019 ns/op 108 B/op 7 allocs/op +``` +# Swag [![Build Status](https://github.com/go-openapi/swag/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/swag/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/swag/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/swag) + +[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) +[![license](https://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/swag/master/LICENSE) +[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/swag.svg)](https://pkg.go.dev/github.com/go-openapi/swag) +[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/swag)](https://goreportcard.com/report/github.com/go-openapi/swag) + +Package `swag` contains a bunch of helper functions for go-openapi and go-swagger projects. + +You may also use it standalone for your projects. + +> `swag` is one of the foundational building blocks of the go-openapi initiative. +> +> Most repositories in `github.com/go-openapi/...` depend on it in some way. +> So does the CLI tool `github.com/go-swagger/go-swagger`, +> and the code generated by this tool. + +## Contents + +`go-openapi/swag` now exposes a collection of relatively independent modules. + +Here is what is inside: + +* Module `cmdutils` + + * [x] utilities to work with CLIs + +* Module `conv` + + * [x] convert between values and pointers for any types + * [x] convert from string to builtin types (wraps `strconv`) + * [x] require `./typeutils` (test dependency) + +* Module `fileutils` + + * [x] file upload type + * [x] search in path (deprecated) + +* Module `jsonname` + + * [x] infer JSON names from go properties + +* Module `jsonutils` + + * [x] fast json concatenation + * [x] read and write JSON from and to dynamic go data structures + * [x] require `github.com/mailru/easyjson` + +* Module `loading` + + * [x] load from file or http + * [x] require `./yamlutils` + +* Module `mangling` + + * [x] name mangling for go + +* Module `netutils` + + * [x] host, port from address + +* Module `stringutils` + + * [x] search in slice (with case-insensitive) + * [x] split/join query parameters as arrays + +* Module `typeutils` + + * [x] check the zero value for any type + +* Module `yamlutils` + + * [x] converting YAML to JSON + * [x] loading YAML into a dynamic YAML document + * [x] require `./jsonutils` + * [x] require `github.com/mailru/easyjson` + * [x] require `gopkg.in/yaml.v3` + +--- + +The root module `github.com/go-openapi/swag` at the repo level maintains a few +dependencies outside of the standard library: + +* YAML utilities depend on `gopkg.in/yaml.v3` +* JSON utilities `github.com/mailru/easyjson` + +This is not necessarily the case for all sub-modules. + +## Release notes + +### v0.24.0 [Unreleased] + +With this release, we have largely modernized the API of `swag`: + +* The traditional `swag` API is still supported: code that imports `swag` will still + compile and work the same. +* A deprecation notice is published to encourage consumers of this library to adopt + the newer API +* **Deprecation notice** + * configuration through global variables is now deprecated, in favor of options passed as parameters + * all helper functions are moved to more specialized packages, which are exposed as + go modules. Importing such a module would reduce the footprint of dependencies. + * _all_ functions, variables, constants exposed by the deprecated API have now moved, so + that consumers of the new API no longer need to import github.com/go-openapi/swag, but + should import the desired sub-module(s). + +**New with this release**: + +* [x] type converters and pointer to value helpers now support generic types +* [x] name mangling now support pluralized initialisms (issue #46) + Strings like "contact IDs" are now recognized as such a plural form and mangled as a linter would expect. +* [x] performance: small improvements to reduce the overhead of convert/format wrappers (see issues #110, or PR #108) +* [x] performance: name mangling utilities run ~ 10% faster (PR #115) + +--- + +Moving forward, no additional feature will be added to the `swag` API directly. + +However, child modules will continue to evolve or some new ones may be added in the future. + + +#### Note to contributors + +The mono-repo structure comes with some unavoidable extra pains... + +* Testing + +> The usual `go test ./...` command, run from the root of this repo won't work any longer to test all submodules. +> +> Each module constitutes an independant unit of test. So you have to run `go test` inside each module. +> Or you may take a look at how this is achieved by CI +> [here] https://github.com/go-openapi/swag/blob/master/.github/workflows/go-test.yml). +> +> There are also some alternative tricks using `go work`, for local development, if you feel comfortable with +> go workspaces. Perhaps some day, we'll have a `go work test` to run all tests without any hack. + +* Releasing + +> Each module follows its own independant module versioning. +> +> So you have tags like `mangling/v0.24.0`, `fileutils/v0.24.0` etc that are used by `go mod` and `go get` +> to refer to the tagged version of each module specifically. +> +> This means we may release patches etc to each module independently. +> +> We'd like to adopt the rule that modules in this repo would only differ by a patch version +> (e.g. `v0.24.5` vs `v0.24.3`), and we'll level all modules whenever a minor version is introduced. +> +> A script in `./hack` is provided to tag all modules in one go at the same level in one go. + +## Todos, suggestions and plans + +All kinds of contributions are welcome. + +A few ideas: + +* [ ] Complete the split of dependencies to isolate easyjson from the rest +* [ ] Improve mangling utilities (improve readability, support for capitalized words, + better word substitution for non-letter symbols...) +* [ ] Move back to this common shared pot a few of the technical features introduced by go-swagger independently + (e.g. mangle go package names, search package with go modules support, ...) +* [ ] Apply a similar mono-repo approach to go-openapi/strfmt which suffer from similar woes: bloated API, + imposed dependency to some database driver. + +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at ivan+abuse@flanders.co.nz. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ +## Contribution Guidelines + +### Pull requests are always welcome + +We are always thrilled to receive pull requests, and do our best to +process them as fast as possible. Not sure if that typo is worth a pull +request? Do it! We will appreciate it. + +If your pull request is not accepted on the first try, don't be +discouraged! If there's a problem with the implementation, hopefully you +received feedback on what to improve. + +We're trying very hard to keep go-swagger lean and focused. We don't want it +to do everything for everybody. This means that we might decide against +incorporating a new feature. However, there might be a way to implement +that feature *on top of* go-swagger. + + +### Conventions + +Fork the repo and make changes on your fork in a feature branch: + +- If it's a bugfix branch, name it XXX-something where XXX is the number of the + issue +- If it's a feature branch, create an enhancement issue to announce your + intentions, and name it XXX-something where XXX is the number of the issue. + +Submit unit tests for your changes. Go has a great test framework built in; use +it! Take a look at existing tests for inspiration. Run the full test suite on +your branch before submitting a pull request. + +Update the documentation when creating or modifying features. Test +your documentation changes for clarity, concision, and correctness, as +well as a clean documentation build. See ``docs/README.md`` for more +information on building the docs and how docs get released. + +Write clean code. Universally formatted code promotes ease of writing, reading, +and maintenance. Always run `gofmt -s -w file.go` on each changed file before +committing your changes. Most editors have plugins that do this automatically. + +Pull requests descriptions should be as clear as possible and include a +reference to all the issues that they address. + +Pull requests must not contain commits from other users or branches. + +Commit messages must start with a capitalized and short summary (max. 50 +chars) written in the imperative, followed by an optional, more detailed +explanatory text which is separated from the summary by an empty line. + +Code review comments may be added to your pull request. Discuss, then make the +suggested modifications and push additional commits to your feature branch. Be +sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you +comment. + +Before the pull request is merged, make sure that you squash your commits into +logical units of work using `git rebase -i` and `git push -f`. After every +commit the test suite should be passing. Include documentation changes in the +same commit so that a revert would remove all traces of the feature or fix. + +Commits that fix or close an issue should include a reference like `Closes #XXX` +or `Fixes #XXX`, which will automatically close the issue when merged. + +### Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](http://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign off when creating the git commit via `git commit -s`. +# Strfmt [![Build Status](https://github.com/go-openapi/strfmt/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/strfmt/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/strfmt/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/strfmt) +[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) +[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/strfmt/master/LICENSE) +[![GoDoc](https://godoc.org/github.com/go-openapi/strfmt?status.svg)](http://godoc.org/github.com/go-openapi/strfmt) +[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/strfmt)](https://goreportcard.com/report/github.com/go-openapi/strfmt) + +This package exposes a registry of data types to support string formats in the go-openapi toolkit. + +strfmt represents a well known string format such as credit card or email. The go toolkit for OpenAPI specifications knows how to deal with those. + +## Supported data formats +go-openapi/strfmt follows the swagger 2.0 specification with the following formats +defined [here](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types). + +It also provides convenient extensions to go-openapi users. + +- [x] JSON-schema draft 4 formats + - date-time + - email + - hostname + - ipv4 + - ipv6 + - uri +- [x] swagger 2.0 format extensions + - binary + - byte (e.g. base64 encoded string) + - date (e.g. "1970-01-01") + - password +- [x] go-openapi custom format extensions + - bsonobjectid (BSON objectID) + - creditcard + - duration (e.g. "3 weeks", "1ms") + - hexcolor (e.g. "#FFFFFF") + - isbn, isbn10, isbn13 + - mac (e.g "01:02:03:04:05:06") + - rgbcolor (e.g. "rgb(100,100,100)") + - ssn + - uuid, uuid3, uuid4, uuid5 + - cidr (e.g. "192.0.2.1/24", "2001:db8:a0b:12f0::1/32") + - ulid (e.g. "00000PP9HGSBSSDZ1JTEXBJ0PW", [spec](https://github.com/ulid/spec)) + +> NOTE: as the name stands for, this package is intended to support string formatting only. +> It does not provide validation for numerical values with swagger format extension for JSON types "number" or +> "integer" (e.g. float, double, int32...). + +## Type conversion + +All types defined here are stringers and may be converted to strings with `.String()`. +Note that most types defined by this package may be converted directly to string like `string(Email{})`. + +`Date` and `DateTime` may be converted directly to `time.Time` like `time.Time(Time{})`. +Similarly, you can convert `Duration` to `time.Duration` as in `time.Duration(Duration{})` + +## Using pointers + +The `conv` subpackage provides helpers to convert the types to and from pointers, just like `go-openapi/swag` does +with primitive types. + +## Format types +Types defined in strfmt expose marshaling and validation capabilities. + +List of defined types: +- Base64 +- CreditCard +- Date +- DateTime +- Duration +- Email +- HexColor +- Hostname +- IPv4 +- IPv6 +- CIDR +- ISBN +- ISBN10 +- ISBN13 +- MAC +- ObjectId +- Password +- RGBColor +- SSN +- URI +- UUID +- UUID3 +- UUID4 +- UUID5 +- [ULID](https://github.com/ulid/spec) +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at ivan+abuse@flanders.co.nz. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ +## Contribution Guidelines + +### Pull requests are always welcome + +We are always thrilled to receive pull requests, and do our best to +process them as fast as possible. Not sure if that typo is worth a pull +request? Do it! We will appreciate it. + +If your pull request is not accepted on the first try, don't be +discouraged! If there's a problem with the implementation, hopefully you +received feedback on what to improve. + +We're trying very hard to keep go-swagger lean and focused. We don't want it +to do everything for everybody. This means that we might decide against +incorporating a new feature. However, there might be a way to implement +that feature *on top of* go-swagger. + + +### Conventions + +Fork the repo and make changes on your fork in a feature branch: + +- If it's a bugfix branch, name it XXX-something where XXX is the number of the + issue +- If it's a feature branch, create an enhancement issue to announce your + intentions, and name it XXX-something where XXX is the number of the issue. + +Submit unit tests for your changes. Go has a great test framework built in; use +it! Take a look at existing tests for inspiration. Run the full test suite on +your branch before submitting a pull request. + +Update the documentation when creating or modifying features. Test +your documentation changes for clarity, concision, and correctness, as +well as a clean documentation build. See ``docs/README.md`` for more +information on building the docs and how docs get released. + +Write clean code. Universally formatted code promotes ease of writing, reading, +and maintenance. Always run `gofmt -s -w file.go` on each changed file before +committing your changes. Most editors have plugins that do this automatically. + +Pull requests descriptions should be as clear as possible and include a +reference to all the issues that they address. + +Pull requests must not contain commits from other users or branches. + +Commit messages must start with a capitalized and short summary (max. 50 +chars) written in the imperative, followed by an optional, more detailed +explanatory text which is separated from the summary by an empty line. + +Code review comments may be added to your pull request. Discuss, then make the +suggested modifications and push additional commits to your feature branch. Be +sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you +comment. + +Before the pull request is merged, make sure that you squash your commits into +logical units of work using `git rebase -i` and `git push -f`. After every +commit the test suite should be passing. Include documentation changes in the +same commit so that a revert would remove all traces of the feature or fix. + +Commits that fix or close an issue should include a reference like `Closes #XXX` +or `Fixes #XXX`, which will automatically close the issue when merged. + +### Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](http://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign off when creating the git commit via `git commit -s`. +# blag blah +# blag blah + +Ordered list: + + 1. xyz + 2. abc + +First list: + + - a + - b + - c + +Second list: + + * A + * B + * C + +Another Ordered list: + + 0. xyz + 0. abc +# OpenAPI errors [![Build Status](https://github.com/go-openapi/errors/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/errors/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/errors/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/errors) + +[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) +[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/errors/master/LICENSE) +[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/errors.svg)](https://pkg.go.dev/github.com/go-openapi/errors) +[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/errors)](https://goreportcard.com/report/github.com/go-openapi/errors) + +Shared errors and error interface used throughout the various libraries found in the go-openapi toolkit. +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at ivan+abuse@flanders.co.nz. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ +## Contribution Guidelines + +### Pull requests are always welcome + +We are always thrilled to receive pull requests, and do our best to +process them as fast as possible. Not sure if that typo is worth a pull +request? Do it! We will appreciate it. + +If your pull request is not accepted on the first try, don't be +discouraged! If there's a problem with the implementation, hopefully you +received feedback on what to improve. + +We're trying very hard to keep go-swagger lean and focused. We don't want it +to do everything for everybody. This means that we might decide against +incorporating a new feature. However, there might be a way to implement +that feature *on top of* go-swagger. + + +### Conventions + +Fork the repo and make changes on your fork in a feature branch: + +- If it's a bugfix branch, name it XXX-something where XXX is the number of the + issue +- If it's a feature branch, create an enhancement issue to announce your + intentions, and name it XXX-something where XXX is the number of the issue. + +Submit unit tests for your changes. Go has a great test framework built in; use +it! Take a look at existing tests for inspiration. Run the full test suite on +your branch before submitting a pull request. + +Update the documentation when creating or modifying features. Test +your documentation changes for clarity, concision, and correctness, as +well as a clean documentation build. See ``docs/README.md`` for more +information on building the docs and how docs get released. + +Write clean code. Universally formatted code promotes ease of writing, reading, +and maintenance. Always run `gofmt -s -w file.go` on each changed file before +committing your changes. Most editors have plugins that do this automatically. + +Pull requests descriptions should be as clear as possible and include a +reference to all the issues that they address. + +Pull requests must not contain commits from other users or branches. + +Commit messages must start with a capitalized and short summary (max. 50 +chars) written in the imperative, followed by an optional, more detailed +explanatory text which is separated from the summary by an empty line. + +Code review comments may be added to your pull request. Discuss, then make the +suggested modifications and push additional commits to your feature branch. Be +sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you +comment. + +Before the pull request is merged, make sure that you squash your commits into +logical units of work using `git rebase -i` and `git push -f`. After every +commit the test suite should be passing. Include documentation changes in the +same commit so that a revert would remove all traces of the feature or fix. + +Commits that fix or close an issue should include a reference like `Closes #XXX` +or `Fixes #XXX`, which will automatically close the issue when merged. + +### Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](http://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign off when creating the git commit via `git commit -s`. +Evaluate: + +* markdownlint + * assessment: go + * used by opentelemetry/opentelemetry-go + * packaged as github action +* misspell +* spellcheck +* govulncheck +* [x] godoc-lint: + * assessment: no go + * too simplistic: no real value added + * not integrated into golangci's suite of linters + * no packaged github action +

dfkjfkfj

+ + +ERGGLGKLK +========== +this is a title +# .github +Default github settings for go-openapi repositories +--- +name: '❓ Question' +about: I have a question about this project +title: '' +labels: [question] +assignees: '' + +--- + +**Question** + + +**Additional context** + +--- +name: '➕ Feature request' +about: Suggest an idea for this project +title: '' +labels: [enhancement] +assignees: '' + +--- + +**Is your feature request related to a problem? Please describe.** + + +**Describe the solution you'd like** + + +**Describe alternatives you've considered** + + +**Additional context** + +--- +name: '🐞 Bug report' +about: Create a report to help us make go-openapi a great project +title: '' +labels: [bug] +assignees: '' + +--- + +**Describe the bug** + + +**Steps to Reproduce** + + + + +**Expected behavior** + + +**Actual behavior** + + +**Environment** + + +**Additional context** + +## Change type + +Please select: 🆕 New feature or enhancement|🔧 Bug fix'|📃 Documentation update + +## Short description + + +## Fixes + + +## Full description + + + + +## Checklist + + + +* [ ] I have signed all my commits with my name and email (see [DCO](https://github.com/apps/dco). **This does not require a PGP-signed commit** +* [ ] I have rebased and squashed my work, so only one commit remains +* [ ] I have added tests to cover my changes. +* [ ] I have properly enriched go doc comments in code. +* [ ] I have properly documented any breaking change. +## Change type: 📃 Documentation update + +## Short description + + +## Fixes + + +## Checklist + + + +* [ ] I have signed all my commits with my name and email (see [DCO](https://github.com/apps/dco). **This does not require a PGP-signed commit** +* [ ] I have rebased and squashed my work, so only one commit remains +* [ ] I have signed all my commits with my name and email (see DCO: https://github.com/apps/dco). **This does not require a PGP-signed commit** +* [ ] I have rebased and squash my work, so only one commit remains +* [ ] I have only modified comments in code or markdown files +## Change type: 🆕 New feature or enhancement + +## Short description + + +## Fixes + + +## Checklist + + + +* [ ] I have signed all my commits with my name and email (see [DCO](https://github.com/apps/dco). **This does not require a PGP-signed commit** +* [ ] I have rebased and squashed my work, so only one commit remains +* [ ] I have added tests to cover my changes. +* [ ] I have properly enriched go doc comments in code. +* [ ] I have properly documented any breaking change. +## Change type: 🔧 Bug fix + +## Short description + + +## Fixes + + +## Full description + + + + +## Checklist + + + +* [ ] I have signed all my commits with my name and email (see [DCO](https://github.com/apps/dco). **This does not require a PGP-signed commit** +* [ ] I have rebased and squashed my work, so only one commit remains +* [ ] I have added tests to cover my changes. +* [ ] I have made sure that my code remains portable +* [ ] I have properly enriched go doc comments in code. +* [ ] I have properly documented any breaking change. +# OpenAPI initiative random data generator [![Build Status](https://travis-ci.org/go-openapi/stubs.svg?branch=master)](https://travis-ci.org/go-openapi/stubs) [![codecov](https://codecov.io/gh/go-openapi/stubs/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/stubs) [![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) + +[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/stubs/master/LICENSE) [![GoDoc](https://godoc.org/github.com/go-openapi/stubs?status.svg)](http://godoc.org/github.com/go-openapi/stubs) + + +A library to generate random data for a swagger specification. +This is a building block for generating stubs for your API as well as tests. +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at ivan+abuse@flanders.co.nz. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ +# Stubs design + +The goal of this library is to be able to generate somewhat good looking random data for structures defined in an openapi or jsonschema document. +These can be used to provide an api with stubs so that you can verify valid and invalid request/responses without an actually meaningful implementation. +Some areas where this is useful are collaboration between different teams so that all teams can do work without having to wait on the delivery of the completed implementation of the API. +A second area where this is obviously useful is for doing automated tests and filling up datastructures for use in those tests. + + +In the openapi 2.0 specification there are 2 families of types that can be used as targets for a random data generator. + +1. Path Item related types + 1. Non-Schema Parameters + 2. Response headers + 3. Collection Items on parameters or headers +2. Schemas + +These 2 families warrant slightly different strategies for getting the necessary parameters for a datagenerator. + +## Functionality + +To generate meaningful random data the library looks at the schema and based on properties for that schema it picks an appropriate random value generator. +This means that when it is generating a string for an object property that represents a first name it should pick a data generator that generates first names. +Similarly should a property be called city it should generate a city name. + +It's possible that the validity of a particular property is dependent on the value of another property, for example a creation date is typically never larger than a modified date. + +A data generator for a schema should be able to generate valid and invalid data, ideally there is control for specifying the value is invalid for a particular validation. This will help in tests to validate error codes + +## How does it work + +The main components in this library are a registry of datagenerators so they are addressable by keys, aliases for those keys to aid with inferring which datagenerator to use. +And of course a value generator, which will generate either a valid or an invalid value. + +In the openapi API document and in a json schema document there is a vendor extension that can be used to customize the generation process. + +### Value generator function + +There are 2 types of data generators but they both have the same function signature. +There are value generators and there are composite value generators. + +* A value generator generates a single value for a simple type. +* A composite generator generates a value that is built out of one or more generators eg. object schemas with properties. + +The signature for the value generator is: + +```go +type ValueGenerator func(GeneratorOpts) (interface{}, error) +``` + +A value generator is the innermost component in the library and the arguments to the function are used to configure the generator. +The generation process for a generator is configured through a GeneratorOpts interface. + +### GeneratorOpts interface + +The generator options describe the type and potentially the format for the value that needs to be generated. +In addition to the type information it also captures the field name or definition name of the value that needs to be generated. + +### StubMode + +The stubmode bitmask allows for configuring which validations should fail for a given value generator. + +### Generator + +The generator is the main entry point for the library and its Generate method is what will generate the random value for the descriptor. +# Use cases for stubs + +The stubs package is intended to support the following use cases: + +1. Generate unit test cases for code generated by go-swagger, especially validation code +2. Generate test cases for API servers and clients +3. Generate realistic examples + +## Supported swagger 2.0 constructs + +- parameter +- header +- response +- schema, including support for: + - [] AllOf + - [] Not + - [] additionalProperties + - [] patternProperties + - [] additionalItems + +Formated strings and numbers support go-openapi/strfmt formats, including: + - [] binary (strfmt.Base64) + - [] bsonobjectid + +The "file" datatype is not supported at the moment. + +The generation assumes the provide swagger spec is valid. + +Warnings regarding test case (2): +- stubs is not concerned about security definitions and credentials +- stubs generates values independently for each parameter, or response: it does not know about consistent sets of values beyond validation constraints, let alone + proper chaining of request with responses. + +## Sample applications for stubs + +- process a spec to include examples +- generate fixtures for codegen unit testing +- generate fixtures for API server benchmarking +- ... + +# Reproducible stubs + +Generated stubs may be regenerated using the same initial seed. + +There are two seeding modes to run the stubs generator: + +- AutoSeed: reseeds itself based on current timestamp +- SetSeed: generation occurs with a single seed, provided by the caller + +The package uses a default seeder to carry on this task. Alternate seeders might be provided. + +This also allows for unit testing this very package... + +# Setting generation goals + +Goals select the general use case and allow for fine tuning of the sample generation. + +We use GenerateMode and StubMode flags to define goals. + +Stubmode is used to tune individually every single generated value. + +GenerateMode sets general directives and may define StubMode autonomously according to the generation goal. + +## GenerateMode + +target: +- unitTest: any value value may be produced, not necessarily a realistic definevalue. + By default in the UnitTest mode, non-formated strings are loren ipsums, numbers, dates and times may be very small or very large +- examples: the generator attempts to figure out realistic values to be used as examples + +GenerateMode accepts arguments to further specify the expected generation: + +args: +- valid: all generated values are valid. This is the default. + - count: number of samples to be generated. May be zero to get only default, examples, edge cases or validation checks. Default is 1. +- invalid: all generated values are invalid, with failures chosen at random. + - count: number of samples to be generated. Default is 1. +- skipTilting: tilting rules are omitted (only applies to invalid values). Default is true in unit test mode and false in example mode. +- skipFuzzying: fuzzying rules are omitted +- withTilting: add tilted invalid values, with failures chosen at random. This forces a tilting strategy on a new set of values. + - count: number of tilted samples to be generated. Default is 1. +- withValidationCheck: for each validation, an invalid value against this validation is generated (e.g. if min and max are specified, we have one value below min and one value above max) + - count: this sets a limit on the count of generated values. If you have n validations, that makes n generated values. With the limit set, validations are checked width-first (outermost validations come first) +- withAllValidationChecks: all combinations of failed validations are generated. This includes one valid value and single failure from withValidation. + - count: this sets a limit on the count of generated values. If you have n validations, that makes 2^n generated values, which may raise quickly when nesting schema structures. With the limit set, validations are checked width-first (outermost validations come first) +- withDefault: add default value to sample values (not included in "count"). This simulates a user providing exactly the same value as the default. Since defaults may be set at different levels of the structure, a new value is generated for each applicable default. +- withExample: add example value to sample values (not included in "count"), whenever applicable. Examples are assumed valid, but may be invalid. + - tiltDefault: constructs invalid values by tilting default + - tiltExample: constructs invalid values by tilting examples + - count: number of title +- withEdgeCase: + - standard: standard preconfigured edge cases (e.g. boundary value for min constraint with boundary included, Feb 29th dates for date types, ...) + - value: a customizable value added as an edge case. May be any value, array or object. Severa values may be specified. +- max: an upper limit on number generation (floats, ints, ...). By default, the full range of the data type is used. +- min: a lower limit on number generation. +- precision: rounding specification for floats +- multipleOf: a multiple specification for numbers +- length: + - on string values: an upper limit on string size, to avoid long texts being unwittingly generated + - on array values: an upper limit on the number of generated items + - on additionalProperties: an upper limit on the number of generated additionalProperties + - on patternProperties: an upper limit on the number of generated patternProperties +- words: a limit on the number of words in generated texts, paragraphs and sentences +- lang: specifies the target language(s) for strings and text. + - [lang] + - all: special value to tell the generator to pick text at random from all supported languages + +This sets an overall target for all generations. For every single spec object, you may hint further and override global settings on a case by case basis. + +# Hinting + +The `x-datagen` extension may be used in the swagger spec to hint the stubs generator. + +Examples: +``` +parameters: + phone: + in: query + required: true + type: string + x-datagen: + name: mobile +``` +will generate a mobile phone number for query parameter "phone". + +``` +parameters: + price: + in: query + required: true + type: string + x-datagen: + name: float +``` +will generate float numbers for the price parameter. +It might be not realistic to have 3.1344344E35 as a price, but it is a valid value... + +`x-datagen` accepts args to further hint the generator. +All Args accepted by GenerateMode or StubMode may be used here to locally override generation options. + +Example: +``` +parameters: + vat: + in: query + required: true + type: number + x-datagen: + args: + min: 100 + max: 10000 + +``` +will generate floats between 100 and 10000. +Again, it might not be realistic to have prices such as 503.14561434566... + +Some generators are already configured to suit some targeted usage. + +Example: +``` +parameters: + price: + in: query + required: true + type: string + x-datagen: + name: small-amounts +``` +and you get more realistic values like 3.23, 104.30... + +## x-datagen args + +- name: overrides the generator's name + +Supported args, not already mentioned in the GenerateMode section: +- args: + +# Fuzzying + +The generation takes basic decisions based on type and available validation constraints. +Obviously, this does not work well when the goal is to generate realistic samples for your data. +Of course, everyhing may be fine-tuned by using the x-datagen extension. +But this is tedious work on large specs. + +We introduce fuzzying as a way to carry on some of the guesswork when deciding which kind of fake value would best match expectations. +Fuzzying relies on names, titles and description to look for recognizable keywords, then elects an adequate random generator. + +Examples for the above samples: +- with name "price", the fuzzying guesses that it is not some arbitrary float to be generated, but a decimal between 0 and 1,000,000 (max overrides this limit). +- with a description such as "The item price expressed in USD. Items are sold at a low price", fuzzying rules should guess that we want to generate small-amount values (so between 0 and 1,000). + +Fuzzying also works for non-strings data: +- a date field named "birthday" would hint toward the birthdate value generator (hence dates are not in the future and only in a recent past) +- a datetime named "timestamp" or described as "The update date" would generate a recent datetime value. Further, edge cases with this guess would add 01/01/1970 to the generated value + +# Tilting + +Tilting is a strategy to generate invalid values, by tilting a valid value just enough so it becomes invalid. +This generates interesting test cases since values are supposed to be "almost" valid but actually are not. + +Tilting strategies depend on validations. + +Examples: +- tilting on max will generate a value at or slightly above the lowest invalid value +- tilting on regexp will change the smallest number of characters in a string so the regexp no more matches +- tilting on enum will slightly modify a valid value and make it invalid +- ... + +Options skipTilting and withTilting tune the generator behavior regarding tilting. +# gojsonpointer [![Build Status](https://github.com/go-openapi/jsonpointer/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/jsonpointer/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/jsonpointer/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/jsonpointer) + +[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) +[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/jsonpointer/master/LICENSE) +[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/jsonpointer.svg)](https://pkg.go.dev/github.com/go-openapi/jsonpointer) +[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/jsonpointer)](https://goreportcard.com/report/github.com/go-openapi/jsonpointer) + +An implementation of JSON Pointer - Go language + +## Status +Completed YES + +Tested YES + +## References +http://tools.ietf.org/html/draft-ietf-appsawg-json-pointer-07 + +### Note +The 4.Evaluation part of the previous reference, starting with 'If the currently referenced value is a JSON array, the reference token MUST contain either...' is not implemented. +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at ivan+abuse@flanders.co.nz. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ +## Contribution Guidelines + +### Pull requests are always welcome + +We are always thrilled to receive pull requests, and do our best to +process them as fast as possible. Not sure if that typo is worth a pull +request? Do it! We will appreciate it. + +If your pull request is not accepted on the first try, don't be +discouraged! If there's a problem with the implementation, hopefully you +received feedback on what to improve. + +We're trying very hard to keep go-swagger lean and focused. We don't want it +to do everything for everybody. This means that we might decide against +incorporating a new feature. However, there might be a way to implement +that feature *on top of* go-swagger. + + +### Conventions + +Fork the repo and make changes on your fork in a feature branch: + +- If it's a bugfix branch, name it XXX-something where XXX is the number of the + issue +- If it's a feature branch, create an enhancement issue to announce your + intentions, and name it XXX-something where XXX is the number of the issue. + +Submit unit tests for your changes. Go has a great test framework built in; use +it! Take a look at existing tests for inspiration. Run the full test suite on +your branch before submitting a pull request. + +Update the documentation when creating or modifying features. Test +your documentation changes for clarity, concision, and correctness, as +well as a clean documentation build. See ``docs/README.md`` for more +information on building the docs and how docs get released. + +Write clean code. Universally formatted code promotes ease of writing, reading, +and maintenance. Always run `gofmt -s -w file.go` on each changed file before +committing your changes. Most editors have plugins that do this automatically. + +Pull requests descriptions should be as clear as possible and include a +reference to all the issues that they address. + +Pull requests must not contain commits from other users or branches. + +Commit messages must start with a capitalized and short summary (max. 50 +chars) written in the imperative, followed by an optional, more detailed +explanatory text which is separated from the summary by an empty line. + +Code review comments may be added to your pull request. Discuss, then make the +suggested modifications and push additional commits to your feature branch. Be +sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you +comment. + +Before the pull request is merged, make sure that you squash your commits into +logical units of work using `git rebase -i` and `git push -f`. After every +commit the test suite should be passing. Include documentation changes in the +same commit so that a revert would remove all traces of the feature or fix. + +Commits that fix or close an issue should include a reference like `Closes #XXX` +or `Fixes #XXX`, which will automatically close the issue when merged. + +### Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](http://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign off when creating the git commit via `git commit -s`. +# Swagger 2.0 specification schema + +This folder contains the Swagger 2.0 specification schema files maintained here: + +https://github.com/reverb/swagger-spec/blob/master/schemas/v2.0# OpenAPI v2 object model [![Build Status](https://github.com/go-openapi/spec/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/spec/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/spec/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/spec) + +[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) +[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/spec/master/LICENSE) +[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/spec.svg)](https://pkg.go.dev/github.com/go-openapi/spec) +[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/spec)](https://goreportcard.com/report/github.com/go-openapi/spec) + +The object model for OpenAPI specification documents. + +### FAQ + +* What does this do? + +> 1. This package knows how to marshal and unmarshal Swagger API specifications into a golang object model +> 2. It knows how to resolve $ref and expand them to make a single root document + +* How does it play with the rest of the go-openapi packages ? + +> 1. This package is at the core of the go-openapi suite of packages and [code generator](https://github.com/go-swagger/go-swagger) +> 2. There is a [spec loading package](https://github.com/go-openapi/loads) to fetch specs as JSON or YAML from local or remote locations +> 3. There is a [spec validation package](https://github.com/go-openapi/validate) built on top of it +> 4. There is a [spec analysis package](https://github.com/go-openapi/analysis) built on top of it, to analyze, flatten, fix and merge spec documents + +* Does this library support OpenAPI 3? + +> No. +> This package currently only supports OpenAPI 2.0 (aka Swagger 2.0). +> There is no plan to make it evolve toward supporting OpenAPI 3.x. +> This [discussion thread](https://github.com/go-openapi/spec/issues/21) relates the full story. +> +> An early attempt to support Swagger 3 may be found at: https://github.com/go-openapi/spec3 + +* Does the unmarshaling support YAML? + +> Not directly. The exposed types know only how to unmarshal from JSON. +> +> In order to load a YAML document as a Swagger spec, you need to use the loaders provided by +> github.com/go-openapi/loads +> +> Take a look at the example there: https://pkg.go.dev/github.com/go-openapi/loads#example-Spec +> +> See also https://github.com/go-openapi/spec/issues/164 + +* How can I validate a spec? + +> Validation is provided by [the validate package](http://github.com/go-openapi/validate) + +* Why do we have an `ID` field for `Schema` which is not part of the swagger spec? + +> We found jsonschema compatibility more important: since `id` in jsonschema influences +> how `$ref` are resolved. +> This `id` does not conflict with any property named `id`. +> +> See also https://github.com/go-openapi/spec/issues/23 +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at ivan+abuse@flanders.co.nz. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ +## Contribution Guidelines + +### Pull requests are always welcome + +We are always thrilled to receive pull requests, and do our best to +process them as fast as possible. Not sure if that typo is worth a pull +request? Do it! We will appreciate it. + +If your pull request is not accepted on the first try, don't be +discouraged! If there's a problem with the implementation, hopefully you +received feedback on what to improve. + +We're trying very hard to keep go-swagger lean and focused. We don't want it +to do everything for everybody. This means that we might decide against +incorporating a new feature. However, there might be a way to implement +that feature *on top of* go-swagger. + + +### Conventions + +Fork the repo and make changes on your fork in a feature branch: + +- If it's a bugfix branch, name it XXX-something where XXX is the number of the + issue +- If it's a feature branch, create an enhancement issue to announce your + intentions, and name it XXX-something where XXX is the number of the issue. + +Submit unit tests for your changes. Go has a great test framework built in; use +it! Take a look at existing tests for inspiration. Run the full test suite on +your branch before submitting a pull request. + +Update the documentation when creating or modifying features. Test +your documentation changes for clarity, concision, and correctness, as +well as a clean documentation build. See ``docs/README.md`` for more +information on building the docs and how docs get released. + +Write clean code. Universally formatted code promotes ease of writing, reading, +and maintenance. Always run `gofmt -s -w file.go` on each changed file before +committing your changes. Most editors have plugins that do this automatically. + +Pull requests descriptions should be as clear as possible and include a +reference to all the issues that they address. + +Pull requests must not contain commits from other users or branches. + +Commit messages must start with a capitalized and short summary (max. 50 +chars) written in the imperative, followed by an optional, more detailed +explanatory text which is separated from the summary by an empty line. + +Code review comments may be added to your pull request. Discuss, then make the +suggested modifications and push additional commits to your feature branch. Be +sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you +comment. + +Before the pull request is merged, make sure that you squash your commits into +logical units of work using `git rebase -i` and `git push -f`. After every +commit the test suite should be passing. Include documentation changes in the +same commit so that a revert would remove all traces of the feature or fix. + +Commits that fix or close an issue should include a reference like `Closes #XXX` +or `Fixes #XXX`, which will automatically close the issue when merged. + +### Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](http://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign off when creating the git commit via `git commit -s`. +# gojsonreference [![Build Status](https://github.com/go-openapi/jsonreference/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/jsonreference/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/jsonreference/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/jsonreference) + +[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) +[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/jsonreference/master/LICENSE) +[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/jsonreference.svg)](https://pkg.go.dev/github.com/go-openapi/jsonreference) +[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/jsonreference)](https://goreportcard.com/report/github.com/go-openapi/jsonreference) + +An implementation of JSON Reference - Go language + +## Status +Feature complete. Stable API + +## Dependencies +* https://github.com/go-openapi/jsonpointer + +## References + +* http://tools.ietf.org/html/draft-ietf-appsawg-json-pointer-07 +* http://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03 +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at ivan+abuse@flanders.co.nz. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ +## Contribution Guidelines + +### Pull requests are always welcome + +We are always thrilled to receive pull requests, and do our best to +process them as fast as possible. Not sure if that typo is worth a pull +request? Do it! We will appreciate it. + +If your pull request is not accepted on the first try, don't be +discouraged! If there's a problem with the implementation, hopefully you +received feedback on what to improve. + +We're trying very hard to keep go-swagger lean and focused. We don't want it +to do everything for everybody. This means that we might decide against +incorporating a new feature. However, there might be a way to implement +that feature *on top of* go-swagger. + + +### Conventions + +Fork the repo and make changes on your fork in a feature branch: + +- If it's a bugfix branch, name it XXX-something where XXX is the number of the + issue +- If it's a feature branch, create an enhancement issue to announce your + intentions, and name it XXX-something where XXX is the number of the issue. + +Submit unit tests for your changes. Go has a great test framework built in; use +it! Take a look at existing tests for inspiration. Run the full test suite on +your branch before submitting a pull request. + +Update the documentation when creating or modifying features. Test +your documentation changes for clarity, concision, and correctness, as +well as a clean documentation build. See ``docs/README.md`` for more +information on building the docs and how docs get released. + +Write clean code. Universally formatted code promotes ease of writing, reading, +and maintenance. Always run `gofmt -s -w file.go` on each changed file before +committing your changes. Most editors have plugins that do this automatically. + +Pull requests descriptions should be as clear as possible and include a +reference to all the issues that they address. + +Pull requests must not contain commits from other users or branches. + +Commit messages must start with a capitalized and short summary (max. 50 +chars) written in the imperative, followed by an optional, more detailed +explanatory text which is separated from the summary by an empty line. + +Code review comments may be added to your pull request. Discuss, then make the +suggested modifications and push additional commits to your feature branch. Be +sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you +comment. + +Before the pull request is merged, make sure that you squash your commits into +logical units of work using `git rebase -i` and `git push -f`. After every +commit the test suite should be passing. Include documentation changes in the +same commit so that a revert would remove all traces of the feature or fix. + +Commits that fix or close an issue should include a reference like `Closes #XXX` +or `Fixes #XXX`, which will automatically close the issue when merged. + +### Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](http://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign off when creating the git commit via `git commit -s`. +# doc + +Documentation check and generation tools. +# ci-workflows[![Build Status](https://github.com/go-openapi/ci-workflows/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/ci-workflows/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/ci-workflows/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/ci-workflows) + +[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) +[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/ci-workflows/master/LICENSE) +[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/ci-workflows.svg)](https://pkg.go.dev/github.com/go-openapi/ci-workflows) +[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/ci-workflows)](https://goreportcard.com/report/github.com/go-openapi/ci-workflows) + +Common Continuous Integration (`CI`) workflows and setup for go-openapi repos. + +* shared github action workflows +* shared `dependabot` configuration (TODO) +* shared `golangci-lint` configuration (**BLOCKED**) + +> NOTE: at this moment, it is difficult to share the golangci-lint config, +> so that one is not shared yet. + +## Motivation + +It took a while, but we eventually managed to align all checks, tests and +dependabot rules declared in the family of go-openapi repos. + +Now we'd like to be able to maintain, enrich and improve these checks without +worrying too much about the burden to replicate it about a dozen times. + +## Contemplated enhancements + +In no particular order: + +* [x] ui: enrich github actions UI with a job summary +* [x] doc: add markdown linting for docs +* [x] doc: add spellcheck for docs (and code?) +* [ ] version common workflows, so we can limit the impact of a change +* [ ] build: verify that go.sum cache for tests works (should be enabled) +* [ ] share mono repo workflows (see github.com/go-openapi/swag/.github/workflows) +* [ ] lint: manage somehow to share golangci config (with local merge) +* [ ] dependencies: manage somehow to share / replicate dependabot config +* [ ] lint: golangci-lint: check valid PR comments etc +* [ ] lint: use non-blocking, scheduled, proactive full linting to check for + the impact of new linters, new go versions etc +* [ ] doc: (possibility) take over hugo & doc gen part from go-swagger +* [ ] (possibility) take over release part from go-swagger +* [ ] doc: produce hugo github page with all latest tagged versions + (incl. mono repo) +* [ ] add bot to filter PRs, issues +* [ ] check with github API that all repo settings (branch protection rules, etc) + are identical +* [ ] comment PRs and issues +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at ivan+abuse@flanders.co.nz. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ +## Contribution Guidelines + +### Pull requests are always welcome + +We are always thrilled to receive pull requests, and do our best to +process them as fast as possible. Not sure if that typo is worth a pull +request? Do it! We will appreciate it. + +If your pull request is not accepted on the first try, don't be +discouraged! If there's a problem with the implementation, hopefully you +received feedback on what to improve. + +We're trying very hard to keep go-swagger lean and focused. We don't want it +to do everything for everybody. This means that we might decide against +incorporating a new feature. However, there might be a way to implement +that feature *on top of* go-swagger. + + +### Conventions + +Fork the repo and make changes on your fork in a feature branch: + +- If it's a bugfix branch, name it XXX-something where XXX is the number of the + issue +- If it's a feature branch, create an enhancement issue to announce your + intentions, and name it XXX-something where XXX is the number of the issue. + +Submit unit tests for your changes. Go has a great test framework built in; use +it! Take a look at existing tests for inspiration. Run the full test suite on +your branch before submitting a pull request. + +Update the documentation when creating or modifying features. Test +your documentation changes for clarity, concision, and correctness, as +well as a clean documentation build. See ``docs/README.md`` for more +information on building the docs and how docs get released. + +Write clean code. Universally formatted code promotes ease of writing, reading, +and maintenance. Always run `gofmt -s -w file.go` on each changed file before +committing your changes. Most editors have plugins that do this automatically. + +Pull requests descriptions should be as clear as possible and include a +reference to all the issues that they address. + +Pull requests must not contain commits from other users or branches. + +Commit messages must start with a capitalized and short summary (max. 50 +chars) written in the imperative, followed by an optional, more detailed +explanatory text which is separated from the summary by an empty line. + +Code review comments may be added to your pull request. Discuss, then make the +suggested modifications and push additional commits to your feature branch. Be +sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you +comment. + +Before the pull request is merged, make sure that you squash your commits into +logical units of work using `git rebase -i` and `git push -f`. After every +commit the test suite should be passing. Include documentation changes in the +same commit so that a revert would remove all traces of the feature or fix. + +Commits that fix or close an issue should include a reference like `Closes #XXX` +or `Fixes #XXX`, which will automatically close the issue when merged. + +### Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](http://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign off when creating the git commit via `git commit -s`. +# Audit + +Audit of github repos to check for inconsistencies. +# inflect [![Build Status](https://github.com/go-openapi/inflect/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/inflect/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/inflect/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/inflect) + +[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) +[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/inflect/master/LICENSE) +[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/inflect.svg)](https://pkg.go.dev/github.com/go-openapi/inflect) +[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/inflect)](https://goreportcard.com/report/github.com/go-openapi/inflect) + +A package to pluralize words. + +Originally forked from fork of https://bitbucket.org/pkg/inflect under a MIT License. + +A golang library applying grammar rules to English words. + +> This package provides a basic set of functions applying +> grammar rules to inflect English words, modify case style +> (Capitalize, camelCase, snake_case, etc.). +> +> Acronyms are properly handled. A common use case is word pluralization. + + +This library is not used at all by other go-openapi packages and is somewhat redundant with +go-openapi/swag/mangling (for camelcase etc). + +Currently we have one single dependency in one place in a go-swagger template (used as a funcmap). + +## Note to maintainers + +* Aug. 2025: CI workflows have now moved to a shared repository go-openapi/ci-workflows +## Contribution Guidelines + +### Pull requests are always welcome + +We are always thrilled to receive pull requests, and do our best to +process them as fast as possible. Not sure if that typo is worth a pull +request? Do it! We will appreciate it. + +If your pull request is not accepted on the first try, don't be +discouraged! If there's a problem with the implementation, hopefully you +received feedback on what to improve. + +We're trying very hard to keep go-swagger lean and focused. We don't want it +to do everything for everybody. This means that we might decide against +incorporating a new feature. However, there might be a way to implement +that feature *on top of* go-swagger. + + +### Conventions + +Fork the repo and make changes on your fork in a feature branch: + +- If it's a bugfix branch, name it XXX-something where XXX is the number of the + issue +- If it's a feature branch, create an enhancement issue to announce your + intentions, and name it XXX-something where XXX is the number of the issue. + +Submit unit tests for your changes. Go has a great test framework built in; use +it! Take a look at existing tests for inspiration. Run the full test suite on +your branch before submitting a pull request. + +Update the documentation when creating or modifying features. Test +your documentation changes for clarity, concision, and correctness, as +well as a clean documentation build. See ``docs/README.md`` for more +information on building the docs and how docs get released. + +Write clean code. Universally formatted code promotes ease of writing, reading, +and maintenance. Always run `gofmt -s -w file.go` on each changed file before +committing your changes. Most editors have plugins that do this automatically. + +Pull requests descriptions should be as clear as possible and include a +reference to all the issues that they address. + +Pull requests must not contain commits from other users or branches. + +Commit messages must start with a capitalized and short summary (max. 50 +chars) written in the imperative, followed by an optional, more detailed +explanatory text which is separated from the summary by an empty line. + +Code review comments may be added to your pull request. Discuss, then make the +suggested modifications and push additional commits to your feature branch. Be +sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you +comment. + +Before the pull request is merged, make sure that you squash your commits into +logical units of work using `git rebase -i` and `git push -f`. After every +commit the test suite should be passing. Include documentation changes in the +same commit so that a revert would remove all traces of the feature or fix. + +Commits that fix or close an issue should include a reference like `Closes #XXX` +or `Fixes #XXX`, which will automatically close the issue when merged. + +### Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](http://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign off when creating the git commit via `git commit -s`. +# Validation helpers [![Build Status](https://github.com/go-openapi/validate/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/validate/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/validate/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/validate) + +[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) +[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/validate/master/LICENSE) +[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/validate.svg)](https://pkg.go.dev/github.com/go-openapi/validate) +[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/validate)](https://goreportcard.com/report/github.com/go-openapi/validate) + +This package provides helpers to validate Swagger 2.0. specification (aka OpenAPI 2.0). + +Reference can be found here: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md. + +## What's inside? + +* A validator for Swagger specifications +* A validator for JSON schemas draft4 +* Helper functions to validate individual values (used by code generated by [go-swagger](https://github.com/go-swagger/go-swagger)). + * Required, RequiredNumber, RequiredString + * ReadOnly + * UniqueItems, MaxItems, MinItems + * Enum, EnumCase + * Pattern, MinLength, MaxLength + * Minimum, Maximum, MultipleOf + * FormatOf + +[Documentation](https://pkg.go.dev/github.com/go-openapi/validate) + +## FAQ + +* Does this library support OpenAPI 3? + +> No. +> This package currently only supports OpenAPI 2.0 (aka Swagger 2.0). +> There is no plan to make it evolve toward supporting OpenAPI 3.x. +> This [discussion thread](https://github.com/go-openapi/spec/issues/21) relates the full story. +> +> An early attempt to support Swagger 3 may be found at: https://github.com/go-openapi/spec3 +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at ivan+abuse@flanders.co.nz. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ +## Contribution Guidelines + +### Pull requests are always welcome + +We are always thrilled to receive pull requests, and do our best to +process them as fast as possible. Not sure if that typo is worth a pull +request? Do it! We will appreciate it. + +If your pull request is not accepted on the first try, don't be +discouraged! If there's a problem with the implementation, hopefully you +received feedback on what to improve. + +We're trying very hard to keep go-swagger lean and focused. We don't want it +to do everything for everybody. This means that we might decide against +incorporating a new feature. However, there might be a way to implement +that feature *on top of* go-swagger. + + +### Conventions + +Fork the repo and make changes on your fork in a feature branch: + +- If it's a bugfix branch, name it XXX-something where XXX is the number of the + issue +- If it's a feature branch, create an enhancement issue to announce your + intentions, and name it XXX-something where XXX is the number of the issue. + +Submit unit tests for your changes. Go has a great test framework built in; use +it! Take a look at existing tests for inspiration. Run the full test suite on +your branch before submitting a pull request. + +Update the documentation when creating or modifying features. Test +your documentation changes for clarity, concision, and correctness, as +well as a clean documentation build. See ``docs/README.md`` for more +information on building the docs and how docs get released. + +Write clean code. Universally formatted code promotes ease of writing, reading, +and maintenance. Always run `gofmt -s -w file.go` on each changed file before +committing your changes. Most editors have plugins that do this automatically. + +Pull requests descriptions should be as clear as possible and include a +reference to all the issues that they address. + +Pull requests must not contain commits from other users or branches. + +Commit messages must start with a capitalized and short summary (max. 50 +chars) written in the imperative, followed by an optional, more detailed +explanatory text which is separated from the summary by an empty line. + +Code review comments may be added to your pull request. Discuss, then make the +suggested modifications and push additional commits to your feature branch. Be +sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you +comment. + +Before the pull request is merged, make sure that you squash your commits into +logical units of work using `git rebase -i` and `git push -f`. After every +commit the test suite should be passing. Include documentation changes in the +same commit so that a revert would remove all traces of the feature or fix. + +Commits that fix or close an issue should include a reference like `Closes #XXX` +or `Fixes #XXX`, which will automatically close the issue when merged. + +### Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](http://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign off when creating the git commit via `git commit -s`. +# Benchmark + +Validating the Kubernetes Swagger API + +## v0.22.6: 60,000,000 allocs +``` +goos: linux +goarch: amd64 +pkg: github.com/go-openapi/validate +cpu: AMD Ryzen 7 5800X 8-Core Processor +Benchmark_KubernetesSpec/validating_kubernetes_API-16 1 8549863982 ns/op 7067424936 B/op 59583275 allocs/op +``` + +## After refact PR: minor but noticable improvements: 25,000,000 allocs +``` +go test -bench Spec +goos: linux +goarch: amd64 +pkg: github.com/go-openapi/validate +cpu: AMD Ryzen 7 5800X 8-Core Processor +Benchmark_KubernetesSpec/validating_kubernetes_API-16 1 4064535557 ns/op 3379715592 B/op 25320330 allocs/op +``` + +## After reduce GC pressure PR: 17,000,000 allocs +``` +goos: linux +goarch: amd64 +pkg: github.com/go-openapi/validate +cpu: AMD Ryzen 7 5800X 8-Core Processor +Benchmark_KubernetesSpec/validating_kubernetes_API-16 1 3758414145 ns/op 2593881496 B/op 17111373 allocs/op +``` +# Denco [![Build Status](https://travis-ci.org/naoina/denco.png?branch=master)](https://travis-ci.org/naoina/denco) + +The fast and flexible HTTP request router for [Go](http://golang.org). + +Denco is based on Double-Array implementation of [Kocha-urlrouter](https://github.com/naoina/kocha-urlrouter). +However, Denco is optimized and some features added. + +## Features + +* Fast (See [go-http-routing-benchmark](https://github.com/naoina/go-http-routing-benchmark)) +* [URL patterns](#url-patterns) (`/foo/:bar` and `/foo/*wildcard`) +* Small (but enough) URL router API +* HTTP request multiplexer like `http.ServeMux` + +## Installation + + go get -u github.com/go-openapi/runtime/middleware/denco + +## Using as HTTP request multiplexer + +```go +package main + +import ( + "fmt" + "log" + "net/http" + + "github.com/go-openapi/runtime/middleware/denco" +) + +func Index(w http.ResponseWriter, r *http.Request, params denco.Params) { + fmt.Fprintf(w, "Welcome to Denco!\n") +} + +func User(w http.ResponseWriter, r *http.Request, params denco.Params) { + fmt.Fprintf(w, "Hello %s!\n", params.Get("name")) +} + +func main() { + mux := denco.NewMux() + handler, err := mux.Build([]denco.Handler{ + mux.GET("/", Index), + mux.GET("/user/:name", User), + mux.POST("/user/:name", User), + }) + if err != nil { + panic(err) + } + log.Fatal(http.ListenAndServe(":8080", handler)) +} +``` + +## Using as URL router + +```go +package main + +import ( + "fmt" + + "github.com/go-openapi/runtime/middleware/denco" +) + +type route struct { + name string +} + +func main() { + router := denco.New() + router.Build([]denco.Record{ + {"/", &route{"root"}}, + {"/user/:id", &route{"user"}}, + {"/user/:name/:id", &route{"username"}}, + {"/static/*filepath", &route{"static"}}, + }) + + data, params, found := router.Lookup("/") + // print `&main.route{name:"root"}, denco.Params(nil), true`. + fmt.Printf("%#v, %#v, %#v\n", data, params, found) + + data, params, found = router.Lookup("/user/hoge") + // print `&main.route{name:"user"}, denco.Params{denco.Param{Name:"id", Value:"hoge"}}, true`. + fmt.Printf("%#v, %#v, %#v\n", data, params, found) + + data, params, found = router.Lookup("/user/hoge/7") + // print `&main.route{name:"username"}, denco.Params{denco.Param{Name:"name", Value:"hoge"}, denco.Param{Name:"id", Value:"7"}}, true`. + fmt.Printf("%#v, %#v, %#v\n", data, params, found) + + data, params, found = router.Lookup("/static/path/to/file") + // print `&main.route{name:"static"}, denco.Params{denco.Param{Name:"filepath", Value:"path/to/file"}}, true`. + fmt.Printf("%#v, %#v, %#v\n", data, params, found) +} +``` + +See [Godoc](http://godoc.org/github.com/go-openapi/runtime/middleware/denco) for more details. + +## Getting the value of path parameter + +You can get the value of path parameter by 2 ways. + +1. Using [`denco.Params.Get`](http://godoc.org/github.com/go-openapi/runtime/middleware/denco#Params.Get) method +2. Find by loop + +```go +package main + +import ( + "fmt" + + "github.com/go-openapi/runtime/middleware/denco" +) + +func main() { + router := denco.New() + if err := router.Build([]denco.Record{ + {"/user/:name/:id", "route1"}, + }); err != nil { + panic(err) + } + + // 1. Using denco.Params.Get method. + _, params, _ := router.Lookup("/user/alice/1") + name := params.Get("name") + if name != "" { + fmt.Printf("Hello %s.\n", name) // prints "Hello alice.". + } + + // 2. Find by loop. + for _, param := range params { + if param.Name == "name" { + fmt.Printf("Hello %s.\n", name) // prints "Hello alice.". + } + } +} +``` + +## URL patterns + +Denco's route matching strategy is "most nearly matching". + +When routes `/:name` and `/alice` have been built, URI `/alice` matches the route `/alice`, not `/:name`. +Because URI `/alice` is more match with the route `/alice` than `/:name`. + +For more example, when routes below have been built: + +``` +/user/alice +/user/:name +/user/:name/:id +/user/alice/:id +/user/:id/bob +``` + +Routes matching are: + +``` +/user/alice => "/user/alice" (no match with "/user/:name") +/user/bob => "/user/:name" +/user/naoina/1 => "/user/:name/1" +/user/alice/1 => "/user/alice/:id" (no match with "/user/:name/:id") +/user/1/bob => "/user/:id/bob" (no match with "/user/:name/:id") +/user/alice/bob => "/user/alice/:id" (no match with "/user/:name/:id" and "/user/:id/bob") +``` + +## Limitation + +Denco has some limitations below. + +* Number of param records (such as `/:name`) must be less than 2^22 +* Number of elements of internal slice must be less than 2^22 + +## Benchmarks + + cd $GOPATH/github.com/go-openapi/runtime/middleware/denco + go test -bench . -benchmem + +## License + +Denco is licensed under the MIT License. +# runtime [![Build Status](https://github.com/go-openapi/runtime/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/runtime/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/runtime/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/runtime) + +[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) +[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/runtime/master/LICENSE) +[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/runtime.svg)](https://pkg.go.dev/github.com/go-openapi/runtime) +[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/runtime)](https://goreportcard.com/report/github.com/go-openapi/runtime) + +# go OpenAPI toolkit runtime + +The runtime component for use in code generation or as untyped usage. +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at ivan+abuse@flanders.co.nz. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ +## Contribution Guidelines + +### Pull requests are always welcome + +We are always thrilled to receive pull requests, and do our best to +process them as fast as possible. Not sure if that typo is worth a pull +request? Do it! We will appreciate it. + +If your pull request is not accepted on the first try, don't be +discouraged! If there's a problem with the implementation, hopefully you +received feedback on what to improve. + +We're trying very hard to keep go-swagger lean and focused. We don't want it +to do everything for everybody. This means that we might decide against +incorporating a new feature. However, there might be a way to implement +that feature *on top of* go-swagger. + + +### Conventions + +Fork the repo and make changes on your fork in a feature branch: + +- If it's a bugfix branch, name it XXX-something where XXX is the number of the + issue +- If it's a feature branch, create an enhancement issue to announce your + intentions, and name it XXX-something where XXX is the number of the issue. + +Submit unit tests for your changes. Go has a great test framework built in; use +it! Take a look at existing tests for inspiration. Run the full test suite on +your branch before submitting a pull request. + +Update the documentation when creating or modifying features. Test +your documentation changes for clarity, concision, and correctness, as +well as a clean documentation build. See ``docs/README.md`` for more +information on building the docs and how docs get released. + +Write clean code. Universally formatted code promotes ease of writing, reading, +and maintenance. Always run `gofmt -s -w file.go` on each changed file before +committing your changes. Most editors have plugins that do this automatically. + +Pull requests descriptions should be as clear as possible and include a +reference to all the issues that they address. + +Pull requests must not contain commits from other users or branches. + +Commit messages must start with a capitalized and short summary (max. 50 +chars) written in the imperative, followed by an optional, more detailed +explanatory text which is separated from the summary by an empty line. + +Code review comments may be added to your pull request. Discuss, then make the +suggested modifications and push additional commits to your feature branch. Be +sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you +comment. + +Before the pull request is merged, make sure that you squash your commits into +logical units of work using `git rebase -i` and `git push -f`. After every +commit the test suite should be passing. Include documentation changes in the +same commit so that a revert would remove all traces of the feature or fix. + +Commits that fix or close an issue should include a reference like `Closes #XXX` +or `Fixes #XXX`, which will automatically close the issue when merged. + +### Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](http://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign off when creating the git commit via `git commit -s`. +# Loads OAI specs [![Build Status](https://github.com/go-openapi/loads/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/loads/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/loads/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/loads) + +[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/loads/master/LICENSE) [![GoDoc](https://godoc.org/github.com/go-openapi/loads?status.svg)](http://godoc.org/github.com/go-openapi/loads) +[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/loads)](https://goreportcard.com/report/github.com/go-openapi/loads) + +Loading of OAI specification documents from local or remote locations. Supports JSON and YAML documents. +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at ivan+abuse@flanders.co.nz. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ +## Contribution Guidelines + +### Pull requests are always welcome + +We are always thrilled to receive pull requests, and do our best to +process them as fast as possible. Not sure if that typo is worth a pull +request? Do it! We will appreciate it. + +If your pull request is not accepted on the first try, don't be +discouraged! If there's a problem with the implementation, hopefully you +received feedback on what to improve. + +We're trying very hard to keep go-swagger lean and focused. We don't want it +to do everything for everybody. This means that we might decide against +incorporating a new feature. However, there might be a way to implement +that feature *on top of* go-swagger. + + +### Conventions + +Fork the repo and make changes on your fork in a feature branch: + +- If it's a bugfix branch, name it XXX-something where XXX is the number of the + issue +- If it's a feature branch, create an enhancement issue to announce your + intentions, and name it XXX-something where XXX is the number of the issue. + +Submit unit tests for your changes. Go has a great test framework built in; use +it! Take a look at existing tests for inspiration. Run the full test suite on +your branch before submitting a pull request. + +Update the documentation when creating or modifying features. Test +your documentation changes for clarity, concision, and correctness, as +well as a clean documentation build. See ``docs/README.md`` for more +information on building the docs and how docs get released. + +Write clean code. Universally formatted code promotes ease of writing, reading, +and maintenance. Always run `gofmt -s -w file.go` on each changed file before +committing your changes. Most editors have plugins that do this automatically. + +Pull requests descriptions should be as clear as possible and include a +reference to all the issues that they address. + +Pull requests must not contain commits from other users or branches. + +Commit messages must start with a capitalized and short summary (max. 50 +chars) written in the imperative, followed by an optional, more detailed +explanatory text which is separated from the summary by an empty line. + +Code review comments may be added to your pull request. Discuss, then make the +suggested modifications and push additional commits to your feature branch. Be +sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you +comment. + +Before the pull request is merged, make sure that you squash your commits into +logical units of work using `git rebase -i` and `git push -f`. After every +commit the test suite should be passing. Include documentation changes in the +same commit so that a revert would remove all traces of the feature or fix. + +Commits that fix or close an issue should include a reference like `Closes #XXX` +or `Fixes #XXX`, which will automatically close the issue when merged. + +### Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](http://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign off when creating the git commit via `git commit -s`. +# OpenAPI analysis [![Build Status](https://github.com/go-openapi/analysis/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/analysis/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/analysis/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/analysis) + +[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) +[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/analysis/master/LICENSE) +[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/analysis.svg)](https://pkg.go.dev/github.com/go-openapi/analysis) +[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/analysis)](https://goreportcard.com/report/github.com/go-openapi/analysis) + + +A foundational library to analyze an OAI specification document for easier reasoning about the content. + +## What's inside? + +* An analyzer providing methods to walk the functional content of a specification +* A spec flattener producing a self-contained document bundle, while preserving `$ref`s +* A spec merger ("mixin") to merge several spec documents into a primary spec +* A spec "fixer" ensuring that response descriptions are non empty + +[Documentation](https://pkg.go.dev/github.com/go-openapi/analysis) + +## FAQ + +* Does this library support OpenAPI 3? + +> No. +> This package currently only supports OpenAPI 2.0 (aka Swagger 2.0). +> There is no plan to make it evolve toward supporting OpenAPI 3.x. +> This [discussion thread](https://github.com/go-openapi/spec/issues/21) relates the full story. +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at ivan+abuse@flanders.co.nz. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ +## Contribution Guidelines + +### Pull requests are always welcome + +We are always thrilled to receive pull requests, and do our best to +process them as fast as possible. Not sure if that typo is worth a pull +request? Do it! We will appreciate it. + +If your pull request is not accepted on the first try, don't be +discouraged! If there's a problem with the implementation, hopefully you +received feedback on what to improve. + +We're trying very hard to keep go-swagger lean and focused. We don't want it +to do everything for everybody. This means that we might decide against +incorporating a new feature. However, there might be a way to implement +that feature *on top of* go-swagger. + + +### Conventions + +Fork the repo and make changes on your fork in a feature branch: + +- If it's a bugfix branch, name it XXX-something where XXX is the number of the + issue +- If it's a feature branch, create an enhancement issue to announce your + intentions, and name it XXX-something where XXX is the number of the issue. + +Submit unit tests for your changes. Go has a great test framework built in; use +it! Take a look at existing tests for inspiration. Run the full test suite on +your branch before submitting a pull request. + +Update the documentation when creating or modifying features. Test +your documentation changes for clarity, concision, and correctness, as +well as a clean documentation build. See ``docs/README.md`` for more +information on building the docs and how docs get released. + +Write clean code. Universally formatted code promotes ease of writing, reading, +and maintenance. Always run `gofmt -s -w file.go` on each changed file before +committing your changes. Most editors have plugins that do this automatically. + +Pull requests descriptions should be as clear as possible and include a +reference to all the issues that they address. + +Pull requests must not contain commits from other users or branches. + +Commit messages must start with a capitalized and short summary (max. 50 +chars) written in the imperative, followed by an optional, more detailed +explanatory text which is separated from the summary by an empty line. + +Code review comments may be added to your pull request. Discuss, then make the +suggested modifications and push additional commits to your feature branch. Be +sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you +comment. + +Before the pull request is merged, make sure that you squash your commits into +logical units of work using `git rebase -i` and `git push -f`. After every +commit the test suite should be passing. Include documentation changes in the +same commit so that a revert would remove all traces of the feature or fix. + +Commits that fix or close an issue should include a reference like `Closes #XXX` +or `Fixes #XXX`, which will automatically close the issue when merged. + +### Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](http://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign off when creating the git commit via `git commit -s`. +# Benchmarking name mangling utilities + +```bash +go test -bench XXX -run XXX -benchtime 30s +``` + +## Benchmarks at b3e7a5386f996177e4808f11acb2aa93a0f660df + +``` +goos: linux +goarch: amd64 +pkg: github.com/go-openapi/swag +cpu: Intel(R) Core(TM) i5-6200U CPU @ 2.30GHz +BenchmarkToXXXName/ToGoName-4 862623 44101 ns/op 10450 B/op 732 allocs/op +BenchmarkToXXXName/ToVarName-4 853656 40728 ns/op 10468 B/op 734 allocs/op +BenchmarkToXXXName/ToFileName-4 1268312 27813 ns/op 9785 B/op 617 allocs/op +BenchmarkToXXXName/ToCommandName-4 1276322 27903 ns/op 9785 B/op 617 allocs/op +BenchmarkToXXXName/ToHumanNameLower-4 895334 40354 ns/op 10472 B/op 731 allocs/op +BenchmarkToXXXName/ToHumanNameTitle-4 882441 40678 ns/op 10566 B/op 749 allocs/op +``` + +## Benchmarks after PR #79 + +~ x10 performance improvement and ~ /100 memory allocations. + +``` +goos: linux +goarch: amd64 +pkg: github.com/go-openapi/swag +cpu: Intel(R) Core(TM) i5-6200U CPU @ 2.30GHz +BenchmarkToXXXName/ToGoName-4 9595830 3991 ns/op 42 B/op 5 allocs/op +BenchmarkToXXXName/ToVarName-4 9194276 3984 ns/op 62 B/op 7 allocs/op +BenchmarkToXXXName/ToFileName-4 17002711 2123 ns/op 147 B/op 7 allocs/op +BenchmarkToXXXName/ToCommandName-4 16772926 2111 ns/op 147 B/op 7 allocs/op +BenchmarkToXXXName/ToHumanNameLower-4 9788331 3749 ns/op 92 B/op 6 allocs/op +BenchmarkToXXXName/ToHumanNameTitle-4 9188260 3941 ns/op 104 B/op 6 allocs/op +``` + +``` +goos: linux +goarch: amd64 +pkg: github.com/go-openapi/swag +cpu: AMD Ryzen 7 5800X 8-Core Processor +BenchmarkToXXXName/ToGoName-16 18527378 1972 ns/op 42 B/op 5 allocs/op +BenchmarkToXXXName/ToVarName-16 15552692 2093 ns/op 62 B/op 7 allocs/op +BenchmarkToXXXName/ToFileName-16 32161176 1117 ns/op 147 B/op 7 allocs/op +BenchmarkToXXXName/ToCommandName-16 32256634 1137 ns/op 147 B/op 7 allocs/op +BenchmarkToXXXName/ToHumanNameLower-16 18599661 1946 ns/op 92 B/op 6 allocs/op +BenchmarkToXXXName/ToHumanNameTitle-16 17581353 2054 ns/op 105 B/op 6 allocs/op +``` + +## Benchmarks at d7d2d1b895f5b6747afaff312dd2a402e69e818b + +go1.24 + +``` +goos: linux +goarch: amd64 +pkg: github.com/go-openapi/swag +cpu: AMD Ryzen 7 5800X 8-Core Processor +BenchmarkToXXXName/ToGoName-16 19757858 1881 ns/op 42 B/op 5 allocs/op +BenchmarkToXXXName/ToVarName-16 17494111 2094 ns/op 74 B/op 7 allocs/op +BenchmarkToXXXName/ToFileName-16 28161226 1492 ns/op 158 B/op 7 allocs/op +BenchmarkToXXXName/ToCommandName-16 23787333 1489 ns/op 158 B/op 7 allocs/op +BenchmarkToXXXName/ToHumanNameLower-16 17537257 2030 ns/op 103 B/op 6 allocs/op +BenchmarkToXXXName/ToHumanNameTitle-16 16977453 2156 ns/op 105 B/op 6 allocs/op +``` + +## Benchmarks after PR #106 + +Moving the scope of everything down to a struct allowed to reduce a bit garbage and pooling. + +On top of that, ToGoName (and thus ToVarName) have been subject to a minor optimization, removing a few allocations. + +Overall timings improve by ~ -10%. + +go1.24 + +``` +goos: linux +goarch: amd64 +pkg: github.com/go-openapi/swag/mangling +cpu: AMD Ryzen 7 5800X 8-Core Processor +BenchmarkToXXXName/ToGoName-16 22496130 1618 ns/op 31 B/op 3 allocs/op +BenchmarkToXXXName/ToVarName-16 22538068 1618 ns/op 33 B/op 3 allocs/op +BenchmarkToXXXName/ToFileName-16 27722977 1236 ns/op 105 B/op 6 allocs/op +BenchmarkToXXXName/ToCommandName-16 27967395 1258 ns/op 105 B/op 6 allocs/op +BenchmarkToXXXName/ToHumanNameLower-16 18587901 1917 ns/op 103 B/op 6 allocs/op +BenchmarkToXXXName/ToHumanNameTitle-16 17193208 2019 ns/op 108 B/op 7 allocs/op +``` +# Swag [![Build Status](https://github.com/go-openapi/swag/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/swag/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/swag/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/swag) + +[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) +[![license](https://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/swag/master/LICENSE) +[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/swag.svg)](https://pkg.go.dev/github.com/go-openapi/swag) +[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/swag)](https://goreportcard.com/report/github.com/go-openapi/swag) + +Package `swag` contains a bunch of helper functions for go-openapi and go-swagger projects. + +You may also use it standalone for your projects. + +> `swag` is one of the foundational building blocks of the go-openapi initiative. +> +> Most repositories in `github.com/go-openapi/...` depend on it in some way. +> So does the CLI tool `github.com/go-swagger/go-swagger`, +> and the code generated by this tool. + +## Contents + +`go-openapi/swag` now exposes a collection of relatively independent modules. + +Here is what is inside: + +* Module `cmdutils` + + * [x] utilities to work with CLIs + +* Module `conv` + + * [x] convert between values and pointers for any types + * [x] convert from string to builtin types (wraps `strconv`) + * [x] require `./typeutils` (test dependency) + +* Module `fileutils` + + * [x] file upload type + * [x] search in path (deprecated) + +* Module `jsonname` + + * [x] infer JSON names from go properties + +* Module `jsonutils` + + * [x] fast json concatenation + * [x] read and write JSON from and to dynamic go data structures + * [x] require `github.com/mailru/easyjson` + +* Module `loading` + + * [x] load from file or http + * [x] require `./yamlutils` + +* Module `mangling` + + * [x] name mangling for go + +* Module `netutils` + + * [x] host, port from address + +* Module `stringutils` + + * [x] search in slice (with case-insensitive) + * [x] split/join query parameters as arrays + +* Module `typeutils` + + * [x] check the zero value for any type + +* Module `yamlutils` + + * [x] converting YAML to JSON + * [x] loading YAML into a dynamic YAML document + * [x] require `./jsonutils` + * [x] require `github.com/mailru/easyjson` + * [x] require `gopkg.in/yaml.v3` + +--- + +The root module `github.com/go-openapi/swag` at the repo level maintains a few +dependencies outside of the standard library: + +* YAML utilities depend on `gopkg.in/yaml.v3` +* JSON utilities `github.com/mailru/easyjson` + +This is not necessarily the case for all sub-modules. + +## Release notes + +### v0.24.0 [Unreleased] + +With this release, we have largely modernized the API of `swag`: + +* The traditional `swag` API is still supported: code that imports `swag` will still + compile and work the same. +* A deprecation notice is published to encourage consumers of this library to adopt + the newer API +* **Deprecation notice** + * configuration through global variables is now deprecated, in favor of options passed as parameters + * all helper functions are moved to more specialized packages, which are exposed as + go modules. Importing such a module would reduce the footprint of dependencies. + * _all_ functions, variables, constants exposed by the deprecated API have now moved, so + that consumers of the new API no longer need to import github.com/go-openapi/swag, but + should import the desired sub-module(s). + +**New with this release**: + +* [x] type converters and pointer to value helpers now support generic types +* [x] name mangling now support pluralized initialisms (issue #46) + Strings like "contact IDs" are now recognized as such a plural form and mangled as a linter would expect. +* [x] performance: small improvements to reduce the overhead of convert/format wrappers (see issues #110, or PR #108) +* [x] performance: name mangling utilities run ~ 10% faster (PR #115) + +--- + +Moving forward, no additional feature will be added to the `swag` API directly. + +However, child modules will continue to evolve or some new ones may be added in the future. + + +#### Note to contributors + +The mono-repo structure comes with some unavoidable extra pains... + +* Testing + +> The usual `go test ./...` command, run from the root of this repo won't work any longer to test all submodules. +> +> Each module constitutes an independant unit of test. So you have to run `go test` inside each module. +> Or you may take a look at how this is achieved by CI +> [here] https://github.com/go-openapi/swag/blob/master/.github/workflows/go-test.yml). +> +> There are also some alternative tricks using `go work`, for local development, if you feel comfortable with +> go workspaces. Perhaps some day, we'll have a `go work test` to run all tests without any hack. + +* Releasing + +> Each module follows its own independant module versioning. +> +> So you have tags like `mangling/v0.24.0`, `fileutils/v0.24.0` etc that are used by `go mod` and `go get` +> to refer to the tagged version of each module specifically. +> +> This means we may release patches etc to each module independently. +> +> We'd like to adopt the rule that modules in this repo would only differ by a patch version +> (e.g. `v0.24.5` vs `v0.24.3`), and we'll level all modules whenever a minor version is introduced. +> +> A script in `./hack` is provided to tag all modules in one go at the same level in one go. + +## Todos, suggestions and plans + +All kinds of contributions are welcome. + +A few ideas: + +* [ ] Complete the split of dependencies to isolate easyjson from the rest +* [ ] Improve mangling utilities (improve readability, support for capitalized words, + better word substitution for non-letter symbols...) +* [ ] Move back to this common shared pot a few of the technical features introduced by go-swagger independently + (e.g. mangle go package names, search package with go modules support, ...) +* [ ] Apply a similar mono-repo approach to go-openapi/strfmt which suffer from similar woes: bloated API, + imposed dependency to some database driver. + +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at ivan+abuse@flanders.co.nz. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ +## Contribution Guidelines + +### Pull requests are always welcome + +We are always thrilled to receive pull requests, and do our best to +process them as fast as possible. Not sure if that typo is worth a pull +request? Do it! We will appreciate it. + +If your pull request is not accepted on the first try, don't be +discouraged! If there's a problem with the implementation, hopefully you +received feedback on what to improve. + +We're trying very hard to keep go-swagger lean and focused. We don't want it +to do everything for everybody. This means that we might decide against +incorporating a new feature. However, there might be a way to implement +that feature *on top of* go-swagger. + + +### Conventions + +Fork the repo and make changes on your fork in a feature branch: + +- If it's a bugfix branch, name it XXX-something where XXX is the number of the + issue +- If it's a feature branch, create an enhancement issue to announce your + intentions, and name it XXX-something where XXX is the number of the issue. + +Submit unit tests for your changes. Go has a great test framework built in; use +it! Take a look at existing tests for inspiration. Run the full test suite on +your branch before submitting a pull request. + +Update the documentation when creating or modifying features. Test +your documentation changes for clarity, concision, and correctness, as +well as a clean documentation build. See ``docs/README.md`` for more +information on building the docs and how docs get released. + +Write clean code. Universally formatted code promotes ease of writing, reading, +and maintenance. Always run `gofmt -s -w file.go` on each changed file before +committing your changes. Most editors have plugins that do this automatically. + +Pull requests descriptions should be as clear as possible and include a +reference to all the issues that they address. + +Pull requests must not contain commits from other users or branches. + +Commit messages must start with a capitalized and short summary (max. 50 +chars) written in the imperative, followed by an optional, more detailed +explanatory text which is separated from the summary by an empty line. + +Code review comments may be added to your pull request. Discuss, then make the +suggested modifications and push additional commits to your feature branch. Be +sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you +comment. + +Before the pull request is merged, make sure that you squash your commits into +logical units of work using `git rebase -i` and `git push -f`. After every +commit the test suite should be passing. Include documentation changes in the +same commit so that a revert would remove all traces of the feature or fix. + +Commits that fix or close an issue should include a reference like `Closes #XXX` +or `Fixes #XXX`, which will automatically close the issue when merged. + +### Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](http://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign off when creating the git commit via `git commit -s`. +# Strfmt [![Build Status](https://github.com/go-openapi/strfmt/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/strfmt/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/strfmt/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/strfmt) +[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) +[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/strfmt/master/LICENSE) +[![GoDoc](https://godoc.org/github.com/go-openapi/strfmt?status.svg)](http://godoc.org/github.com/go-openapi/strfmt) +[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/strfmt)](https://goreportcard.com/report/github.com/go-openapi/strfmt) + +This package exposes a registry of data types to support string formats in the go-openapi toolkit. + +strfmt represents a well known string format such as credit card or email. The go toolkit for OpenAPI specifications knows how to deal with those. + +## Supported data formats +go-openapi/strfmt follows the swagger 2.0 specification with the following formats +defined [here](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types). + +It also provides convenient extensions to go-openapi users. + +- [x] JSON-schema draft 4 formats + - date-time + - email + - hostname + - ipv4 + - ipv6 + - uri +- [x] swagger 2.0 format extensions + - binary + - byte (e.g. base64 encoded string) + - date (e.g. "1970-01-01") + - password +- [x] go-openapi custom format extensions + - bsonobjectid (BSON objectID) + - creditcard + - duration (e.g. "3 weeks", "1ms") + - hexcolor (e.g. "#FFFFFF") + - isbn, isbn10, isbn13 + - mac (e.g "01:02:03:04:05:06") + - rgbcolor (e.g. "rgb(100,100,100)") + - ssn + - uuid, uuid3, uuid4, uuid5 + - cidr (e.g. "192.0.2.1/24", "2001:db8:a0b:12f0::1/32") + - ulid (e.g. "00000PP9HGSBSSDZ1JTEXBJ0PW", [spec](https://github.com/ulid/spec)) + +> NOTE: as the name stands for, this package is intended to support string formatting only. +> It does not provide validation for numerical values with swagger format extension for JSON types "number" or +> "integer" (e.g. float, double, int32...). + +## Type conversion + +All types defined here are stringers and may be converted to strings with `.String()`. +Note that most types defined by this package may be converted directly to string like `string(Email{})`. + +`Date` and `DateTime` may be converted directly to `time.Time` like `time.Time(Time{})`. +Similarly, you can convert `Duration` to `time.Duration` as in `time.Duration(Duration{})` + +## Using pointers + +The `conv` subpackage provides helpers to convert the types to and from pointers, just like `go-openapi/swag` does +with primitive types. + +## Format types +Types defined in strfmt expose marshaling and validation capabilities. + +List of defined types: +- Base64 +- CreditCard +- Date +- DateTime +- Duration +- Email +- HexColor +- Hostname +- IPv4 +- IPv6 +- CIDR +- ISBN +- ISBN10 +- ISBN13 +- MAC +- ObjectId +- Password +- RGBColor +- SSN +- URI +- UUID +- UUID3 +- UUID4 +- UUID5 +- [ULID](https://github.com/ulid/spec) +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at ivan+abuse@flanders.co.nz. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ +## Contribution Guidelines + +### Pull requests are always welcome + +We are always thrilled to receive pull requests, and do our best to +process them as fast as possible. Not sure if that typo is worth a pull +request? Do it! We will appreciate it. + +If your pull request is not accepted on the first try, don't be +discouraged! If there's a problem with the implementation, hopefully you +received feedback on what to improve. + +We're trying very hard to keep go-swagger lean and focused. We don't want it +to do everything for everybody. This means that we might decide against +incorporating a new feature. However, there might be a way to implement +that feature *on top of* go-swagger. + + +### Conventions + +Fork the repo and make changes on your fork in a feature branch: + +- If it's a bugfix branch, name it XXX-something where XXX is the number of the + issue +- If it's a feature branch, create an enhancement issue to announce your + intentions, and name it XXX-something where XXX is the number of the issue. + +Submit unit tests for your changes. Go has a great test framework built in; use +it! Take a look at existing tests for inspiration. Run the full test suite on +your branch before submitting a pull request. + +Update the documentation when creating or modifying features. Test +your documentation changes for clarity, concision, and correctness, as +well as a clean documentation build. See ``docs/README.md`` for more +information on building the docs and how docs get released. + +Write clean code. Universally formatted code promotes ease of writing, reading, +and maintenance. Always run `gofmt -s -w file.go` on each changed file before +committing your changes. Most editors have plugins that do this automatically. + +Pull requests descriptions should be as clear as possible and include a +reference to all the issues that they address. + +Pull requests must not contain commits from other users or branches. + +Commit messages must start with a capitalized and short summary (max. 50 +chars) written in the imperative, followed by an optional, more detailed +explanatory text which is separated from the summary by an empty line. + +Code review comments may be added to your pull request. Discuss, then make the +suggested modifications and push additional commits to your feature branch. Be +sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you +comment. + +Before the pull request is merged, make sure that you squash your commits into +logical units of work using `git rebase -i` and `git push -f`. After every +commit the test suite should be passing. Include documentation changes in the +same commit so that a revert would remove all traces of the feature or fix. + +Commits that fix or close an issue should include a reference like `Closes #XXX` +or `Fixes #XXX`, which will automatically close the issue when merged. + +### Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](http://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign off when creating the git commit via `git commit -s`. +# blag blah +# blag blah + +Ordered list: + + 1. xyz + 2. abc + +First list: + + - a + - b + - c + +Second list: + + * A + * B + * C + +Another Ordered list: + + 0. xyz + 0. abc +# OpenAPI errors [![Build Status](https://github.com/go-openapi/errors/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/errors/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/errors/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/errors) + +[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) +[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/errors/master/LICENSE) +[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/errors.svg)](https://pkg.go.dev/github.com/go-openapi/errors) +[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/errors)](https://goreportcard.com/report/github.com/go-openapi/errors) + +Shared errors and error interface used throughout the various libraries found in the go-openapi toolkit. +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at ivan+abuse@flanders.co.nz. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ +## Contribution Guidelines + +### Pull requests are always welcome + +We are always thrilled to receive pull requests, and do our best to +process them as fast as possible. Not sure if that typo is worth a pull +request? Do it! We will appreciate it. + +If your pull request is not accepted on the first try, don't be +discouraged! If there's a problem with the implementation, hopefully you +received feedback on what to improve. + +We're trying very hard to keep go-swagger lean and focused. We don't want it +to do everything for everybody. This means that we might decide against +incorporating a new feature. However, there might be a way to implement +that feature *on top of* go-swagger. + + +### Conventions + +Fork the repo and make changes on your fork in a feature branch: + +- If it's a bugfix branch, name it XXX-something where XXX is the number of the + issue +- If it's a feature branch, create an enhancement issue to announce your + intentions, and name it XXX-something where XXX is the number of the issue. + +Submit unit tests for your changes. Go has a great test framework built in; use +it! Take a look at existing tests for inspiration. Run the full test suite on +your branch before submitting a pull request. + +Update the documentation when creating or modifying features. Test +your documentation changes for clarity, concision, and correctness, as +well as a clean documentation build. See ``docs/README.md`` for more +information on building the docs and how docs get released. + +Write clean code. Universally formatted code promotes ease of writing, reading, +and maintenance. Always run `gofmt -s -w file.go` on each changed file before +committing your changes. Most editors have plugins that do this automatically. + +Pull requests descriptions should be as clear as possible and include a +reference to all the issues that they address. + +Pull requests must not contain commits from other users or branches. + +Commit messages must start with a capitalized and short summary (max. 50 +chars) written in the imperative, followed by an optional, more detailed +explanatory text which is separated from the summary by an empty line. + +Code review comments may be added to your pull request. Discuss, then make the +suggested modifications and push additional commits to your feature branch. Be +sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you +comment. + +Before the pull request is merged, make sure that you squash your commits into +logical units of work using `git rebase -i` and `git push -f`. After every +commit the test suite should be passing. Include documentation changes in the +same commit so that a revert would remove all traces of the feature or fix. + +Commits that fix or close an issue should include a reference like `Closes #XXX` +or `Fixes #XXX`, which will automatically close the issue when merged. + +### Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](http://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign off when creating the git commit via `git commit -s`. +Evaluate: + +* markdownlint + * assessment: go + * used by opentelemetry/opentelemetry-go + * packaged as github action +* misspell +* spellcheck +* govulncheck +* [x] godoc-lint: + * assessment: no go + * too simplistic: no real value added + * not integrated into golangci's suite of linters + * no packaged github action +

dfkjfkfj

+ + +ERGGLGKLK +========== +this is a title +# .github +Default github settings for go-openapi repositories +--- +name: '❓ Question' +about: I have a question about this project +title: '' +labels: [question] +assignees: '' + +--- + +**Question** + + +**Additional context** + +--- +name: '➕ Feature request' +about: Suggest an idea for this project +title: '' +labels: [enhancement] +assignees: '' + +--- + +**Is your feature request related to a problem? Please describe.** + + +**Describe the solution you'd like** + + +**Describe alternatives you've considered** + + +**Additional context** + +--- +name: '🐞 Bug report' +about: Create a report to help us make go-openapi a great project +title: '' +labels: [bug] +assignees: '' + +--- + +**Describe the bug** + + +**Steps to Reproduce** + + + + +**Expected behavior** + + +**Actual behavior** + + +**Environment** + + +**Additional context** + +## Change type + +Please select: 🆕 New feature or enhancement|🔧 Bug fix'|📃 Documentation update + +## Short description + + +## Fixes + + +## Full description + + + + +## Checklist + + + +* [ ] I have signed all my commits with my name and email (see [DCO](https://github.com/apps/dco). **This does not require a PGP-signed commit** +* [ ] I have rebased and squashed my work, so only one commit remains +* [ ] I have added tests to cover my changes. +* [ ] I have properly enriched go doc comments in code. +* [ ] I have properly documented any breaking change. +## Change type: 📃 Documentation update + +## Short description + + +## Fixes + + +## Checklist + + + +* [ ] I have signed all my commits with my name and email (see [DCO](https://github.com/apps/dco). **This does not require a PGP-signed commit** +* [ ] I have rebased and squashed my work, so only one commit remains +* [ ] I have signed all my commits with my name and email (see DCO: https://github.com/apps/dco). **This does not require a PGP-signed commit** +* [ ] I have rebased and squash my work, so only one commit remains +* [ ] I have only modified comments in code or markdown files +## Change type: 🆕 New feature or enhancement + +## Short description + + +## Fixes + + +## Checklist + + + +* [ ] I have signed all my commits with my name and email (see [DCO](https://github.com/apps/dco). **This does not require a PGP-signed commit** +* [ ] I have rebased and squashed my work, so only one commit remains +* [ ] I have added tests to cover my changes. +* [ ] I have properly enriched go doc comments in code. +* [ ] I have properly documented any breaking change. +## Change type: 🔧 Bug fix + +## Short description + + +## Fixes + + +## Full description + + + + +## Checklist + + + +* [ ] I have signed all my commits with my name and email (see [DCO](https://github.com/apps/dco). **This does not require a PGP-signed commit** +* [ ] I have rebased and squashed my work, so only one commit remains +* [ ] I have added tests to cover my changes. +* [ ] I have made sure that my code remains portable +* [ ] I have properly enriched go doc comments in code. +* [ ] I have properly documented any breaking change. +# OpenAPI initiative random data generator [![Build Status](https://travis-ci.org/go-openapi/stubs.svg?branch=master)](https://travis-ci.org/go-openapi/stubs) [![codecov](https://codecov.io/gh/go-openapi/stubs/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/stubs) [![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) + +[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/stubs/master/LICENSE) [![GoDoc](https://godoc.org/github.com/go-openapi/stubs?status.svg)](http://godoc.org/github.com/go-openapi/stubs) + + +A library to generate random data for a swagger specification. +This is a building block for generating stubs for your API as well as tests. +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at ivan+abuse@flanders.co.nz. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ +# Stubs design + +The goal of this library is to be able to generate somewhat good looking random data for structures defined in an openapi or jsonschema document. +These can be used to provide an api with stubs so that you can verify valid and invalid request/responses without an actually meaningful implementation. +Some areas where this is useful are collaboration between different teams so that all teams can do work without having to wait on the delivery of the completed implementation of the API. +A second area where this is obviously useful is for doing automated tests and filling up datastructures for use in those tests. + + +In the openapi 2.0 specification there are 2 families of types that can be used as targets for a random data generator. + +1. Path Item related types + 1. Non-Schema Parameters + 2. Response headers + 3. Collection Items on parameters or headers +2. Schemas + +These 2 families warrant slightly different strategies for getting the necessary parameters for a datagenerator. + +## Functionality + +To generate meaningful random data the library looks at the schema and based on properties for that schema it picks an appropriate random value generator. +This means that when it is generating a string for an object property that represents a first name it should pick a data generator that generates first names. +Similarly should a property be called city it should generate a city name. + +It's possible that the validity of a particular property is dependent on the value of another property, for example a creation date is typically never larger than a modified date. + +A data generator for a schema should be able to generate valid and invalid data, ideally there is control for specifying the value is invalid for a particular validation. This will help in tests to validate error codes + +## How does it work + +The main components in this library are a registry of datagenerators so they are addressable by keys, aliases for those keys to aid with inferring which datagenerator to use. +And of course a value generator, which will generate either a valid or an invalid value. + +In the openapi API document and in a json schema document there is a vendor extension that can be used to customize the generation process. + +### Value generator function + +There are 2 types of data generators but they both have the same function signature. +There are value generators and there are composite value generators. + +* A value generator generates a single value for a simple type. +* A composite generator generates a value that is built out of one or more generators eg. object schemas with properties. + +The signature for the value generator is: + +```go +type ValueGenerator func(GeneratorOpts) (interface{}, error) +``` + +A value generator is the innermost component in the library and the arguments to the function are used to configure the generator. +The generation process for a generator is configured through a GeneratorOpts interface. + +### GeneratorOpts interface + +The generator options describe the type and potentially the format for the value that needs to be generated. +In addition to the type information it also captures the field name or definition name of the value that needs to be generated. + +### StubMode + +The stubmode bitmask allows for configuring which validations should fail for a given value generator. + +### Generator + +The generator is the main entry point for the library and its Generate method is what will generate the random value for the descriptor. +# Use cases for stubs + +The stubs package is intended to support the following use cases: + +1. Generate unit test cases for code generated by go-swagger, especially validation code +2. Generate test cases for API servers and clients +3. Generate realistic examples + +## Supported swagger 2.0 constructs + +- parameter +- header +- response +- schema, including support for: + - [] AllOf + - [] Not + - [] additionalProperties + - [] patternProperties + - [] additionalItems + +Formated strings and numbers support go-openapi/strfmt formats, including: + - [] binary (strfmt.Base64) + - [] bsonobjectid + +The "file" datatype is not supported at the moment. + +The generation assumes the provide swagger spec is valid. + +Warnings regarding test case (2): +- stubs is not concerned about security definitions and credentials +- stubs generates values independently for each parameter, or response: it does not know about consistent sets of values beyond validation constraints, let alone + proper chaining of request with responses. + +## Sample applications for stubs + +- process a spec to include examples +- generate fixtures for codegen unit testing +- generate fixtures for API server benchmarking +- ... + +# Reproducible stubs + +Generated stubs may be regenerated using the same initial seed. + +There are two seeding modes to run the stubs generator: + +- AutoSeed: reseeds itself based on current timestamp +- SetSeed: generation occurs with a single seed, provided by the caller + +The package uses a default seeder to carry on this task. Alternate seeders might be provided. + +This also allows for unit testing this very package... + +# Setting generation goals + +Goals select the general use case and allow for fine tuning of the sample generation. + +We use GenerateMode and StubMode flags to define goals. + +Stubmode is used to tune individually every single generated value. + +GenerateMode sets general directives and may define StubMode autonomously according to the generation goal. + +## GenerateMode + +target: +- unitTest: any value value may be produced, not necessarily a realistic definevalue. + By default in the UnitTest mode, non-formated strings are loren ipsums, numbers, dates and times may be very small or very large +- examples: the generator attempts to figure out realistic values to be used as examples + +GenerateMode accepts arguments to further specify the expected generation: + +args: +- valid: all generated values are valid. This is the default. + - count: number of samples to be generated. May be zero to get only default, examples, edge cases or validation checks. Default is 1. +- invalid: all generated values are invalid, with failures chosen at random. + - count: number of samples to be generated. Default is 1. +- skipTilting: tilting rules are omitted (only applies to invalid values). Default is true in unit test mode and false in example mode. +- skipFuzzying: fuzzying rules are omitted +- withTilting: add tilted invalid values, with failures chosen at random. This forces a tilting strategy on a new set of values. + - count: number of tilted samples to be generated. Default is 1. +- withValidationCheck: for each validation, an invalid value against this validation is generated (e.g. if min and max are specified, we have one value below min and one value above max) + - count: this sets a limit on the count of generated values. If you have n validations, that makes n generated values. With the limit set, validations are checked width-first (outermost validations come first) +- withAllValidationChecks: all combinations of failed validations are generated. This includes one valid value and single failure from withValidation. + - count: this sets a limit on the count of generated values. If you have n validations, that makes 2^n generated values, which may raise quickly when nesting schema structures. With the limit set, validations are checked width-first (outermost validations come first) +- withDefault: add default value to sample values (not included in "count"). This simulates a user providing exactly the same value as the default. Since defaults may be set at different levels of the structure, a new value is generated for each applicable default. +- withExample: add example value to sample values (not included in "count"), whenever applicable. Examples are assumed valid, but may be invalid. + - tiltDefault: constructs invalid values by tilting default + - tiltExample: constructs invalid values by tilting examples + - count: number of title +- withEdgeCase: + - standard: standard preconfigured edge cases (e.g. boundary value for min constraint with boundary included, Feb 29th dates for date types, ...) + - value: a customizable value added as an edge case. May be any value, array or object. Severa values may be specified. +- max: an upper limit on number generation (floats, ints, ...). By default, the full range of the data type is used. +- min: a lower limit on number generation. +- precision: rounding specification for floats +- multipleOf: a multiple specification for numbers +- length: + - on string values: an upper limit on string size, to avoid long texts being unwittingly generated + - on array values: an upper limit on the number of generated items + - on additionalProperties: an upper limit on the number of generated additionalProperties + - on patternProperties: an upper limit on the number of generated patternProperties +- words: a limit on the number of words in generated texts, paragraphs and sentences +- lang: specifies the target language(s) for strings and text. + - [lang] + - all: special value to tell the generator to pick text at random from all supported languages + +This sets an overall target for all generations. For every single spec object, you may hint further and override global settings on a case by case basis. + +# Hinting + +The `x-datagen` extension may be used in the swagger spec to hint the stubs generator. + +Examples: +``` +parameters: + phone: + in: query + required: true + type: string + x-datagen: + name: mobile +``` +will generate a mobile phone number for query parameter "phone". + +``` +parameters: + price: + in: query + required: true + type: string + x-datagen: + name: float +``` +will generate float numbers for the price parameter. +It might be not realistic to have 3.1344344E35 as a price, but it is a valid value... + +`x-datagen` accepts args to further hint the generator. +All Args accepted by GenerateMode or StubMode may be used here to locally override generation options. + +Example: +``` +parameters: + vat: + in: query + required: true + type: number + x-datagen: + args: + min: 100 + max: 10000 + +``` +will generate floats between 100 and 10000. +Again, it might not be realistic to have prices such as 503.14561434566... + +Some generators are already configured to suit some targeted usage. + +Example: +``` +parameters: + price: + in: query + required: true + type: string + x-datagen: + name: small-amounts +``` +and you get more realistic values like 3.23, 104.30... + +## x-datagen args + +- name: overrides the generator's name + +Supported args, not already mentioned in the GenerateMode section: +- args: + +# Fuzzying + +The generation takes basic decisions based on type and available validation constraints. +Obviously, this does not work well when the goal is to generate realistic samples for your data. +Of course, everyhing may be fine-tuned by using the x-datagen extension. +But this is tedious work on large specs. + +We introduce fuzzying as a way to carry on some of the guesswork when deciding which kind of fake value would best match expectations. +Fuzzying relies on names, titles and description to look for recognizable keywords, then elects an adequate random generator. + +Examples for the above samples: +- with name "price", the fuzzying guesses that it is not some arbitrary float to be generated, but a decimal between 0 and 1,000,000 (max overrides this limit). +- with a description such as "The item price expressed in USD. Items are sold at a low price", fuzzying rules should guess that we want to generate small-amount values (so between 0 and 1,000). + +Fuzzying also works for non-strings data: +- a date field named "birthday" would hint toward the birthdate value generator (hence dates are not in the future and only in a recent past) +- a datetime named "timestamp" or described as "The update date" would generate a recent datetime value. Further, edge cases with this guess would add 01/01/1970 to the generated value + +# Tilting + +Tilting is a strategy to generate invalid values, by tilting a valid value just enough so it becomes invalid. +This generates interesting test cases since values are supposed to be "almost" valid but actually are not. + +Tilting strategies depend on validations. + +Examples: +- tilting on max will generate a value at or slightly above the lowest invalid value +- tilting on regexp will change the smallest number of characters in a string so the regexp no more matches +- tilting on enum will slightly modify a valid value and make it invalid +- ... + +Options skipTilting and withTilting tune the generator behavior regarding tilting. +# gojsonpointer [![Build Status](https://github.com/go-openapi/jsonpointer/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/jsonpointer/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/jsonpointer/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/jsonpointer) + +[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) +[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/jsonpointer/master/LICENSE) +[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/jsonpointer.svg)](https://pkg.go.dev/github.com/go-openapi/jsonpointer) +[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/jsonpointer)](https://goreportcard.com/report/github.com/go-openapi/jsonpointer) + +An implementation of JSON Pointer - Go language + +## Status +Completed YES + +Tested YES + +## References +http://tools.ietf.org/html/draft-ietf-appsawg-json-pointer-07 + +### Note +The 4.Evaluation part of the previous reference, starting with 'If the currently referenced value is a JSON array, the reference token MUST contain either...' is not implemented. +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at ivan+abuse@flanders.co.nz. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ +## Contribution Guidelines + +### Pull requests are always welcome + +We are always thrilled to receive pull requests, and do our best to +process them as fast as possible. Not sure if that typo is worth a pull +request? Do it! We will appreciate it. + +If your pull request is not accepted on the first try, don't be +discouraged! If there's a problem with the implementation, hopefully you +received feedback on what to improve. + +We're trying very hard to keep go-swagger lean and focused. We don't want it +to do everything for everybody. This means that we might decide against +incorporating a new feature. However, there might be a way to implement +that feature *on top of* go-swagger. + + +### Conventions + +Fork the repo and make changes on your fork in a feature branch: + +- If it's a bugfix branch, name it XXX-something where XXX is the number of the + issue +- If it's a feature branch, create an enhancement issue to announce your + intentions, and name it XXX-something where XXX is the number of the issue. + +Submit unit tests for your changes. Go has a great test framework built in; use +it! Take a look at existing tests for inspiration. Run the full test suite on +your branch before submitting a pull request. + +Update the documentation when creating or modifying features. Test +your documentation changes for clarity, concision, and correctness, as +well as a clean documentation build. See ``docs/README.md`` for more +information on building the docs and how docs get released. + +Write clean code. Universally formatted code promotes ease of writing, reading, +and maintenance. Always run `gofmt -s -w file.go` on each changed file before +committing your changes. Most editors have plugins that do this automatically. + +Pull requests descriptions should be as clear as possible and include a +reference to all the issues that they address. + +Pull requests must not contain commits from other users or branches. + +Commit messages must start with a capitalized and short summary (max. 50 +chars) written in the imperative, followed by an optional, more detailed +explanatory text which is separated from the summary by an empty line. + +Code review comments may be added to your pull request. Discuss, then make the +suggested modifications and push additional commits to your feature branch. Be +sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you +comment. + +Before the pull request is merged, make sure that you squash your commits into +logical units of work using `git rebase -i` and `git push -f`. After every +commit the test suite should be passing. Include documentation changes in the +same commit so that a revert would remove all traces of the feature or fix. + +Commits that fix or close an issue should include a reference like `Closes #XXX` +or `Fixes #XXX`, which will automatically close the issue when merged. + +### Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](http://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign off when creating the git commit via `git commit -s`. diff --git a/README.md b/README.md index e469436..9631908 100644 --- a/README.md +++ b/README.md @@ -5,11 +5,11 @@ [![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/ci-workflows.svg)](https://pkg.go.dev/github.com/go-openapi/ci-workflows) [![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/ci-workflows)](https://goreportcard.com/report/github.com/go-openapi/ci-workflows) -Common CI workflows and setup for go-openapi repos. +Common Continuous Integration (`CI`) workflows and setup for go-openapi repos. * shared github action workflows -* shared dependabot config (TODO) -* shared golangci config (**BLOCKED**) +* shared `dependabot` configuration (TODO) +* shared `golangci-lint` configuration (**BLOCKED**) > NOTE: at this moment, it is difficult to share the golangci-lint config, > so that one is not shared yet. @@ -28,12 +28,14 @@ In no particular order: * [x] ui: enrich github actions UI with a job summary * [x] doc: add markdown linting for docs -* [ ] doc: add spellcheck for docs (and code?) +* [x] doc: add spellcheck for docs (and code?) +* [x] introduce config file specific checkout (markdownlint, spellcheck) +* [x] security: separate PR / issue comments as a trusted bot workflow, acting on request artifacts * [ ] version common workflows, so we can limit the impact of a change * [ ] build: verify that go.sum cache for tests works (should be enabled) * [ ] share mono repo workflows (see github.com/go-openapi/swag/.github/workflows) * [ ] lint: manage somehow to share golangci config (with local merge) -* [ ] deps: manage somehow to share / replicate dependabot config +* [ ] dependencies: manage somehow to share / replicate dependabot config * [ ] lint: golangci-lint: check valid PR comments etc * [ ] lint: use non-blocking, scheduled, proactive full linting to check for the impact of new linters, new go versions etc @@ -45,3 +47,8 @@ In no particular order: * [ ] check with github API that all repo settings (branch protection rules, etc) are identical * [ ] comment PRs and issues +* [ ] doc: checkout vale style-check guide (vale-action exists) +* [ ] doc: experiment LanguageTool for grammar checks ( -> a github action / docker image exists) +* [ ] doc: experiment LLM from github model, using embeddings ( -> +* [ ] issues: experiment LLM from github model, using embeddings ( -> show related issues) +* [ ] github pages w/ hugo (like go-swagger, experiment another theme and json data) From 3f3fee5461a068c61a82d0a74a6f6d4ab6a4cc3a Mon Sep 17 00:00:00 2001 From: fredbi Date: Sat, 30 Aug 2025 23:12:59 +0200 Subject: [PATCH 14/28] test spellcheck dict (#9) * test spellcheck dict Signed-off-by: Frederic BIDON * fix permissions Signed-off-by: Frederic BIDON --------- Signed-off-by: Frederic BIDON --- .github/workflows/doc-update.yml | 8 ++++---- .github/workflows/pr-comment.yml | 20 +++++++++++--------- ALL.md | 2 ++ 3 files changed, 17 insertions(+), 13 deletions(-) diff --git a/.github/workflows/doc-update.yml b/.github/workflows/doc-update.yml index 2385cff..9e752d9 100644 --- a/.github/workflows/doc-update.yml +++ b/.github/workflows/doc-update.yml @@ -30,7 +30,7 @@ on: workflow_call: permissions: - pull-requests: read + pull-requests: write contents: read env: @@ -466,14 +466,14 @@ jobs: echo "target_repo=${{ github.repository }}" >> "$GITHUB_OUTPUT" echo "pr_number=${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT" echo "pr_sha=${{ github.event.pull_request.head.sha }}" >> "$GITHUB_OUTPUT" - echo "artifact_name=${{ env.spelling_artifact }}" >> "$GITHUB_OUTPUT" - echo "comment_title=${{ env.spelling_comment_title }}" >> "$GITHUB_OUTPUT" + echo "artifact_name=${{ env.spellcheck_artifact }}" >> "$GITHUB_OUTPUT" + echo "comment_title=${{ env.spellcheck_comment_title }}" >> "$GITHUB_OUTPUT" echo "reactions=confused" >> "$GITHUB_OUTPUT" pr-comment-spelling-report: name: Create or update comment needs: pr-markdown-spelling-report - secrets: inherit + secrets: inherits uses: ./.github/workflows/pr-comment.yml with: run_id: ${{ needs.pr-markdown-spelling-report.outputs.run_id }} diff --git a/.github/workflows/pr-comment.yml b/.github/workflows/pr-comment.yml index 0a36dd4..e1d6657 100644 --- a/.github/workflows/pr-comment.yml +++ b/.github/workflows/pr-comment.yml @@ -113,7 +113,7 @@ jobs: if: ${{ steps.check_pr.outputs.proceed == 'true'}} run: | MESSAGE_FILE="${{ steps.download.outputs.download-path }}/${{ inputs.artifact_name }}" - SIZE=$(wc -c "${MESSAGE_FILE}") + SIZE=$(cat "${MESSAGE_FILE}"|wc -c) if [[ "${SIZE}" -gt "${{ env.MAX_MESSAGE_SIZE }}" ]] ; then # truncate the message up to MAX_MESSAGE_SIZE head -c ${{ env.MAX_MESSAGE_SIZE }} "${MESSAGE_FILE}" > /tmp/truncated @@ -134,13 +134,15 @@ jobs: direction: last token: ${{ secrets.GITHUB_TOKEN }} - - name: Acquire write access to PR - if: ${{ steps.check_pr.outputs.proceed == 'true'}} - id: acquire_write_token - uses: actions/create-github-app-token@v2 - with: - app-id: ${{ secrets.CI_WORKFLOWS_PR_APP_ID }} - private-key: ${{ secrets.CI_WORKFLOWS_PR_APP_PRIVATE_KEY }} + #- name: Acquire write access to PR + # if: ${{ steps.check_pr.outputs.proceed == 'true'}} + # id: acquire_write_token + # uses: actions/create-github-app-token@v2 + # with: + # app-id: ${{ secrets.CI_WORKFLOWS_PR_APP_ID }} + # private-key: ${{ secrets.CI_WORKFLOWS_PR_APP_PRIVATE_KEY }} + # owner: go-openapi + # repo: ${{ inputs.target_repo }} - name: Create or update PR comment if: ${{ steps.check_pr.outputs.proceed == 'true'}} @@ -152,7 +154,7 @@ jobs: reactions-edit-mode: replace body-path: ${{ steps.download.outputs.download-path }}/${{ inputs.artifact_name }} edit-mode: replace - token: ${{ steps.acquire_write_token.outputs.token }} + token: ${{ secrets.GITHUB_TOKEN }} - name: Notify run: | diff --git a/ALL.md b/ALL.md index 2a01e42..f148d87 100644 --- a/ALL.md +++ b/ALL.md @@ -1,3 +1,5 @@ +This is a test of the spellcheck dictionary + # Swagger 2.0 specification schema This folder contains the Swagger 2.0 specification schema files maintained here: From a428e6d21f47cd8f20451de7221dcd7dd75e81e8 Mon Sep 17 00:00:00 2001 From: Frederic BIDON Date: Sun, 31 Aug 2025 08:46:51 +0200 Subject: [PATCH 15/28] fixup Signed-off-by: Frederic BIDON --- .github/workflows/doc-update.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/doc-update.yml b/.github/workflows/doc-update.yml index 9e752d9..698743a 100644 --- a/.github/workflows/doc-update.yml +++ b/.github/workflows/doc-update.yml @@ -473,7 +473,7 @@ jobs: pr-comment-spelling-report: name: Create or update comment needs: pr-markdown-spelling-report - secrets: inherits + secrets: inherit uses: ./.github/workflows/pr-comment.yml with: run_id: ${{ needs.pr-markdown-spelling-report.outputs.run_id }} From ac3c7f3f4e9a3b74db6e0cf11f2a4e679117166c Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Fri, 29 Aug 2025 01:04:24 +0000 Subject: [PATCH 16/28] Bump github.com/stretchr/testify in the development-dependencies group Bumps the development-dependencies group with 1 update: [github.com/stretchr/testify](https://github.com/stretchr/testify). Updates `github.com/stretchr/testify` from 1.10.0 to 1.11.1 - [Release notes](https://github.com/stretchr/testify/releases) - [Commits](https://github.com/stretchr/testify/compare/v1.10.0...v1.11.1) --- updated-dependencies: - dependency-name: github.com/stretchr/testify dependency-version: 1.11.1 dependency-type: direct:production update-type: version-update:semver-minor dependency-group: development-dependencies ... Signed-off-by: dependabot[bot] --- go.mod | 2 +- go.sum | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/go.mod b/go.mod index 51c159d..dd46419 100644 --- a/go.mod +++ b/go.mod @@ -2,7 +2,7 @@ module github.com/go-openapi/ci-workflows go 1.24.2 -require github.com/stretchr/testify v1.10.0 +require github.com/stretchr/testify v1.11.1 require ( github.com/davecgh/go-spew v1.1.1 // indirect diff --git a/go.sum b/go.sum index 713a0b4..c4c1710 100644 --- a/go.sum +++ b/go.sum @@ -2,8 +2,8 @@ github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= -github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA= -github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY= +github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U= +github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= From 88f33c068872555e94011e6ba0e8fbd304f68c79 Mon Sep 17 00:00:00 2001 From: Frederic BIDON Date: Sun, 31 Aug 2025 08:59:17 +0200 Subject: [PATCH 17/28] tidy up Signed-off-by: Frederic BIDON --- .github/workflows/doc-update.yml | 1 - .github/workflows/gists.yml | 11 +++++++++++ .github/workflows/pr-comment.yml | 20 +++++--------------- 3 files changed, 16 insertions(+), 16 deletions(-) create mode 100644 .github/workflows/gists.yml diff --git a/.github/workflows/doc-update.yml b/.github/workflows/doc-update.yml index 698743a..0c9fd0e 100644 --- a/.github/workflows/doc-update.yml +++ b/.github/workflows/doc-update.yml @@ -20,7 +20,6 @@ name: doc update check # # ## TODO # -# * [ ] to refactor repeated jobs as a matrix job? as separate workflow # * [ ] should make an adapted version that runs on schedule and analyzes all markdown. # * [ ] in this case, instead of commenting pull requests, it should raise issues. # * [ ] should be able to retrieve config files and dictionary from the called ref, not master. diff --git a/.github/workflows/gists.yml b/.github/workflows/gists.yml new file mode 100644 index 0000000..0af013d --- /dev/null +++ b/.github/workflows/gists.yml @@ -0,0 +1,11 @@ +# A few useful actions + + #- name: Acquire write access to PR + # if: ${{ steps.check_pr.outputs.proceed == 'true'}} + # id: acquire_write_token + # uses: actions/create-github-app-token@v2 + # with: + # app-id: ${{ secrets.CI_WORKFLOWS_PR_APP_ID }} + # private-key: ${{ secrets.CI_WORKFLOWS_PR_APP_PRIVATE_KEY }} + # owner: go-openapi + # repo: ${{ inputs.target_repo }} diff --git a/.github/workflows/pr-comment.yml b/.github/workflows/pr-comment.yml index e1d6657..0c1d632 100644 --- a/.github/workflows/pr-comment.yml +++ b/.github/workflows/pr-comment.yml @@ -2,10 +2,14 @@ name: pr-comment # description: | # This workflow is a trusted workflow that creates or updates comments in PRs. # -# It may be called by other workflows executing on pull_requests against the go-openapi repos. +# It may be called by other workflows executing on pull_request_target against the go-openapi repos. # # The principle is to communicate the content of a comment between workflows using an uploaded artifact. +permissions: + pull-requests: write + contents: read + on: workflow_call: inputs: @@ -47,10 +51,6 @@ on: type: string required: false -permissions: - pull-requests: read # <- job will exchange token as-needed when it comes to writing. - contents: read - env: GITHUB_API: "https://api.github.com" MAX_MESSAGE_SIZE: 4096 @@ -134,16 +134,6 @@ jobs: direction: last token: ${{ secrets.GITHUB_TOKEN }} - #- name: Acquire write access to PR - # if: ${{ steps.check_pr.outputs.proceed == 'true'}} - # id: acquire_write_token - # uses: actions/create-github-app-token@v2 - # with: - # app-id: ${{ secrets.CI_WORKFLOWS_PR_APP_ID }} - # private-key: ${{ secrets.CI_WORKFLOWS_PR_APP_PRIVATE_KEY }} - # owner: go-openapi - # repo: ${{ inputs.target_repo }} - - name: Create or update PR comment if: ${{ steps.check_pr.outputs.proceed == 'true'}} uses: peter-evans/create-or-update-comment@v4 From f21008f30624c7e722f21d0180846d29a2d6fa0c Mon Sep 17 00:00:00 2001 From: Frederic BIDON Date: Sun, 31 Aug 2025 09:08:21 +0200 Subject: [PATCH 18/28] tested ok: now fix artifact name in check Signed-off-by: Frederic BIDON --- .github/workflows/pr-comment.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/pr-comment.yml b/.github/workflows/pr-comment.yml index 0c1d632..3fc12a1 100644 --- a/.github/workflows/pr-comment.yml +++ b/.github/workflows/pr-comment.yml @@ -37,7 +37,7 @@ on: description: | The reference to the artifact containing the text of the comment. - At this moment, only supports "markdown_comment.txt" and "spelling_comment.txt" + At this moment, only supports "markdown_comment.txt" and "spellcheck_comment.txt" type: string required: true comment_title: From 4663b1c48698c61508b720c278b4022d19191538 Mon Sep 17 00:00:00 2001 From: Frederic BIDON Date: Sun, 31 Aug 2025 09:11:48 +0200 Subject: [PATCH 19/28] tested ok: now fix artifact name in check Signed-off-by: Frederic BIDON --- .github/workflows/pr-comment.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/pr-comment.yml b/.github/workflows/pr-comment.yml index 3fc12a1..1c22e3d 100644 --- a/.github/workflows/pr-comment.yml +++ b/.github/workflows/pr-comment.yml @@ -68,8 +68,8 @@ jobs: echo "This workflow only applies to target repos in github.com/go-openapi." exit 1 fi - if [[ "${{ inputs.artifact_name }}" != "markdown_comment.txt" && "${{ inputs.artifact_name }}" != "spelling_comment.txt" ]] ; then - echo "This workflow only applies to artifacts named markdown_comment.txt or spelling_comment.txt" + if [[ "${{ inputs.artifact_name }}" != "markdown_comment.txt" && "${{ inputs.artifact_name }}" != "spellcheck_comment.txt" ]] ; then + echo "This workflow only applies to artifacts named markdown_comment.txt or spellcheck_comment.txt" exit 1 fi From 1b7da679626cf00134196a0b44ec59d6a2cb3195 Mon Sep 17 00:00:00 2001 From: Frederic BIDON Date: Sun, 31 Aug 2025 09:37:05 +0200 Subject: [PATCH 20/28] tested ok: now make correct truncate Signed-off-by: Frederic BIDON --- .github/workflows/pr-comment.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/pr-comment.yml b/.github/workflows/pr-comment.yml index 1c22e3d..5509847 100644 --- a/.github/workflows/pr-comment.yml +++ b/.github/workflows/pr-comment.yml @@ -117,10 +117,10 @@ jobs: if [[ "${SIZE}" -gt "${{ env.MAX_MESSAGE_SIZE }}" ]] ; then # truncate the message up to MAX_MESSAGE_SIZE head -c ${{ env.MAX_MESSAGE_SIZE }} "${MESSAGE_FILE}" > /tmp/truncated - echo > /tmp/truncated - echo "... (truncated)" > /tmp/truncated + echo >> /tmp/truncated + echo "... (truncated)" >> /tmp/truncated mv /tmp/truncated "${MESSAGE_FILE}" - echo "::warning:: comment message with size ${SIZE} has been truncated to ${{ env.MAX_MESSAGE_SIZE }} bytes." + echo "::warning:: ${{ inputs.artifact_name }} comment message with size ${SIZE} has been truncated to ${{ env.MAX_MESSAGE_SIZE }} bytes." fi - name: Find previous PR comment @@ -148,4 +148,4 @@ jobs: - name: Notify run: | - echo "::notice::Commented pull request ${{ inputs.pr_number }}" + echo "::notice::Commented pull request ${{ inputs.pr_number }} with ${{ inputs.artifact_name }}" From 760cb97fb883090f2ad43327a2cfdd44210af223 Mon Sep 17 00:00:00 2001 From: fredbi Date: Sun, 31 Aug 2025 09:50:19 +0200 Subject: [PATCH 21/28] change md for testing (#12) * change md for testing Signed-off-by: Frederic BIDON * report output verbatim Signed-off-by: Frederic BIDON * report output verbatim Signed-off-by: Frederic BIDON --------- Signed-off-by: Frederic BIDON --- .github/workflows/doc-update.yml | 6 ++++++ .github/workflows/{gists.yml => gists.md} | 0 .github/workflows/go-test.yml | 1 + ALL.md | 2 ++ 4 files changed, 9 insertions(+) rename .github/workflows/{gists.yml => gists.md} (100%) diff --git a/.github/workflows/doc-update.yml b/.github/workflows/doc-update.yml index 0c9fd0e..83c434a 100644 --- a/.github/workflows/doc-update.yml +++ b/.github/workflows/doc-update.yml @@ -304,7 +304,10 @@ jobs: Markdown formatting rules are documented [here](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md).
+ + ``` {{ text }} + ``` - name: Slap on the wrist env: @@ -434,7 +437,10 @@ jobs: This check is advisory only and not blocking. Please help us improve our documentation.
+ + ``` {{ text }} + ``` - name: Slap on the wrist env: diff --git a/.github/workflows/gists.yml b/.github/workflows/gists.md similarity index 100% rename from .github/workflows/gists.yml rename to .github/workflows/gists.md diff --git a/.github/workflows/go-test.yml b/.github/workflows/go-test.yml index a949b61..c7fecd8 100644 --- a/.github/workflows/go-test.yml +++ b/.github/workflows/go-test.yml @@ -19,6 +19,7 @@ name: go test # like all repos to allow users to fork, lint and run just like they were independent, # and not impose some "invisible linter" check. # * [ ] we need to make a specific version for mono-repos. For now, only go-openapi swag is a mono-repo. +# * [ ] detect minimum required go version in go.mod and run a test for that one on: workflow_call: diff --git a/ALL.md b/ALL.md index f148d87..67aeeb4 100644 --- a/ALL.md +++ b/ALL.md @@ -1,5 +1,7 @@ This is a test of the spellcheck dictionary +Bump md + # Swagger 2.0 specification schema This folder contains the Swagger 2.0 specification schema files maintained here: From d1432a4c0f0b8f5ef5450806097fe881e1cec7fb Mon Sep 17 00:00:00 2001 From: Frederic BIDON Date: Sun, 31 Aug 2025 11:05:04 +0200 Subject: [PATCH 22/28] augmented spellcheck wordlist Signed-off-by: Frederic BIDON --- .github/.wordlist.txt | 55 + .github/workflows/doc-update.yml | 5 +- ALL.md | 7262 ------------------------------ 3 files changed, 59 insertions(+), 7263 deletions(-) delete mode 100644 ALL.md diff --git a/.github/.wordlist.txt b/.github/.wordlist.txt index 54a72c0..f6d9f97 100644 --- a/.github/.wordlist.txt +++ b/.github/.wordlist.txt @@ -1,51 +1,106 @@ API +BSON CI +CIDR +CLI DCO DockerHub FAQ +GC +GoDoc +Godoc HUGO ID IDs +IP +IPs +ISBN +Kubernetes Markdown OAI OpenAPI PR PRs +README +SSN TODO UI +ULID +URI +URL USD +UUID api assignees +backquote +backquoted bash +benchmarking bitmask +bson ci +cidr codecov +codegen config +customizable dependabot docker +e.g. faq +flattener fuzzying +gc github go-openapi +godoc golang golangci +hostname html http https hugo +i.e. id +initialism +initialisms +ipsum +ipsums +ipv4 +ipv6 +isbn json jsonschema +k8s +kubernetes linter linters +loren markdown +marshaling +mixin oai openapi repo repos schema +schemas +sexualized +ssn +submodule +subpackage swagger toolchain ui +ulid +unmarshaling +untyped +uri +url utf-8 +uuid +validator +workspace +workspaces yaml diff --git a/.github/workflows/doc-update.yml b/.github/workflows/doc-update.yml index 83c434a..25f9749 100644 --- a/.github/workflows/doc-update.yml +++ b/.github/workflows/doc-update.yml @@ -24,6 +24,7 @@ name: doc update check # * [ ] in this case, instead of commenting pull requests, it should raise issues. # * [ ] should be able to retrieve config files and dictionary from the called ref, not master. # * [ ] should be able to merge config files and dictionary with local definitions on target repo. +# * [ ] should be able to work on diff on: workflow_call: @@ -451,7 +452,9 @@ jobs: echo "### Changed markdown docs show some mispelled words. ⚠ī¸" >> $GITHUB_STEP_SUMMARY echo "" >> $GITHUB_STEP_SUMMARY - echo "> ℹī¸ INFO: we use [rojopolis/spellcheck-github-actions](https://github.com/rojopolis/spellcheck-github-actions)" >> $GITHUB_STEP_SUMMARY + echo "> ℹī¸ INFO: we use [rojopolis/spellcheck-github-actions](https://github.com/rojopolis/spellcheck-github-actions)." >> $GITHUB_STEP_SUMMARY + echo ">" >> $GITHUB_STEP_SUMMARY + echo "> As a general rule, technical terms or acronyms and references to code objects should be backquoted in markdown" >> $GITHUB_STEP_SUMMARY - name: Upload comment as artifact # description: | diff --git a/ALL.md b/ALL.md deleted file mode 100644 index 67aeeb4..0000000 --- a/ALL.md +++ /dev/null @@ -1,7262 +0,0 @@ -This is a test of the spellcheck dictionary - -Bump md - -# Swagger 2.0 specification schema - -This folder contains the Swagger 2.0 specification schema files maintained here: - -https://github.com/reverb/swagger-spec/blob/master/schemas/v2.0# OpenAPI v2 object model [![Build Status](https://github.com/go-openapi/spec/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/spec/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/spec/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/spec) - -[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) -[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/spec/master/LICENSE) -[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/spec.svg)](https://pkg.go.dev/github.com/go-openapi/spec) -[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/spec)](https://goreportcard.com/report/github.com/go-openapi/spec) - -The object model for OpenAPI specification documents. - -### FAQ - -* What does this do? - -> 1. This package knows how to marshal and unmarshal Swagger API specifications into a golang object model -> 2. It knows how to resolve $ref and expand them to make a single root document - -* How does it play with the rest of the go-openapi packages ? - -> 1. This package is at the core of the go-openapi suite of packages and [code generator](https://github.com/go-swagger/go-swagger) -> 2. There is a [spec loading package](https://github.com/go-openapi/loads) to fetch specs as JSON or YAML from local or remote locations -> 3. There is a [spec validation package](https://github.com/go-openapi/validate) built on top of it -> 4. There is a [spec analysis package](https://github.com/go-openapi/analysis) built on top of it, to analyze, flatten, fix and merge spec documents - -* Does this library support OpenAPI 3? - -> No. -> This package currently only supports OpenAPI 2.0 (aka Swagger 2.0). -> There is no plan to make it evolve toward supporting OpenAPI 3.x. -> This [discussion thread](https://github.com/go-openapi/spec/issues/21) relates the full story. -> -> An early attempt to support Swagger 3 may be found at: https://github.com/go-openapi/spec3 - -* Does the unmarshaling support YAML? - -> Not directly. The exposed types know only how to unmarshal from JSON. -> -> In order to load a YAML document as a Swagger spec, you need to use the loaders provided by -> github.com/go-openapi/loads -> -> Take a look at the example there: https://pkg.go.dev/github.com/go-openapi/loads#example-Spec -> -> See also https://github.com/go-openapi/spec/issues/164 - -* How can I validate a spec? - -> Validation is provided by [the validate package](http://github.com/go-openapi/validate) - -* Why do we have an `ID` field for `Schema` which is not part of the swagger spec? - -> We found jsonschema compatibility more important: since `id` in jsonschema influences -> how `$ref` are resolved. -> This `id` does not conflict with any property named `id`. -> -> See also https://github.com/go-openapi/spec/issues/23 -# Contributor Covenant Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. - -## Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at ivan+abuse@flanders.co.nz. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] - -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ -## Contribution Guidelines - -### Pull requests are always welcome - -We are always thrilled to receive pull requests, and do our best to -process them as fast as possible. Not sure if that typo is worth a pull -request? Do it! We will appreciate it. - -If your pull request is not accepted on the first try, don't be -discouraged! If there's a problem with the implementation, hopefully you -received feedback on what to improve. - -We're trying very hard to keep go-swagger lean and focused. We don't want it -to do everything for everybody. This means that we might decide against -incorporating a new feature. However, there might be a way to implement -that feature *on top of* go-swagger. - - -### Conventions - -Fork the repo and make changes on your fork in a feature branch: - -- If it's a bugfix branch, name it XXX-something where XXX is the number of the - issue -- If it's a feature branch, create an enhancement issue to announce your - intentions, and name it XXX-something where XXX is the number of the issue. - -Submit unit tests for your changes. Go has a great test framework built in; use -it! Take a look at existing tests for inspiration. Run the full test suite on -your branch before submitting a pull request. - -Update the documentation when creating or modifying features. Test -your documentation changes for clarity, concision, and correctness, as -well as a clean documentation build. See ``docs/README.md`` for more -information on building the docs and how docs get released. - -Write clean code. Universally formatted code promotes ease of writing, reading, -and maintenance. Always run `gofmt -s -w file.go` on each changed file before -committing your changes. Most editors have plugins that do this automatically. - -Pull requests descriptions should be as clear as possible and include a -reference to all the issues that they address. - -Pull requests must not contain commits from other users or branches. - -Commit messages must start with a capitalized and short summary (max. 50 -chars) written in the imperative, followed by an optional, more detailed -explanatory text which is separated from the summary by an empty line. - -Code review comments may be added to your pull request. Discuss, then make the -suggested modifications and push additional commits to your feature branch. Be -sure to post a comment after pushing. The new commits will show up in the pull -request automatically, but the reviewers will not be notified unless you -comment. - -Before the pull request is merged, make sure that you squash your commits into -logical units of work using `git rebase -i` and `git push -f`. After every -commit the test suite should be passing. Include documentation changes in the -same commit so that a revert would remove all traces of the feature or fix. - -Commits that fix or close an issue should include a reference like `Closes #XXX` -or `Fixes #XXX`, which will automatically close the issue when merged. - -### Sign your work - -The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as an open-source patch. The rules are pretty simple: if you -can certify the below (from -[developercertificate.org](http://developercertificate.org/)): - -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` - -then you just add a line to every git commit message: - - Signed-off-by: Joe Smith - -using your real name (sorry, no pseudonyms or anonymous contributions.) - -You can add the sign off when creating the git commit via `git commit -s`. -# gojsonreference [![Build Status](https://github.com/go-openapi/jsonreference/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/jsonreference/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/jsonreference/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/jsonreference) - -[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) -[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/jsonreference/master/LICENSE) -[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/jsonreference.svg)](https://pkg.go.dev/github.com/go-openapi/jsonreference) -[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/jsonreference)](https://goreportcard.com/report/github.com/go-openapi/jsonreference) - -An implementation of JSON Reference - Go language - -## Status -Feature complete. Stable API - -## Dependencies -* https://github.com/go-openapi/jsonpointer - -## References - -* http://tools.ietf.org/html/draft-ietf-appsawg-json-pointer-07 -* http://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03 -# Contributor Covenant Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. - -## Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at ivan+abuse@flanders.co.nz. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] - -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ -## Contribution Guidelines - -### Pull requests are always welcome - -We are always thrilled to receive pull requests, and do our best to -process them as fast as possible. Not sure if that typo is worth a pull -request? Do it! We will appreciate it. - -If your pull request is not accepted on the first try, don't be -discouraged! If there's a problem with the implementation, hopefully you -received feedback on what to improve. - -We're trying very hard to keep go-swagger lean and focused. We don't want it -to do everything for everybody. This means that we might decide against -incorporating a new feature. However, there might be a way to implement -that feature *on top of* go-swagger. - - -### Conventions - -Fork the repo and make changes on your fork in a feature branch: - -- If it's a bugfix branch, name it XXX-something where XXX is the number of the - issue -- If it's a feature branch, create an enhancement issue to announce your - intentions, and name it XXX-something where XXX is the number of the issue. - -Submit unit tests for your changes. Go has a great test framework built in; use -it! Take a look at existing tests for inspiration. Run the full test suite on -your branch before submitting a pull request. - -Update the documentation when creating or modifying features. Test -your documentation changes for clarity, concision, and correctness, as -well as a clean documentation build. See ``docs/README.md`` for more -information on building the docs and how docs get released. - -Write clean code. Universally formatted code promotes ease of writing, reading, -and maintenance. Always run `gofmt -s -w file.go` on each changed file before -committing your changes. Most editors have plugins that do this automatically. - -Pull requests descriptions should be as clear as possible and include a -reference to all the issues that they address. - -Pull requests must not contain commits from other users or branches. - -Commit messages must start with a capitalized and short summary (max. 50 -chars) written in the imperative, followed by an optional, more detailed -explanatory text which is separated from the summary by an empty line. - -Code review comments may be added to your pull request. Discuss, then make the -suggested modifications and push additional commits to your feature branch. Be -sure to post a comment after pushing. The new commits will show up in the pull -request automatically, but the reviewers will not be notified unless you -comment. - -Before the pull request is merged, make sure that you squash your commits into -logical units of work using `git rebase -i` and `git push -f`. After every -commit the test suite should be passing. Include documentation changes in the -same commit so that a revert would remove all traces of the feature or fix. - -Commits that fix or close an issue should include a reference like `Closes #XXX` -or `Fixes #XXX`, which will automatically close the issue when merged. - -### Sign your work - -The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as an open-source patch. The rules are pretty simple: if you -can certify the below (from -[developercertificate.org](http://developercertificate.org/)): - -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` - -then you just add a line to every git commit message: - - Signed-off-by: Joe Smith - -using your real name (sorry, no pseudonyms or anonymous contributions.) - -You can add the sign off when creating the git commit via `git commit -s`. -# doc - -Documentation check and generation tools. -# ci-workflows[![Build Status](https://github.com/go-openapi/ci-workflows/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/ci-workflows/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/ci-workflows/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/ci-workflows) - -[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) -[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/ci-workflows/master/LICENSE) -[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/ci-workflows.svg)](https://pkg.go.dev/github.com/go-openapi/ci-workflows) -[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/ci-workflows)](https://goreportcard.com/report/github.com/go-openapi/ci-workflows) - -Common Continuous Integration (`CI`) workflows and setup for go-openapi repos. - -* shared github action workflows -* shared `dependabot` configuration (TODO) -* shared `golangci-lint` configuration (**BLOCKED**) - -> NOTE: at this moment, it is difficult to share the golangci-lint config, -> so that one is not shared yet. - -## Motivation - -It took a while, but we eventually managed to align all checks, tests and -dependabot rules declared in the family of go-openapi repos. - -Now we'd like to be able to maintain, enrich and improve these checks without -worrying too much about the burden to replicate it about a dozen times. - -## Contemplated enhancements - -In no particular order: - -* [x] ui: enrich github actions UI with a job summary -* [x] doc: add markdown linting for docs -* [x] doc: add spellcheck for docs (and code?) -* [ ] version common workflows, so we can limit the impact of a change -* [ ] build: verify that go.sum cache for tests works (should be enabled) -* [ ] share mono repo workflows (see github.com/go-openapi/swag/.github/workflows) -* [ ] lint: manage somehow to share golangci config (with local merge) -* [ ] dependencies: manage somehow to share / replicate dependabot config -* [ ] lint: golangci-lint: check valid PR comments etc -* [ ] lint: use non-blocking, scheduled, proactive full linting to check for - the impact of new linters, new go versions etc -* [ ] doc: (possibility) take over hugo & doc gen part from go-swagger -* [ ] (possibility) take over release part from go-swagger -* [ ] doc: produce hugo github page with all latest tagged versions - (incl. mono repo) -* [ ] add bot to filter PRs, issues -* [ ] check with github API that all repo settings (branch protection rules, etc) - are identical -* [ ] comment PRs and issues -# Contributor Covenant Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. - -## Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at ivan+abuse@flanders.co.nz. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] - -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ -## Contribution Guidelines - -### Pull requests are always welcome - -We are always thrilled to receive pull requests, and do our best to -process them as fast as possible. Not sure if that typo is worth a pull -request? Do it! We will appreciate it. - -If your pull request is not accepted on the first try, don't be -discouraged! If there's a problem with the implementation, hopefully you -received feedback on what to improve. - -We're trying very hard to keep go-swagger lean and focused. We don't want it -to do everything for everybody. This means that we might decide against -incorporating a new feature. However, there might be a way to implement -that feature *on top of* go-swagger. - - -### Conventions - -Fork the repo and make changes on your fork in a feature branch: - -- If it's a bugfix branch, name it XXX-something where XXX is the number of the - issue -- If it's a feature branch, create an enhancement issue to announce your - intentions, and name it XXX-something where XXX is the number of the issue. - -Submit unit tests for your changes. Go has a great test framework built in; use -it! Take a look at existing tests for inspiration. Run the full test suite on -your branch before submitting a pull request. - -Update the documentation when creating or modifying features. Test -your documentation changes for clarity, concision, and correctness, as -well as a clean documentation build. See ``docs/README.md`` for more -information on building the docs and how docs get released. - -Write clean code. Universally formatted code promotes ease of writing, reading, -and maintenance. Always run `gofmt -s -w file.go` on each changed file before -committing your changes. Most editors have plugins that do this automatically. - -Pull requests descriptions should be as clear as possible and include a -reference to all the issues that they address. - -Pull requests must not contain commits from other users or branches. - -Commit messages must start with a capitalized and short summary (max. 50 -chars) written in the imperative, followed by an optional, more detailed -explanatory text which is separated from the summary by an empty line. - -Code review comments may be added to your pull request. Discuss, then make the -suggested modifications and push additional commits to your feature branch. Be -sure to post a comment after pushing. The new commits will show up in the pull -request automatically, but the reviewers will not be notified unless you -comment. - -Before the pull request is merged, make sure that you squash your commits into -logical units of work using `git rebase -i` and `git push -f`. After every -commit the test suite should be passing. Include documentation changes in the -same commit so that a revert would remove all traces of the feature or fix. - -Commits that fix or close an issue should include a reference like `Closes #XXX` -or `Fixes #XXX`, which will automatically close the issue when merged. - -### Sign your work - -The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as an open-source patch. The rules are pretty simple: if you -can certify the below (from -[developercertificate.org](http://developercertificate.org/)): - -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` - -then you just add a line to every git commit message: - - Signed-off-by: Joe Smith - -using your real name (sorry, no pseudonyms or anonymous contributions.) - -You can add the sign off when creating the git commit via `git commit -s`. -# Audit - -Audit of github repos to check for inconsistencies. -# inflect [![Build Status](https://github.com/go-openapi/inflect/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/inflect/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/inflect/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/inflect) - -[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) -[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/inflect/master/LICENSE) -[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/inflect.svg)](https://pkg.go.dev/github.com/go-openapi/inflect) -[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/inflect)](https://goreportcard.com/report/github.com/go-openapi/inflect) - -A package to pluralize words. - -Originally forked from fork of https://bitbucket.org/pkg/inflect under a MIT License. - -A golang library applying grammar rules to English words. - -> This package provides a basic set of functions applying -> grammar rules to inflect English words, modify case style -> (Capitalize, camelCase, snake_case, etc.). -> -> Acronyms are properly handled. A common use case is word pluralization. - - -This library is not used at all by other go-openapi packages and is somewhat redundant with -go-openapi/swag/mangling (for camelcase etc). - -Currently we have one single dependency in one place in a go-swagger template (used as a funcmap). - -## Note to maintainers - -* Aug. 2025: CI workflows have now moved to a shared repository go-openapi/ci-workflows -## Contribution Guidelines - -### Pull requests are always welcome - -We are always thrilled to receive pull requests, and do our best to -process them as fast as possible. Not sure if that typo is worth a pull -request? Do it! We will appreciate it. - -If your pull request is not accepted on the first try, don't be -discouraged! If there's a problem with the implementation, hopefully you -received feedback on what to improve. - -We're trying very hard to keep go-swagger lean and focused. We don't want it -to do everything for everybody. This means that we might decide against -incorporating a new feature. However, there might be a way to implement -that feature *on top of* go-swagger. - - -### Conventions - -Fork the repo and make changes on your fork in a feature branch: - -- If it's a bugfix branch, name it XXX-something where XXX is the number of the - issue -- If it's a feature branch, create an enhancement issue to announce your - intentions, and name it XXX-something where XXX is the number of the issue. - -Submit unit tests for your changes. Go has a great test framework built in; use -it! Take a look at existing tests for inspiration. Run the full test suite on -your branch before submitting a pull request. - -Update the documentation when creating or modifying features. Test -your documentation changes for clarity, concision, and correctness, as -well as a clean documentation build. See ``docs/README.md`` for more -information on building the docs and how docs get released. - -Write clean code. Universally formatted code promotes ease of writing, reading, -and maintenance. Always run `gofmt -s -w file.go` on each changed file before -committing your changes. Most editors have plugins that do this automatically. - -Pull requests descriptions should be as clear as possible and include a -reference to all the issues that they address. - -Pull requests must not contain commits from other users or branches. - -Commit messages must start with a capitalized and short summary (max. 50 -chars) written in the imperative, followed by an optional, more detailed -explanatory text which is separated from the summary by an empty line. - -Code review comments may be added to your pull request. Discuss, then make the -suggested modifications and push additional commits to your feature branch. Be -sure to post a comment after pushing. The new commits will show up in the pull -request automatically, but the reviewers will not be notified unless you -comment. - -Before the pull request is merged, make sure that you squash your commits into -logical units of work using `git rebase -i` and `git push -f`. After every -commit the test suite should be passing. Include documentation changes in the -same commit so that a revert would remove all traces of the feature or fix. - -Commits that fix or close an issue should include a reference like `Closes #XXX` -or `Fixes #XXX`, which will automatically close the issue when merged. - -### Sign your work - -The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as an open-source patch. The rules are pretty simple: if you -can certify the below (from -[developercertificate.org](http://developercertificate.org/)): - -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` - -then you just add a line to every git commit message: - - Signed-off-by: Joe Smith - -using your real name (sorry, no pseudonyms or anonymous contributions.) - -You can add the sign off when creating the git commit via `git commit -s`. -# Validation helpers [![Build Status](https://github.com/go-openapi/validate/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/validate/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/validate/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/validate) - -[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) -[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/validate/master/LICENSE) -[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/validate.svg)](https://pkg.go.dev/github.com/go-openapi/validate) -[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/validate)](https://goreportcard.com/report/github.com/go-openapi/validate) - -This package provides helpers to validate Swagger 2.0. specification (aka OpenAPI 2.0). - -Reference can be found here: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md. - -## What's inside? - -* A validator for Swagger specifications -* A validator for JSON schemas draft4 -* Helper functions to validate individual values (used by code generated by [go-swagger](https://github.com/go-swagger/go-swagger)). - * Required, RequiredNumber, RequiredString - * ReadOnly - * UniqueItems, MaxItems, MinItems - * Enum, EnumCase - * Pattern, MinLength, MaxLength - * Minimum, Maximum, MultipleOf - * FormatOf - -[Documentation](https://pkg.go.dev/github.com/go-openapi/validate) - -## FAQ - -* Does this library support OpenAPI 3? - -> No. -> This package currently only supports OpenAPI 2.0 (aka Swagger 2.0). -> There is no plan to make it evolve toward supporting OpenAPI 3.x. -> This [discussion thread](https://github.com/go-openapi/spec/issues/21) relates the full story. -> -> An early attempt to support Swagger 3 may be found at: https://github.com/go-openapi/spec3 -# Contributor Covenant Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. - -## Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at ivan+abuse@flanders.co.nz. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] - -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ -## Contribution Guidelines - -### Pull requests are always welcome - -We are always thrilled to receive pull requests, and do our best to -process them as fast as possible. Not sure if that typo is worth a pull -request? Do it! We will appreciate it. - -If your pull request is not accepted on the first try, don't be -discouraged! If there's a problem with the implementation, hopefully you -received feedback on what to improve. - -We're trying very hard to keep go-swagger lean and focused. We don't want it -to do everything for everybody. This means that we might decide against -incorporating a new feature. However, there might be a way to implement -that feature *on top of* go-swagger. - - -### Conventions - -Fork the repo and make changes on your fork in a feature branch: - -- If it's a bugfix branch, name it XXX-something where XXX is the number of the - issue -- If it's a feature branch, create an enhancement issue to announce your - intentions, and name it XXX-something where XXX is the number of the issue. - -Submit unit tests for your changes. Go has a great test framework built in; use -it! Take a look at existing tests for inspiration. Run the full test suite on -your branch before submitting a pull request. - -Update the documentation when creating or modifying features. Test -your documentation changes for clarity, concision, and correctness, as -well as a clean documentation build. See ``docs/README.md`` for more -information on building the docs and how docs get released. - -Write clean code. Universally formatted code promotes ease of writing, reading, -and maintenance. Always run `gofmt -s -w file.go` on each changed file before -committing your changes. Most editors have plugins that do this automatically. - -Pull requests descriptions should be as clear as possible and include a -reference to all the issues that they address. - -Pull requests must not contain commits from other users or branches. - -Commit messages must start with a capitalized and short summary (max. 50 -chars) written in the imperative, followed by an optional, more detailed -explanatory text which is separated from the summary by an empty line. - -Code review comments may be added to your pull request. Discuss, then make the -suggested modifications and push additional commits to your feature branch. Be -sure to post a comment after pushing. The new commits will show up in the pull -request automatically, but the reviewers will not be notified unless you -comment. - -Before the pull request is merged, make sure that you squash your commits into -logical units of work using `git rebase -i` and `git push -f`. After every -commit the test suite should be passing. Include documentation changes in the -same commit so that a revert would remove all traces of the feature or fix. - -Commits that fix or close an issue should include a reference like `Closes #XXX` -or `Fixes #XXX`, which will automatically close the issue when merged. - -### Sign your work - -The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as an open-source patch. The rules are pretty simple: if you -can certify the below (from -[developercertificate.org](http://developercertificate.org/)): - -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` - -then you just add a line to every git commit message: - - Signed-off-by: Joe Smith - -using your real name (sorry, no pseudonyms or anonymous contributions.) - -You can add the sign off when creating the git commit via `git commit -s`. -# Benchmark - -Validating the Kubernetes Swagger API - -## v0.22.6: 60,000,000 allocs -``` -goos: linux -goarch: amd64 -pkg: github.com/go-openapi/validate -cpu: AMD Ryzen 7 5800X 8-Core Processor -Benchmark_KubernetesSpec/validating_kubernetes_API-16 1 8549863982 ns/op 7067424936 B/op 59583275 allocs/op -``` - -## After refact PR: minor but noticable improvements: 25,000,000 allocs -``` -go test -bench Spec -goos: linux -goarch: amd64 -pkg: github.com/go-openapi/validate -cpu: AMD Ryzen 7 5800X 8-Core Processor -Benchmark_KubernetesSpec/validating_kubernetes_API-16 1 4064535557 ns/op 3379715592 B/op 25320330 allocs/op -``` - -## After reduce GC pressure PR: 17,000,000 allocs -``` -goos: linux -goarch: amd64 -pkg: github.com/go-openapi/validate -cpu: AMD Ryzen 7 5800X 8-Core Processor -Benchmark_KubernetesSpec/validating_kubernetes_API-16 1 3758414145 ns/op 2593881496 B/op 17111373 allocs/op -``` -# Denco [![Build Status](https://travis-ci.org/naoina/denco.png?branch=master)](https://travis-ci.org/naoina/denco) - -The fast and flexible HTTP request router for [Go](http://golang.org). - -Denco is based on Double-Array implementation of [Kocha-urlrouter](https://github.com/naoina/kocha-urlrouter). -However, Denco is optimized and some features added. - -## Features - -* Fast (See [go-http-routing-benchmark](https://github.com/naoina/go-http-routing-benchmark)) -* [URL patterns](#url-patterns) (`/foo/:bar` and `/foo/*wildcard`) -* Small (but enough) URL router API -* HTTP request multiplexer like `http.ServeMux` - -## Installation - - go get -u github.com/go-openapi/runtime/middleware/denco - -## Using as HTTP request multiplexer - -```go -package main - -import ( - "fmt" - "log" - "net/http" - - "github.com/go-openapi/runtime/middleware/denco" -) - -func Index(w http.ResponseWriter, r *http.Request, params denco.Params) { - fmt.Fprintf(w, "Welcome to Denco!\n") -} - -func User(w http.ResponseWriter, r *http.Request, params denco.Params) { - fmt.Fprintf(w, "Hello %s!\n", params.Get("name")) -} - -func main() { - mux := denco.NewMux() - handler, err := mux.Build([]denco.Handler{ - mux.GET("/", Index), - mux.GET("/user/:name", User), - mux.POST("/user/:name", User), - }) - if err != nil { - panic(err) - } - log.Fatal(http.ListenAndServe(":8080", handler)) -} -``` - -## Using as URL router - -```go -package main - -import ( - "fmt" - - "github.com/go-openapi/runtime/middleware/denco" -) - -type route struct { - name string -} - -func main() { - router := denco.New() - router.Build([]denco.Record{ - {"/", &route{"root"}}, - {"/user/:id", &route{"user"}}, - {"/user/:name/:id", &route{"username"}}, - {"/static/*filepath", &route{"static"}}, - }) - - data, params, found := router.Lookup("/") - // print `&main.route{name:"root"}, denco.Params(nil), true`. - fmt.Printf("%#v, %#v, %#v\n", data, params, found) - - data, params, found = router.Lookup("/user/hoge") - // print `&main.route{name:"user"}, denco.Params{denco.Param{Name:"id", Value:"hoge"}}, true`. - fmt.Printf("%#v, %#v, %#v\n", data, params, found) - - data, params, found = router.Lookup("/user/hoge/7") - // print `&main.route{name:"username"}, denco.Params{denco.Param{Name:"name", Value:"hoge"}, denco.Param{Name:"id", Value:"7"}}, true`. - fmt.Printf("%#v, %#v, %#v\n", data, params, found) - - data, params, found = router.Lookup("/static/path/to/file") - // print `&main.route{name:"static"}, denco.Params{denco.Param{Name:"filepath", Value:"path/to/file"}}, true`. - fmt.Printf("%#v, %#v, %#v\n", data, params, found) -} -``` - -See [Godoc](http://godoc.org/github.com/go-openapi/runtime/middleware/denco) for more details. - -## Getting the value of path parameter - -You can get the value of path parameter by 2 ways. - -1. Using [`denco.Params.Get`](http://godoc.org/github.com/go-openapi/runtime/middleware/denco#Params.Get) method -2. Find by loop - -```go -package main - -import ( - "fmt" - - "github.com/go-openapi/runtime/middleware/denco" -) - -func main() { - router := denco.New() - if err := router.Build([]denco.Record{ - {"/user/:name/:id", "route1"}, - }); err != nil { - panic(err) - } - - // 1. Using denco.Params.Get method. - _, params, _ := router.Lookup("/user/alice/1") - name := params.Get("name") - if name != "" { - fmt.Printf("Hello %s.\n", name) // prints "Hello alice.". - } - - // 2. Find by loop. - for _, param := range params { - if param.Name == "name" { - fmt.Printf("Hello %s.\n", name) // prints "Hello alice.". - } - } -} -``` - -## URL patterns - -Denco's route matching strategy is "most nearly matching". - -When routes `/:name` and `/alice` have been built, URI `/alice` matches the route `/alice`, not `/:name`. -Because URI `/alice` is more match with the route `/alice` than `/:name`. - -For more example, when routes below have been built: - -``` -/user/alice -/user/:name -/user/:name/:id -/user/alice/:id -/user/:id/bob -``` - -Routes matching are: - -``` -/user/alice => "/user/alice" (no match with "/user/:name") -/user/bob => "/user/:name" -/user/naoina/1 => "/user/:name/1" -/user/alice/1 => "/user/alice/:id" (no match with "/user/:name/:id") -/user/1/bob => "/user/:id/bob" (no match with "/user/:name/:id") -/user/alice/bob => "/user/alice/:id" (no match with "/user/:name/:id" and "/user/:id/bob") -``` - -## Limitation - -Denco has some limitations below. - -* Number of param records (such as `/:name`) must be less than 2^22 -* Number of elements of internal slice must be less than 2^22 - -## Benchmarks - - cd $GOPATH/github.com/go-openapi/runtime/middleware/denco - go test -bench . -benchmem - -## License - -Denco is licensed under the MIT License. -# runtime [![Build Status](https://github.com/go-openapi/runtime/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/runtime/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/runtime/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/runtime) - -[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) -[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/runtime/master/LICENSE) -[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/runtime.svg)](https://pkg.go.dev/github.com/go-openapi/runtime) -[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/runtime)](https://goreportcard.com/report/github.com/go-openapi/runtime) - -# go OpenAPI toolkit runtime - -The runtime component for use in code generation or as untyped usage. -# Contributor Covenant Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. - -## Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at ivan+abuse@flanders.co.nz. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] - -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ -## Contribution Guidelines - -### Pull requests are always welcome - -We are always thrilled to receive pull requests, and do our best to -process them as fast as possible. Not sure if that typo is worth a pull -request? Do it! We will appreciate it. - -If your pull request is not accepted on the first try, don't be -discouraged! If there's a problem with the implementation, hopefully you -received feedback on what to improve. - -We're trying very hard to keep go-swagger lean and focused. We don't want it -to do everything for everybody. This means that we might decide against -incorporating a new feature. However, there might be a way to implement -that feature *on top of* go-swagger. - - -### Conventions - -Fork the repo and make changes on your fork in a feature branch: - -- If it's a bugfix branch, name it XXX-something where XXX is the number of the - issue -- If it's a feature branch, create an enhancement issue to announce your - intentions, and name it XXX-something where XXX is the number of the issue. - -Submit unit tests for your changes. Go has a great test framework built in; use -it! Take a look at existing tests for inspiration. Run the full test suite on -your branch before submitting a pull request. - -Update the documentation when creating or modifying features. Test -your documentation changes for clarity, concision, and correctness, as -well as a clean documentation build. See ``docs/README.md`` for more -information on building the docs and how docs get released. - -Write clean code. Universally formatted code promotes ease of writing, reading, -and maintenance. Always run `gofmt -s -w file.go` on each changed file before -committing your changes. Most editors have plugins that do this automatically. - -Pull requests descriptions should be as clear as possible and include a -reference to all the issues that they address. - -Pull requests must not contain commits from other users or branches. - -Commit messages must start with a capitalized and short summary (max. 50 -chars) written in the imperative, followed by an optional, more detailed -explanatory text which is separated from the summary by an empty line. - -Code review comments may be added to your pull request. Discuss, then make the -suggested modifications and push additional commits to your feature branch. Be -sure to post a comment after pushing. The new commits will show up in the pull -request automatically, but the reviewers will not be notified unless you -comment. - -Before the pull request is merged, make sure that you squash your commits into -logical units of work using `git rebase -i` and `git push -f`. After every -commit the test suite should be passing. Include documentation changes in the -same commit so that a revert would remove all traces of the feature or fix. - -Commits that fix or close an issue should include a reference like `Closes #XXX` -or `Fixes #XXX`, which will automatically close the issue when merged. - -### Sign your work - -The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as an open-source patch. The rules are pretty simple: if you -can certify the below (from -[developercertificate.org](http://developercertificate.org/)): - -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` - -then you just add a line to every git commit message: - - Signed-off-by: Joe Smith - -using your real name (sorry, no pseudonyms or anonymous contributions.) - -You can add the sign off when creating the git commit via `git commit -s`. -# Loads OAI specs [![Build Status](https://github.com/go-openapi/loads/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/loads/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/loads/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/loads) - -[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/loads/master/LICENSE) [![GoDoc](https://godoc.org/github.com/go-openapi/loads?status.svg)](http://godoc.org/github.com/go-openapi/loads) -[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/loads)](https://goreportcard.com/report/github.com/go-openapi/loads) - -Loading of OAI specification documents from local or remote locations. Supports JSON and YAML documents. -# Contributor Covenant Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. - -## Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at ivan+abuse@flanders.co.nz. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] - -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ -## Contribution Guidelines - -### Pull requests are always welcome - -We are always thrilled to receive pull requests, and do our best to -process them as fast as possible. Not sure if that typo is worth a pull -request? Do it! We will appreciate it. - -If your pull request is not accepted on the first try, don't be -discouraged! If there's a problem with the implementation, hopefully you -received feedback on what to improve. - -We're trying very hard to keep go-swagger lean and focused. We don't want it -to do everything for everybody. This means that we might decide against -incorporating a new feature. However, there might be a way to implement -that feature *on top of* go-swagger. - - -### Conventions - -Fork the repo and make changes on your fork in a feature branch: - -- If it's a bugfix branch, name it XXX-something where XXX is the number of the - issue -- If it's a feature branch, create an enhancement issue to announce your - intentions, and name it XXX-something where XXX is the number of the issue. - -Submit unit tests for your changes. Go has a great test framework built in; use -it! Take a look at existing tests for inspiration. Run the full test suite on -your branch before submitting a pull request. - -Update the documentation when creating or modifying features. Test -your documentation changes for clarity, concision, and correctness, as -well as a clean documentation build. See ``docs/README.md`` for more -information on building the docs and how docs get released. - -Write clean code. Universally formatted code promotes ease of writing, reading, -and maintenance. Always run `gofmt -s -w file.go` on each changed file before -committing your changes. Most editors have plugins that do this automatically. - -Pull requests descriptions should be as clear as possible and include a -reference to all the issues that they address. - -Pull requests must not contain commits from other users or branches. - -Commit messages must start with a capitalized and short summary (max. 50 -chars) written in the imperative, followed by an optional, more detailed -explanatory text which is separated from the summary by an empty line. - -Code review comments may be added to your pull request. Discuss, then make the -suggested modifications and push additional commits to your feature branch. Be -sure to post a comment after pushing. The new commits will show up in the pull -request automatically, but the reviewers will not be notified unless you -comment. - -Before the pull request is merged, make sure that you squash your commits into -logical units of work using `git rebase -i` and `git push -f`. After every -commit the test suite should be passing. Include documentation changes in the -same commit so that a revert would remove all traces of the feature or fix. - -Commits that fix or close an issue should include a reference like `Closes #XXX` -or `Fixes #XXX`, which will automatically close the issue when merged. - -### Sign your work - -The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as an open-source patch. The rules are pretty simple: if you -can certify the below (from -[developercertificate.org](http://developercertificate.org/)): - -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` - -then you just add a line to every git commit message: - - Signed-off-by: Joe Smith - -using your real name (sorry, no pseudonyms or anonymous contributions.) - -You can add the sign off when creating the git commit via `git commit -s`. -# OpenAPI analysis [![Build Status](https://github.com/go-openapi/analysis/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/analysis/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/analysis/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/analysis) - -[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) -[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/analysis/master/LICENSE) -[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/analysis.svg)](https://pkg.go.dev/github.com/go-openapi/analysis) -[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/analysis)](https://goreportcard.com/report/github.com/go-openapi/analysis) - - -A foundational library to analyze an OAI specification document for easier reasoning about the content. - -## What's inside? - -* An analyzer providing methods to walk the functional content of a specification -* A spec flattener producing a self-contained document bundle, while preserving `$ref`s -* A spec merger ("mixin") to merge several spec documents into a primary spec -* A spec "fixer" ensuring that response descriptions are non empty - -[Documentation](https://pkg.go.dev/github.com/go-openapi/analysis) - -## FAQ - -* Does this library support OpenAPI 3? - -> No. -> This package currently only supports OpenAPI 2.0 (aka Swagger 2.0). -> There is no plan to make it evolve toward supporting OpenAPI 3.x. -> This [discussion thread](https://github.com/go-openapi/spec/issues/21) relates the full story. -# Contributor Covenant Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. - -## Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at ivan+abuse@flanders.co.nz. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] - -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ -## Contribution Guidelines - -### Pull requests are always welcome - -We are always thrilled to receive pull requests, and do our best to -process them as fast as possible. Not sure if that typo is worth a pull -request? Do it! We will appreciate it. - -If your pull request is not accepted on the first try, don't be -discouraged! If there's a problem with the implementation, hopefully you -received feedback on what to improve. - -We're trying very hard to keep go-swagger lean and focused. We don't want it -to do everything for everybody. This means that we might decide against -incorporating a new feature. However, there might be a way to implement -that feature *on top of* go-swagger. - - -### Conventions - -Fork the repo and make changes on your fork in a feature branch: - -- If it's a bugfix branch, name it XXX-something where XXX is the number of the - issue -- If it's a feature branch, create an enhancement issue to announce your - intentions, and name it XXX-something where XXX is the number of the issue. - -Submit unit tests for your changes. Go has a great test framework built in; use -it! Take a look at existing tests for inspiration. Run the full test suite on -your branch before submitting a pull request. - -Update the documentation when creating or modifying features. Test -your documentation changes for clarity, concision, and correctness, as -well as a clean documentation build. See ``docs/README.md`` for more -information on building the docs and how docs get released. - -Write clean code. Universally formatted code promotes ease of writing, reading, -and maintenance. Always run `gofmt -s -w file.go` on each changed file before -committing your changes. Most editors have plugins that do this automatically. - -Pull requests descriptions should be as clear as possible and include a -reference to all the issues that they address. - -Pull requests must not contain commits from other users or branches. - -Commit messages must start with a capitalized and short summary (max. 50 -chars) written in the imperative, followed by an optional, more detailed -explanatory text which is separated from the summary by an empty line. - -Code review comments may be added to your pull request. Discuss, then make the -suggested modifications and push additional commits to your feature branch. Be -sure to post a comment after pushing. The new commits will show up in the pull -request automatically, but the reviewers will not be notified unless you -comment. - -Before the pull request is merged, make sure that you squash your commits into -logical units of work using `git rebase -i` and `git push -f`. After every -commit the test suite should be passing. Include documentation changes in the -same commit so that a revert would remove all traces of the feature or fix. - -Commits that fix or close an issue should include a reference like `Closes #XXX` -or `Fixes #XXX`, which will automatically close the issue when merged. - -### Sign your work - -The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as an open-source patch. The rules are pretty simple: if you -can certify the below (from -[developercertificate.org](http://developercertificate.org/)): - -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` - -then you just add a line to every git commit message: - - Signed-off-by: Joe Smith - -using your real name (sorry, no pseudonyms or anonymous contributions.) - -You can add the sign off when creating the git commit via `git commit -s`. -# Benchmarking name mangling utilities - -```bash -go test -bench XXX -run XXX -benchtime 30s -``` - -## Benchmarks at b3e7a5386f996177e4808f11acb2aa93a0f660df - -``` -goos: linux -goarch: amd64 -pkg: github.com/go-openapi/swag -cpu: Intel(R) Core(TM) i5-6200U CPU @ 2.30GHz -BenchmarkToXXXName/ToGoName-4 862623 44101 ns/op 10450 B/op 732 allocs/op -BenchmarkToXXXName/ToVarName-4 853656 40728 ns/op 10468 B/op 734 allocs/op -BenchmarkToXXXName/ToFileName-4 1268312 27813 ns/op 9785 B/op 617 allocs/op -BenchmarkToXXXName/ToCommandName-4 1276322 27903 ns/op 9785 B/op 617 allocs/op -BenchmarkToXXXName/ToHumanNameLower-4 895334 40354 ns/op 10472 B/op 731 allocs/op -BenchmarkToXXXName/ToHumanNameTitle-4 882441 40678 ns/op 10566 B/op 749 allocs/op -``` - -## Benchmarks after PR #79 - -~ x10 performance improvement and ~ /100 memory allocations. - -``` -goos: linux -goarch: amd64 -pkg: github.com/go-openapi/swag -cpu: Intel(R) Core(TM) i5-6200U CPU @ 2.30GHz -BenchmarkToXXXName/ToGoName-4 9595830 3991 ns/op 42 B/op 5 allocs/op -BenchmarkToXXXName/ToVarName-4 9194276 3984 ns/op 62 B/op 7 allocs/op -BenchmarkToXXXName/ToFileName-4 17002711 2123 ns/op 147 B/op 7 allocs/op -BenchmarkToXXXName/ToCommandName-4 16772926 2111 ns/op 147 B/op 7 allocs/op -BenchmarkToXXXName/ToHumanNameLower-4 9788331 3749 ns/op 92 B/op 6 allocs/op -BenchmarkToXXXName/ToHumanNameTitle-4 9188260 3941 ns/op 104 B/op 6 allocs/op -``` - -``` -goos: linux -goarch: amd64 -pkg: github.com/go-openapi/swag -cpu: AMD Ryzen 7 5800X 8-Core Processor -BenchmarkToXXXName/ToGoName-16 18527378 1972 ns/op 42 B/op 5 allocs/op -BenchmarkToXXXName/ToVarName-16 15552692 2093 ns/op 62 B/op 7 allocs/op -BenchmarkToXXXName/ToFileName-16 32161176 1117 ns/op 147 B/op 7 allocs/op -BenchmarkToXXXName/ToCommandName-16 32256634 1137 ns/op 147 B/op 7 allocs/op -BenchmarkToXXXName/ToHumanNameLower-16 18599661 1946 ns/op 92 B/op 6 allocs/op -BenchmarkToXXXName/ToHumanNameTitle-16 17581353 2054 ns/op 105 B/op 6 allocs/op -``` - -## Benchmarks at d7d2d1b895f5b6747afaff312dd2a402e69e818b - -go1.24 - -``` -goos: linux -goarch: amd64 -pkg: github.com/go-openapi/swag -cpu: AMD Ryzen 7 5800X 8-Core Processor -BenchmarkToXXXName/ToGoName-16 19757858 1881 ns/op 42 B/op 5 allocs/op -BenchmarkToXXXName/ToVarName-16 17494111 2094 ns/op 74 B/op 7 allocs/op -BenchmarkToXXXName/ToFileName-16 28161226 1492 ns/op 158 B/op 7 allocs/op -BenchmarkToXXXName/ToCommandName-16 23787333 1489 ns/op 158 B/op 7 allocs/op -BenchmarkToXXXName/ToHumanNameLower-16 17537257 2030 ns/op 103 B/op 6 allocs/op -BenchmarkToXXXName/ToHumanNameTitle-16 16977453 2156 ns/op 105 B/op 6 allocs/op -``` - -## Benchmarks after PR #106 - -Moving the scope of everything down to a struct allowed to reduce a bit garbage and pooling. - -On top of that, ToGoName (and thus ToVarName) have been subject to a minor optimization, removing a few allocations. - -Overall timings improve by ~ -10%. - -go1.24 - -``` -goos: linux -goarch: amd64 -pkg: github.com/go-openapi/swag/mangling -cpu: AMD Ryzen 7 5800X 8-Core Processor -BenchmarkToXXXName/ToGoName-16 22496130 1618 ns/op 31 B/op 3 allocs/op -BenchmarkToXXXName/ToVarName-16 22538068 1618 ns/op 33 B/op 3 allocs/op -BenchmarkToXXXName/ToFileName-16 27722977 1236 ns/op 105 B/op 6 allocs/op -BenchmarkToXXXName/ToCommandName-16 27967395 1258 ns/op 105 B/op 6 allocs/op -BenchmarkToXXXName/ToHumanNameLower-16 18587901 1917 ns/op 103 B/op 6 allocs/op -BenchmarkToXXXName/ToHumanNameTitle-16 17193208 2019 ns/op 108 B/op 7 allocs/op -``` -# Swag [![Build Status](https://github.com/go-openapi/swag/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/swag/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/swag/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/swag) - -[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) -[![license](https://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/swag/master/LICENSE) -[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/swag.svg)](https://pkg.go.dev/github.com/go-openapi/swag) -[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/swag)](https://goreportcard.com/report/github.com/go-openapi/swag) - -Package `swag` contains a bunch of helper functions for go-openapi and go-swagger projects. - -You may also use it standalone for your projects. - -> `swag` is one of the foundational building blocks of the go-openapi initiative. -> -> Most repositories in `github.com/go-openapi/...` depend on it in some way. -> So does the CLI tool `github.com/go-swagger/go-swagger`, -> and the code generated by this tool. - -## Contents - -`go-openapi/swag` now exposes a collection of relatively independent modules. - -Here is what is inside: - -* Module `cmdutils` - - * [x] utilities to work with CLIs - -* Module `conv` - - * [x] convert between values and pointers for any types - * [x] convert from string to builtin types (wraps `strconv`) - * [x] require `./typeutils` (test dependency) - -* Module `fileutils` - - * [x] file upload type - * [x] search in path (deprecated) - -* Module `jsonname` - - * [x] infer JSON names from go properties - -* Module `jsonutils` - - * [x] fast json concatenation - * [x] read and write JSON from and to dynamic go data structures - * [x] require `github.com/mailru/easyjson` - -* Module `loading` - - * [x] load from file or http - * [x] require `./yamlutils` - -* Module `mangling` - - * [x] name mangling for go - -* Module `netutils` - - * [x] host, port from address - -* Module `stringutils` - - * [x] search in slice (with case-insensitive) - * [x] split/join query parameters as arrays - -* Module `typeutils` - - * [x] check the zero value for any type - -* Module `yamlutils` - - * [x] converting YAML to JSON - * [x] loading YAML into a dynamic YAML document - * [x] require `./jsonutils` - * [x] require `github.com/mailru/easyjson` - * [x] require `gopkg.in/yaml.v3` - ---- - -The root module `github.com/go-openapi/swag` at the repo level maintains a few -dependencies outside of the standard library: - -* YAML utilities depend on `gopkg.in/yaml.v3` -* JSON utilities `github.com/mailru/easyjson` - -This is not necessarily the case for all sub-modules. - -## Release notes - -### v0.24.0 [Unreleased] - -With this release, we have largely modernized the API of `swag`: - -* The traditional `swag` API is still supported: code that imports `swag` will still - compile and work the same. -* A deprecation notice is published to encourage consumers of this library to adopt - the newer API -* **Deprecation notice** - * configuration through global variables is now deprecated, in favor of options passed as parameters - * all helper functions are moved to more specialized packages, which are exposed as - go modules. Importing such a module would reduce the footprint of dependencies. - * _all_ functions, variables, constants exposed by the deprecated API have now moved, so - that consumers of the new API no longer need to import github.com/go-openapi/swag, but - should import the desired sub-module(s). - -**New with this release**: - -* [x] type converters and pointer to value helpers now support generic types -* [x] name mangling now support pluralized initialisms (issue #46) - Strings like "contact IDs" are now recognized as such a plural form and mangled as a linter would expect. -* [x] performance: small improvements to reduce the overhead of convert/format wrappers (see issues #110, or PR #108) -* [x] performance: name mangling utilities run ~ 10% faster (PR #115) - ---- - -Moving forward, no additional feature will be added to the `swag` API directly. - -However, child modules will continue to evolve or some new ones may be added in the future. - - -#### Note to contributors - -The mono-repo structure comes with some unavoidable extra pains... - -* Testing - -> The usual `go test ./...` command, run from the root of this repo won't work any longer to test all submodules. -> -> Each module constitutes an independant unit of test. So you have to run `go test` inside each module. -> Or you may take a look at how this is achieved by CI -> [here] https://github.com/go-openapi/swag/blob/master/.github/workflows/go-test.yml). -> -> There are also some alternative tricks using `go work`, for local development, if you feel comfortable with -> go workspaces. Perhaps some day, we'll have a `go work test` to run all tests without any hack. - -* Releasing - -> Each module follows its own independant module versioning. -> -> So you have tags like `mangling/v0.24.0`, `fileutils/v0.24.0` etc that are used by `go mod` and `go get` -> to refer to the tagged version of each module specifically. -> -> This means we may release patches etc to each module independently. -> -> We'd like to adopt the rule that modules in this repo would only differ by a patch version -> (e.g. `v0.24.5` vs `v0.24.3`), and we'll level all modules whenever a minor version is introduced. -> -> A script in `./hack` is provided to tag all modules in one go at the same level in one go. - -## Todos, suggestions and plans - -All kinds of contributions are welcome. - -A few ideas: - -* [ ] Complete the split of dependencies to isolate easyjson from the rest -* [ ] Improve mangling utilities (improve readability, support for capitalized words, - better word substitution for non-letter symbols...) -* [ ] Move back to this common shared pot a few of the technical features introduced by go-swagger independently - (e.g. mangle go package names, search package with go modules support, ...) -* [ ] Apply a similar mono-repo approach to go-openapi/strfmt which suffer from similar woes: bloated API, - imposed dependency to some database driver. - -# Contributor Covenant Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. - -## Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at ivan+abuse@flanders.co.nz. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] - -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ -## Contribution Guidelines - -### Pull requests are always welcome - -We are always thrilled to receive pull requests, and do our best to -process them as fast as possible. Not sure if that typo is worth a pull -request? Do it! We will appreciate it. - -If your pull request is not accepted on the first try, don't be -discouraged! If there's a problem with the implementation, hopefully you -received feedback on what to improve. - -We're trying very hard to keep go-swagger lean and focused. We don't want it -to do everything for everybody. This means that we might decide against -incorporating a new feature. However, there might be a way to implement -that feature *on top of* go-swagger. - - -### Conventions - -Fork the repo and make changes on your fork in a feature branch: - -- If it's a bugfix branch, name it XXX-something where XXX is the number of the - issue -- If it's a feature branch, create an enhancement issue to announce your - intentions, and name it XXX-something where XXX is the number of the issue. - -Submit unit tests for your changes. Go has a great test framework built in; use -it! Take a look at existing tests for inspiration. Run the full test suite on -your branch before submitting a pull request. - -Update the documentation when creating or modifying features. Test -your documentation changes for clarity, concision, and correctness, as -well as a clean documentation build. See ``docs/README.md`` for more -information on building the docs and how docs get released. - -Write clean code. Universally formatted code promotes ease of writing, reading, -and maintenance. Always run `gofmt -s -w file.go` on each changed file before -committing your changes. Most editors have plugins that do this automatically. - -Pull requests descriptions should be as clear as possible and include a -reference to all the issues that they address. - -Pull requests must not contain commits from other users or branches. - -Commit messages must start with a capitalized and short summary (max. 50 -chars) written in the imperative, followed by an optional, more detailed -explanatory text which is separated from the summary by an empty line. - -Code review comments may be added to your pull request. Discuss, then make the -suggested modifications and push additional commits to your feature branch. Be -sure to post a comment after pushing. The new commits will show up in the pull -request automatically, but the reviewers will not be notified unless you -comment. - -Before the pull request is merged, make sure that you squash your commits into -logical units of work using `git rebase -i` and `git push -f`. After every -commit the test suite should be passing. Include documentation changes in the -same commit so that a revert would remove all traces of the feature or fix. - -Commits that fix or close an issue should include a reference like `Closes #XXX` -or `Fixes #XXX`, which will automatically close the issue when merged. - -### Sign your work - -The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as an open-source patch. The rules are pretty simple: if you -can certify the below (from -[developercertificate.org](http://developercertificate.org/)): - -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` - -then you just add a line to every git commit message: - - Signed-off-by: Joe Smith - -using your real name (sorry, no pseudonyms or anonymous contributions.) - -You can add the sign off when creating the git commit via `git commit -s`. -# Strfmt [![Build Status](https://github.com/go-openapi/strfmt/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/strfmt/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/strfmt/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/strfmt) -[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) -[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/strfmt/master/LICENSE) -[![GoDoc](https://godoc.org/github.com/go-openapi/strfmt?status.svg)](http://godoc.org/github.com/go-openapi/strfmt) -[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/strfmt)](https://goreportcard.com/report/github.com/go-openapi/strfmt) - -This package exposes a registry of data types to support string formats in the go-openapi toolkit. - -strfmt represents a well known string format such as credit card or email. The go toolkit for OpenAPI specifications knows how to deal with those. - -## Supported data formats -go-openapi/strfmt follows the swagger 2.0 specification with the following formats -defined [here](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types). - -It also provides convenient extensions to go-openapi users. - -- [x] JSON-schema draft 4 formats - - date-time - - email - - hostname - - ipv4 - - ipv6 - - uri -- [x] swagger 2.0 format extensions - - binary - - byte (e.g. base64 encoded string) - - date (e.g. "1970-01-01") - - password -- [x] go-openapi custom format extensions - - bsonobjectid (BSON objectID) - - creditcard - - duration (e.g. "3 weeks", "1ms") - - hexcolor (e.g. "#FFFFFF") - - isbn, isbn10, isbn13 - - mac (e.g "01:02:03:04:05:06") - - rgbcolor (e.g. "rgb(100,100,100)") - - ssn - - uuid, uuid3, uuid4, uuid5 - - cidr (e.g. "192.0.2.1/24", "2001:db8:a0b:12f0::1/32") - - ulid (e.g. "00000PP9HGSBSSDZ1JTEXBJ0PW", [spec](https://github.com/ulid/spec)) - -> NOTE: as the name stands for, this package is intended to support string formatting only. -> It does not provide validation for numerical values with swagger format extension for JSON types "number" or -> "integer" (e.g. float, double, int32...). - -## Type conversion - -All types defined here are stringers and may be converted to strings with `.String()`. -Note that most types defined by this package may be converted directly to string like `string(Email{})`. - -`Date` and `DateTime` may be converted directly to `time.Time` like `time.Time(Time{})`. -Similarly, you can convert `Duration` to `time.Duration` as in `time.Duration(Duration{})` - -## Using pointers - -The `conv` subpackage provides helpers to convert the types to and from pointers, just like `go-openapi/swag` does -with primitive types. - -## Format types -Types defined in strfmt expose marshaling and validation capabilities. - -List of defined types: -- Base64 -- CreditCard -- Date -- DateTime -- Duration -- Email -- HexColor -- Hostname -- IPv4 -- IPv6 -- CIDR -- ISBN -- ISBN10 -- ISBN13 -- MAC -- ObjectId -- Password -- RGBColor -- SSN -- URI -- UUID -- UUID3 -- UUID4 -- UUID5 -- [ULID](https://github.com/ulid/spec) -# Contributor Covenant Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. - -## Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at ivan+abuse@flanders.co.nz. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] - -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ -## Contribution Guidelines - -### Pull requests are always welcome - -We are always thrilled to receive pull requests, and do our best to -process them as fast as possible. Not sure if that typo is worth a pull -request? Do it! We will appreciate it. - -If your pull request is not accepted on the first try, don't be -discouraged! If there's a problem with the implementation, hopefully you -received feedback on what to improve. - -We're trying very hard to keep go-swagger lean and focused. We don't want it -to do everything for everybody. This means that we might decide against -incorporating a new feature. However, there might be a way to implement -that feature *on top of* go-swagger. - - -### Conventions - -Fork the repo and make changes on your fork in a feature branch: - -- If it's a bugfix branch, name it XXX-something where XXX is the number of the - issue -- If it's a feature branch, create an enhancement issue to announce your - intentions, and name it XXX-something where XXX is the number of the issue. - -Submit unit tests for your changes. Go has a great test framework built in; use -it! Take a look at existing tests for inspiration. Run the full test suite on -your branch before submitting a pull request. - -Update the documentation when creating or modifying features. Test -your documentation changes for clarity, concision, and correctness, as -well as a clean documentation build. See ``docs/README.md`` for more -information on building the docs and how docs get released. - -Write clean code. Universally formatted code promotes ease of writing, reading, -and maintenance. Always run `gofmt -s -w file.go` on each changed file before -committing your changes. Most editors have plugins that do this automatically. - -Pull requests descriptions should be as clear as possible and include a -reference to all the issues that they address. - -Pull requests must not contain commits from other users or branches. - -Commit messages must start with a capitalized and short summary (max. 50 -chars) written in the imperative, followed by an optional, more detailed -explanatory text which is separated from the summary by an empty line. - -Code review comments may be added to your pull request. Discuss, then make the -suggested modifications and push additional commits to your feature branch. Be -sure to post a comment after pushing. The new commits will show up in the pull -request automatically, but the reviewers will not be notified unless you -comment. - -Before the pull request is merged, make sure that you squash your commits into -logical units of work using `git rebase -i` and `git push -f`. After every -commit the test suite should be passing. Include documentation changes in the -same commit so that a revert would remove all traces of the feature or fix. - -Commits that fix or close an issue should include a reference like `Closes #XXX` -or `Fixes #XXX`, which will automatically close the issue when merged. - -### Sign your work - -The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as an open-source patch. The rules are pretty simple: if you -can certify the below (from -[developercertificate.org](http://developercertificate.org/)): - -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` - -then you just add a line to every git commit message: - - Signed-off-by: Joe Smith - -using your real name (sorry, no pseudonyms or anonymous contributions.) - -You can add the sign off when creating the git commit via `git commit -s`. -# blag blah -# blag blah - -Ordered list: - - 1. xyz - 2. abc - -First list: - - - a - - b - - c - -Second list: - - * A - * B - * C - -Another Ordered list: - - 0. xyz - 0. abc -# OpenAPI errors [![Build Status](https://github.com/go-openapi/errors/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/errors/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/errors/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/errors) - -[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) -[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/errors/master/LICENSE) -[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/errors.svg)](https://pkg.go.dev/github.com/go-openapi/errors) -[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/errors)](https://goreportcard.com/report/github.com/go-openapi/errors) - -Shared errors and error interface used throughout the various libraries found in the go-openapi toolkit. -# Contributor Covenant Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. - -## Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at ivan+abuse@flanders.co.nz. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] - -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ -## Contribution Guidelines - -### Pull requests are always welcome - -We are always thrilled to receive pull requests, and do our best to -process them as fast as possible. Not sure if that typo is worth a pull -request? Do it! We will appreciate it. - -If your pull request is not accepted on the first try, don't be -discouraged! If there's a problem with the implementation, hopefully you -received feedback on what to improve. - -We're trying very hard to keep go-swagger lean and focused. We don't want it -to do everything for everybody. This means that we might decide against -incorporating a new feature. However, there might be a way to implement -that feature *on top of* go-swagger. - - -### Conventions - -Fork the repo and make changes on your fork in a feature branch: - -- If it's a bugfix branch, name it XXX-something where XXX is the number of the - issue -- If it's a feature branch, create an enhancement issue to announce your - intentions, and name it XXX-something where XXX is the number of the issue. - -Submit unit tests for your changes. Go has a great test framework built in; use -it! Take a look at existing tests for inspiration. Run the full test suite on -your branch before submitting a pull request. - -Update the documentation when creating or modifying features. Test -your documentation changes for clarity, concision, and correctness, as -well as a clean documentation build. See ``docs/README.md`` for more -information on building the docs and how docs get released. - -Write clean code. Universally formatted code promotes ease of writing, reading, -and maintenance. Always run `gofmt -s -w file.go` on each changed file before -committing your changes. Most editors have plugins that do this automatically. - -Pull requests descriptions should be as clear as possible and include a -reference to all the issues that they address. - -Pull requests must not contain commits from other users or branches. - -Commit messages must start with a capitalized and short summary (max. 50 -chars) written in the imperative, followed by an optional, more detailed -explanatory text which is separated from the summary by an empty line. - -Code review comments may be added to your pull request. Discuss, then make the -suggested modifications and push additional commits to your feature branch. Be -sure to post a comment after pushing. The new commits will show up in the pull -request automatically, but the reviewers will not be notified unless you -comment. - -Before the pull request is merged, make sure that you squash your commits into -logical units of work using `git rebase -i` and `git push -f`. After every -commit the test suite should be passing. Include documentation changes in the -same commit so that a revert would remove all traces of the feature or fix. - -Commits that fix or close an issue should include a reference like `Closes #XXX` -or `Fixes #XXX`, which will automatically close the issue when merged. - -### Sign your work - -The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as an open-source patch. The rules are pretty simple: if you -can certify the below (from -[developercertificate.org](http://developercertificate.org/)): - -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` - -then you just add a line to every git commit message: - - Signed-off-by: Joe Smith - -using your real name (sorry, no pseudonyms or anonymous contributions.) - -You can add the sign off when creating the git commit via `git commit -s`. -Evaluate: - -* markdownlint - * assessment: go - * used by opentelemetry/opentelemetry-go - * packaged as github action -* misspell -* spellcheck -* govulncheck -* [x] godoc-lint: - * assessment: no go - * too simplistic: no real value added - * not integrated into golangci's suite of linters - * no packaged github action -

dfkjfkfj

- - -ERGGLGKLK -========== -this is a title -# .github -Default github settings for go-openapi repositories ---- -name: '❓ Question' -about: I have a question about this project -title: '' -labels: [question] -assignees: '' - ---- - -**Question** - - -**Additional context** - ---- -name: '➕ Feature request' -about: Suggest an idea for this project -title: '' -labels: [enhancement] -assignees: '' - ---- - -**Is your feature request related to a problem? Please describe.** - - -**Describe the solution you'd like** - - -**Describe alternatives you've considered** - - -**Additional context** - ---- -name: '🐞 Bug report' -about: Create a report to help us make go-openapi a great project -title: '' -labels: [bug] -assignees: '' - ---- - -**Describe the bug** - - -**Steps to Reproduce** - - - - -**Expected behavior** - - -**Actual behavior** - - -**Environment** - - -**Additional context** - -## Change type - -Please select: 🆕 New feature or enhancement|🔧 Bug fix'|📃 Documentation update - -## Short description - - -## Fixes - - -## Full description - - - - -## Checklist - - - -* [ ] I have signed all my commits with my name and email (see [DCO](https://github.com/apps/dco). **This does not require a PGP-signed commit** -* [ ] I have rebased and squashed my work, so only one commit remains -* [ ] I have added tests to cover my changes. -* [ ] I have properly enriched go doc comments in code. -* [ ] I have properly documented any breaking change. -## Change type: 📃 Documentation update - -## Short description - - -## Fixes - - -## Checklist - - - -* [ ] I have signed all my commits with my name and email (see [DCO](https://github.com/apps/dco). **This does not require a PGP-signed commit** -* [ ] I have rebased and squashed my work, so only one commit remains -* [ ] I have signed all my commits with my name and email (see DCO: https://github.com/apps/dco). **This does not require a PGP-signed commit** -* [ ] I have rebased and squash my work, so only one commit remains -* [ ] I have only modified comments in code or markdown files -## Change type: 🆕 New feature or enhancement - -## Short description - - -## Fixes - - -## Checklist - - - -* [ ] I have signed all my commits with my name and email (see [DCO](https://github.com/apps/dco). **This does not require a PGP-signed commit** -* [ ] I have rebased and squashed my work, so only one commit remains -* [ ] I have added tests to cover my changes. -* [ ] I have properly enriched go doc comments in code. -* [ ] I have properly documented any breaking change. -## Change type: 🔧 Bug fix - -## Short description - - -## Fixes - - -## Full description - - - - -## Checklist - - - -* [ ] I have signed all my commits with my name and email (see [DCO](https://github.com/apps/dco). **This does not require a PGP-signed commit** -* [ ] I have rebased and squashed my work, so only one commit remains -* [ ] I have added tests to cover my changes. -* [ ] I have made sure that my code remains portable -* [ ] I have properly enriched go doc comments in code. -* [ ] I have properly documented any breaking change. -# OpenAPI initiative random data generator [![Build Status](https://travis-ci.org/go-openapi/stubs.svg?branch=master)](https://travis-ci.org/go-openapi/stubs) [![codecov](https://codecov.io/gh/go-openapi/stubs/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/stubs) [![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) - -[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/stubs/master/LICENSE) [![GoDoc](https://godoc.org/github.com/go-openapi/stubs?status.svg)](http://godoc.org/github.com/go-openapi/stubs) - - -A library to generate random data for a swagger specification. -This is a building block for generating stubs for your API as well as tests. -# Contributor Covenant Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. - -## Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at ivan+abuse@flanders.co.nz. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] - -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ -# Stubs design - -The goal of this library is to be able to generate somewhat good looking random data for structures defined in an openapi or jsonschema document. -These can be used to provide an api with stubs so that you can verify valid and invalid request/responses without an actually meaningful implementation. -Some areas where this is useful are collaboration between different teams so that all teams can do work without having to wait on the delivery of the completed implementation of the API. -A second area where this is obviously useful is for doing automated tests and filling up datastructures for use in those tests. - - -In the openapi 2.0 specification there are 2 families of types that can be used as targets for a random data generator. - -1. Path Item related types - 1. Non-Schema Parameters - 2. Response headers - 3. Collection Items on parameters or headers -2. Schemas - -These 2 families warrant slightly different strategies for getting the necessary parameters for a datagenerator. - -## Functionality - -To generate meaningful random data the library looks at the schema and based on properties for that schema it picks an appropriate random value generator. -This means that when it is generating a string for an object property that represents a first name it should pick a data generator that generates first names. -Similarly should a property be called city it should generate a city name. - -It's possible that the validity of a particular property is dependent on the value of another property, for example a creation date is typically never larger than a modified date. - -A data generator for a schema should be able to generate valid and invalid data, ideally there is control for specifying the value is invalid for a particular validation. This will help in tests to validate error codes - -## How does it work - -The main components in this library are a registry of datagenerators so they are addressable by keys, aliases for those keys to aid with inferring which datagenerator to use. -And of course a value generator, which will generate either a valid or an invalid value. - -In the openapi API document and in a json schema document there is a vendor extension that can be used to customize the generation process. - -### Value generator function - -There are 2 types of data generators but they both have the same function signature. -There are value generators and there are composite value generators. - -* A value generator generates a single value for a simple type. -* A composite generator generates a value that is built out of one or more generators eg. object schemas with properties. - -The signature for the value generator is: - -```go -type ValueGenerator func(GeneratorOpts) (interface{}, error) -``` - -A value generator is the innermost component in the library and the arguments to the function are used to configure the generator. -The generation process for a generator is configured through a GeneratorOpts interface. - -### GeneratorOpts interface - -The generator options describe the type and potentially the format for the value that needs to be generated. -In addition to the type information it also captures the field name or definition name of the value that needs to be generated. - -### StubMode - -The stubmode bitmask allows for configuring which validations should fail for a given value generator. - -### Generator - -The generator is the main entry point for the library and its Generate method is what will generate the random value for the descriptor. -# Use cases for stubs - -The stubs package is intended to support the following use cases: - -1. Generate unit test cases for code generated by go-swagger, especially validation code -2. Generate test cases for API servers and clients -3. Generate realistic examples - -## Supported swagger 2.0 constructs - -- parameter -- header -- response -- schema, including support for: - - [] AllOf - - [] Not - - [] additionalProperties - - [] patternProperties - - [] additionalItems - -Formated strings and numbers support go-openapi/strfmt formats, including: - - [] binary (strfmt.Base64) - - [] bsonobjectid - -The "file" datatype is not supported at the moment. - -The generation assumes the provide swagger spec is valid. - -Warnings regarding test case (2): -- stubs is not concerned about security definitions and credentials -- stubs generates values independently for each parameter, or response: it does not know about consistent sets of values beyond validation constraints, let alone - proper chaining of request with responses. - -## Sample applications for stubs - -- process a spec to include examples -- generate fixtures for codegen unit testing -- generate fixtures for API server benchmarking -- ... - -# Reproducible stubs - -Generated stubs may be regenerated using the same initial seed. - -There are two seeding modes to run the stubs generator: - -- AutoSeed: reseeds itself based on current timestamp -- SetSeed: generation occurs with a single seed, provided by the caller - -The package uses a default seeder to carry on this task. Alternate seeders might be provided. - -This also allows for unit testing this very package... - -# Setting generation goals - -Goals select the general use case and allow for fine tuning of the sample generation. - -We use GenerateMode and StubMode flags to define goals. - -Stubmode is used to tune individually every single generated value. - -GenerateMode sets general directives and may define StubMode autonomously according to the generation goal. - -## GenerateMode - -target: -- unitTest: any value value may be produced, not necessarily a realistic definevalue. - By default in the UnitTest mode, non-formated strings are loren ipsums, numbers, dates and times may be very small or very large -- examples: the generator attempts to figure out realistic values to be used as examples - -GenerateMode accepts arguments to further specify the expected generation: - -args: -- valid: all generated values are valid. This is the default. - - count: number of samples to be generated. May be zero to get only default, examples, edge cases or validation checks. Default is 1. -- invalid: all generated values are invalid, with failures chosen at random. - - count: number of samples to be generated. Default is 1. -- skipTilting: tilting rules are omitted (only applies to invalid values). Default is true in unit test mode and false in example mode. -- skipFuzzying: fuzzying rules are omitted -- withTilting: add tilted invalid values, with failures chosen at random. This forces a tilting strategy on a new set of values. - - count: number of tilted samples to be generated. Default is 1. -- withValidationCheck: for each validation, an invalid value against this validation is generated (e.g. if min and max are specified, we have one value below min and one value above max) - - count: this sets a limit on the count of generated values. If you have n validations, that makes n generated values. With the limit set, validations are checked width-first (outermost validations come first) -- withAllValidationChecks: all combinations of failed validations are generated. This includes one valid value and single failure from withValidation. - - count: this sets a limit on the count of generated values. If you have n validations, that makes 2^n generated values, which may raise quickly when nesting schema structures. With the limit set, validations are checked width-first (outermost validations come first) -- withDefault: add default value to sample values (not included in "count"). This simulates a user providing exactly the same value as the default. Since defaults may be set at different levels of the structure, a new value is generated for each applicable default. -- withExample: add example value to sample values (not included in "count"), whenever applicable. Examples are assumed valid, but may be invalid. - - tiltDefault: constructs invalid values by tilting default - - tiltExample: constructs invalid values by tilting examples - - count: number of title -- withEdgeCase: - - standard: standard preconfigured edge cases (e.g. boundary value for min constraint with boundary included, Feb 29th dates for date types, ...) - - value: a customizable value added as an edge case. May be any value, array or object. Severa values may be specified. -- max: an upper limit on number generation (floats, ints, ...). By default, the full range of the data type is used. -- min: a lower limit on number generation. -- precision: rounding specification for floats -- multipleOf: a multiple specification for numbers -- length: - - on string values: an upper limit on string size, to avoid long texts being unwittingly generated - - on array values: an upper limit on the number of generated items - - on additionalProperties: an upper limit on the number of generated additionalProperties - - on patternProperties: an upper limit on the number of generated patternProperties -- words: a limit on the number of words in generated texts, paragraphs and sentences -- lang: specifies the target language(s) for strings and text. - - [lang] - - all: special value to tell the generator to pick text at random from all supported languages - -This sets an overall target for all generations. For every single spec object, you may hint further and override global settings on a case by case basis. - -# Hinting - -The `x-datagen` extension may be used in the swagger spec to hint the stubs generator. - -Examples: -``` -parameters: - phone: - in: query - required: true - type: string - x-datagen: - name: mobile -``` -will generate a mobile phone number for query parameter "phone". - -``` -parameters: - price: - in: query - required: true - type: string - x-datagen: - name: float -``` -will generate float numbers for the price parameter. -It might be not realistic to have 3.1344344E35 as a price, but it is a valid value... - -`x-datagen` accepts args to further hint the generator. -All Args accepted by GenerateMode or StubMode may be used here to locally override generation options. - -Example: -``` -parameters: - vat: - in: query - required: true - type: number - x-datagen: - args: - min: 100 - max: 10000 - -``` -will generate floats between 100 and 10000. -Again, it might not be realistic to have prices such as 503.14561434566... - -Some generators are already configured to suit some targeted usage. - -Example: -``` -parameters: - price: - in: query - required: true - type: string - x-datagen: - name: small-amounts -``` -and you get more realistic values like 3.23, 104.30... - -## x-datagen args - -- name: overrides the generator's name - -Supported args, not already mentioned in the GenerateMode section: -- args: - -# Fuzzying - -The generation takes basic decisions based on type and available validation constraints. -Obviously, this does not work well when the goal is to generate realistic samples for your data. -Of course, everyhing may be fine-tuned by using the x-datagen extension. -But this is tedious work on large specs. - -We introduce fuzzying as a way to carry on some of the guesswork when deciding which kind of fake value would best match expectations. -Fuzzying relies on names, titles and description to look for recognizable keywords, then elects an adequate random generator. - -Examples for the above samples: -- with name "price", the fuzzying guesses that it is not some arbitrary float to be generated, but a decimal between 0 and 1,000,000 (max overrides this limit). -- with a description such as "The item price expressed in USD. Items are sold at a low price", fuzzying rules should guess that we want to generate small-amount values (so between 0 and 1,000). - -Fuzzying also works for non-strings data: -- a date field named "birthday" would hint toward the birthdate value generator (hence dates are not in the future and only in a recent past) -- a datetime named "timestamp" or described as "The update date" would generate a recent datetime value. Further, edge cases with this guess would add 01/01/1970 to the generated value - -# Tilting - -Tilting is a strategy to generate invalid values, by tilting a valid value just enough so it becomes invalid. -This generates interesting test cases since values are supposed to be "almost" valid but actually are not. - -Tilting strategies depend on validations. - -Examples: -- tilting on max will generate a value at or slightly above the lowest invalid value -- tilting on regexp will change the smallest number of characters in a string so the regexp no more matches -- tilting on enum will slightly modify a valid value and make it invalid -- ... - -Options skipTilting and withTilting tune the generator behavior regarding tilting. -# gojsonpointer [![Build Status](https://github.com/go-openapi/jsonpointer/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/jsonpointer/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/jsonpointer/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/jsonpointer) - -[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) -[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/jsonpointer/master/LICENSE) -[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/jsonpointer.svg)](https://pkg.go.dev/github.com/go-openapi/jsonpointer) -[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/jsonpointer)](https://goreportcard.com/report/github.com/go-openapi/jsonpointer) - -An implementation of JSON Pointer - Go language - -## Status -Completed YES - -Tested YES - -## References -http://tools.ietf.org/html/draft-ietf-appsawg-json-pointer-07 - -### Note -The 4.Evaluation part of the previous reference, starting with 'If the currently referenced value is a JSON array, the reference token MUST contain either...' is not implemented. -# Contributor Covenant Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. - -## Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at ivan+abuse@flanders.co.nz. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] - -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ -## Contribution Guidelines - -### Pull requests are always welcome - -We are always thrilled to receive pull requests, and do our best to -process them as fast as possible. Not sure if that typo is worth a pull -request? Do it! We will appreciate it. - -If your pull request is not accepted on the first try, don't be -discouraged! If there's a problem with the implementation, hopefully you -received feedback on what to improve. - -We're trying very hard to keep go-swagger lean and focused. We don't want it -to do everything for everybody. This means that we might decide against -incorporating a new feature. However, there might be a way to implement -that feature *on top of* go-swagger. - - -### Conventions - -Fork the repo and make changes on your fork in a feature branch: - -- If it's a bugfix branch, name it XXX-something where XXX is the number of the - issue -- If it's a feature branch, create an enhancement issue to announce your - intentions, and name it XXX-something where XXX is the number of the issue. - -Submit unit tests for your changes. Go has a great test framework built in; use -it! Take a look at existing tests for inspiration. Run the full test suite on -your branch before submitting a pull request. - -Update the documentation when creating or modifying features. Test -your documentation changes for clarity, concision, and correctness, as -well as a clean documentation build. See ``docs/README.md`` for more -information on building the docs and how docs get released. - -Write clean code. Universally formatted code promotes ease of writing, reading, -and maintenance. Always run `gofmt -s -w file.go` on each changed file before -committing your changes. Most editors have plugins that do this automatically. - -Pull requests descriptions should be as clear as possible and include a -reference to all the issues that they address. - -Pull requests must not contain commits from other users or branches. - -Commit messages must start with a capitalized and short summary (max. 50 -chars) written in the imperative, followed by an optional, more detailed -explanatory text which is separated from the summary by an empty line. - -Code review comments may be added to your pull request. Discuss, then make the -suggested modifications and push additional commits to your feature branch. Be -sure to post a comment after pushing. The new commits will show up in the pull -request automatically, but the reviewers will not be notified unless you -comment. - -Before the pull request is merged, make sure that you squash your commits into -logical units of work using `git rebase -i` and `git push -f`. After every -commit the test suite should be passing. Include documentation changes in the -same commit so that a revert would remove all traces of the feature or fix. - -Commits that fix or close an issue should include a reference like `Closes #XXX` -or `Fixes #XXX`, which will automatically close the issue when merged. - -### Sign your work - -The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as an open-source patch. The rules are pretty simple: if you -can certify the below (from -[developercertificate.org](http://developercertificate.org/)): - -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` - -then you just add a line to every git commit message: - - Signed-off-by: Joe Smith - -using your real name (sorry, no pseudonyms or anonymous contributions.) - -You can add the sign off when creating the git commit via `git commit -s`. -# Swagger 2.0 specification schema - -This folder contains the Swagger 2.0 specification schema files maintained here: - -https://github.com/reverb/swagger-spec/blob/master/schemas/v2.0# OpenAPI v2 object model [![Build Status](https://github.com/go-openapi/spec/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/spec/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/spec/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/spec) - -[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) -[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/spec/master/LICENSE) -[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/spec.svg)](https://pkg.go.dev/github.com/go-openapi/spec) -[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/spec)](https://goreportcard.com/report/github.com/go-openapi/spec) - -The object model for OpenAPI specification documents. - -### FAQ - -* What does this do? - -> 1. This package knows how to marshal and unmarshal Swagger API specifications into a golang object model -> 2. It knows how to resolve $ref and expand them to make a single root document - -* How does it play with the rest of the go-openapi packages ? - -> 1. This package is at the core of the go-openapi suite of packages and [code generator](https://github.com/go-swagger/go-swagger) -> 2. There is a [spec loading package](https://github.com/go-openapi/loads) to fetch specs as JSON or YAML from local or remote locations -> 3. There is a [spec validation package](https://github.com/go-openapi/validate) built on top of it -> 4. There is a [spec analysis package](https://github.com/go-openapi/analysis) built on top of it, to analyze, flatten, fix and merge spec documents - -* Does this library support OpenAPI 3? - -> No. -> This package currently only supports OpenAPI 2.0 (aka Swagger 2.0). -> There is no plan to make it evolve toward supporting OpenAPI 3.x. -> This [discussion thread](https://github.com/go-openapi/spec/issues/21) relates the full story. -> -> An early attempt to support Swagger 3 may be found at: https://github.com/go-openapi/spec3 - -* Does the unmarshaling support YAML? - -> Not directly. The exposed types know only how to unmarshal from JSON. -> -> In order to load a YAML document as a Swagger spec, you need to use the loaders provided by -> github.com/go-openapi/loads -> -> Take a look at the example there: https://pkg.go.dev/github.com/go-openapi/loads#example-Spec -> -> See also https://github.com/go-openapi/spec/issues/164 - -* How can I validate a spec? - -> Validation is provided by [the validate package](http://github.com/go-openapi/validate) - -* Why do we have an `ID` field for `Schema` which is not part of the swagger spec? - -> We found jsonschema compatibility more important: since `id` in jsonschema influences -> how `$ref` are resolved. -> This `id` does not conflict with any property named `id`. -> -> See also https://github.com/go-openapi/spec/issues/23 -# Contributor Covenant Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. - -## Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at ivan+abuse@flanders.co.nz. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] - -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ -## Contribution Guidelines - -### Pull requests are always welcome - -We are always thrilled to receive pull requests, and do our best to -process them as fast as possible. Not sure if that typo is worth a pull -request? Do it! We will appreciate it. - -If your pull request is not accepted on the first try, don't be -discouraged! If there's a problem with the implementation, hopefully you -received feedback on what to improve. - -We're trying very hard to keep go-swagger lean and focused. We don't want it -to do everything for everybody. This means that we might decide against -incorporating a new feature. However, there might be a way to implement -that feature *on top of* go-swagger. - - -### Conventions - -Fork the repo and make changes on your fork in a feature branch: - -- If it's a bugfix branch, name it XXX-something where XXX is the number of the - issue -- If it's a feature branch, create an enhancement issue to announce your - intentions, and name it XXX-something where XXX is the number of the issue. - -Submit unit tests for your changes. Go has a great test framework built in; use -it! Take a look at existing tests for inspiration. Run the full test suite on -your branch before submitting a pull request. - -Update the documentation when creating or modifying features. Test -your documentation changes for clarity, concision, and correctness, as -well as a clean documentation build. See ``docs/README.md`` for more -information on building the docs and how docs get released. - -Write clean code. Universally formatted code promotes ease of writing, reading, -and maintenance. Always run `gofmt -s -w file.go` on each changed file before -committing your changes. Most editors have plugins that do this automatically. - -Pull requests descriptions should be as clear as possible and include a -reference to all the issues that they address. - -Pull requests must not contain commits from other users or branches. - -Commit messages must start with a capitalized and short summary (max. 50 -chars) written in the imperative, followed by an optional, more detailed -explanatory text which is separated from the summary by an empty line. - -Code review comments may be added to your pull request. Discuss, then make the -suggested modifications and push additional commits to your feature branch. Be -sure to post a comment after pushing. The new commits will show up in the pull -request automatically, but the reviewers will not be notified unless you -comment. - -Before the pull request is merged, make sure that you squash your commits into -logical units of work using `git rebase -i` and `git push -f`. After every -commit the test suite should be passing. Include documentation changes in the -same commit so that a revert would remove all traces of the feature or fix. - -Commits that fix or close an issue should include a reference like `Closes #XXX` -or `Fixes #XXX`, which will automatically close the issue when merged. - -### Sign your work - -The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as an open-source patch. The rules are pretty simple: if you -can certify the below (from -[developercertificate.org](http://developercertificate.org/)): - -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` - -then you just add a line to every git commit message: - - Signed-off-by: Joe Smith - -using your real name (sorry, no pseudonyms or anonymous contributions.) - -You can add the sign off when creating the git commit via `git commit -s`. -# gojsonreference [![Build Status](https://github.com/go-openapi/jsonreference/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/jsonreference/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/jsonreference/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/jsonreference) - -[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) -[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/jsonreference/master/LICENSE) -[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/jsonreference.svg)](https://pkg.go.dev/github.com/go-openapi/jsonreference) -[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/jsonreference)](https://goreportcard.com/report/github.com/go-openapi/jsonreference) - -An implementation of JSON Reference - Go language - -## Status -Feature complete. Stable API - -## Dependencies -* https://github.com/go-openapi/jsonpointer - -## References - -* http://tools.ietf.org/html/draft-ietf-appsawg-json-pointer-07 -* http://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03 -# Contributor Covenant Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. - -## Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at ivan+abuse@flanders.co.nz. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] - -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ -## Contribution Guidelines - -### Pull requests are always welcome - -We are always thrilled to receive pull requests, and do our best to -process them as fast as possible. Not sure if that typo is worth a pull -request? Do it! We will appreciate it. - -If your pull request is not accepted on the first try, don't be -discouraged! If there's a problem with the implementation, hopefully you -received feedback on what to improve. - -We're trying very hard to keep go-swagger lean and focused. We don't want it -to do everything for everybody. This means that we might decide against -incorporating a new feature. However, there might be a way to implement -that feature *on top of* go-swagger. - - -### Conventions - -Fork the repo and make changes on your fork in a feature branch: - -- If it's a bugfix branch, name it XXX-something where XXX is the number of the - issue -- If it's a feature branch, create an enhancement issue to announce your - intentions, and name it XXX-something where XXX is the number of the issue. - -Submit unit tests for your changes. Go has a great test framework built in; use -it! Take a look at existing tests for inspiration. Run the full test suite on -your branch before submitting a pull request. - -Update the documentation when creating or modifying features. Test -your documentation changes for clarity, concision, and correctness, as -well as a clean documentation build. See ``docs/README.md`` for more -information on building the docs and how docs get released. - -Write clean code. Universally formatted code promotes ease of writing, reading, -and maintenance. Always run `gofmt -s -w file.go` on each changed file before -committing your changes. Most editors have plugins that do this automatically. - -Pull requests descriptions should be as clear as possible and include a -reference to all the issues that they address. - -Pull requests must not contain commits from other users or branches. - -Commit messages must start with a capitalized and short summary (max. 50 -chars) written in the imperative, followed by an optional, more detailed -explanatory text which is separated from the summary by an empty line. - -Code review comments may be added to your pull request. Discuss, then make the -suggested modifications and push additional commits to your feature branch. Be -sure to post a comment after pushing. The new commits will show up in the pull -request automatically, but the reviewers will not be notified unless you -comment. - -Before the pull request is merged, make sure that you squash your commits into -logical units of work using `git rebase -i` and `git push -f`. After every -commit the test suite should be passing. Include documentation changes in the -same commit so that a revert would remove all traces of the feature or fix. - -Commits that fix or close an issue should include a reference like `Closes #XXX` -or `Fixes #XXX`, which will automatically close the issue when merged. - -### Sign your work - -The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as an open-source patch. The rules are pretty simple: if you -can certify the below (from -[developercertificate.org](http://developercertificate.org/)): - -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` - -then you just add a line to every git commit message: - - Signed-off-by: Joe Smith - -using your real name (sorry, no pseudonyms or anonymous contributions.) - -You can add the sign off when creating the git commit via `git commit -s`. -# doc - -Documentation check and generation tools. -# ci-workflows[![Build Status](https://github.com/go-openapi/ci-workflows/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/ci-workflows/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/ci-workflows/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/ci-workflows) - -[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) -[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/ci-workflows/master/LICENSE) -[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/ci-workflows.svg)](https://pkg.go.dev/github.com/go-openapi/ci-workflows) -[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/ci-workflows)](https://goreportcard.com/report/github.com/go-openapi/ci-workflows) - -Common Continuous Integration (`CI`) workflows and setup for go-openapi repos. - -* shared github action workflows -* shared `dependabot` configuration (TODO) -* shared `golangci-lint` configuration (**BLOCKED**) - -> NOTE: at this moment, it is difficult to share the golangci-lint config, -> so that one is not shared yet. - -## Motivation - -It took a while, but we eventually managed to align all checks, tests and -dependabot rules declared in the family of go-openapi repos. - -Now we'd like to be able to maintain, enrich and improve these checks without -worrying too much about the burden to replicate it about a dozen times. - -## Contemplated enhancements - -In no particular order: - -* [x] ui: enrich github actions UI with a job summary -* [x] doc: add markdown linting for docs -* [x] doc: add spellcheck for docs (and code?) -* [ ] version common workflows, so we can limit the impact of a change -* [ ] build: verify that go.sum cache for tests works (should be enabled) -* [ ] share mono repo workflows (see github.com/go-openapi/swag/.github/workflows) -* [ ] lint: manage somehow to share golangci config (with local merge) -* [ ] dependencies: manage somehow to share / replicate dependabot config -* [ ] lint: golangci-lint: check valid PR comments etc -* [ ] lint: use non-blocking, scheduled, proactive full linting to check for - the impact of new linters, new go versions etc -* [ ] doc: (possibility) take over hugo & doc gen part from go-swagger -* [ ] (possibility) take over release part from go-swagger -* [ ] doc: produce hugo github page with all latest tagged versions - (incl. mono repo) -* [ ] add bot to filter PRs, issues -* [ ] check with github API that all repo settings (branch protection rules, etc) - are identical -* [ ] comment PRs and issues -# Contributor Covenant Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. - -## Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at ivan+abuse@flanders.co.nz. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] - -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ -## Contribution Guidelines - -### Pull requests are always welcome - -We are always thrilled to receive pull requests, and do our best to -process them as fast as possible. Not sure if that typo is worth a pull -request? Do it! We will appreciate it. - -If your pull request is not accepted on the first try, don't be -discouraged! If there's a problem with the implementation, hopefully you -received feedback on what to improve. - -We're trying very hard to keep go-swagger lean and focused. We don't want it -to do everything for everybody. This means that we might decide against -incorporating a new feature. However, there might be a way to implement -that feature *on top of* go-swagger. - - -### Conventions - -Fork the repo and make changes on your fork in a feature branch: - -- If it's a bugfix branch, name it XXX-something where XXX is the number of the - issue -- If it's a feature branch, create an enhancement issue to announce your - intentions, and name it XXX-something where XXX is the number of the issue. - -Submit unit tests for your changes. Go has a great test framework built in; use -it! Take a look at existing tests for inspiration. Run the full test suite on -your branch before submitting a pull request. - -Update the documentation when creating or modifying features. Test -your documentation changes for clarity, concision, and correctness, as -well as a clean documentation build. See ``docs/README.md`` for more -information on building the docs and how docs get released. - -Write clean code. Universally formatted code promotes ease of writing, reading, -and maintenance. Always run `gofmt -s -w file.go` on each changed file before -committing your changes. Most editors have plugins that do this automatically. - -Pull requests descriptions should be as clear as possible and include a -reference to all the issues that they address. - -Pull requests must not contain commits from other users or branches. - -Commit messages must start with a capitalized and short summary (max. 50 -chars) written in the imperative, followed by an optional, more detailed -explanatory text which is separated from the summary by an empty line. - -Code review comments may be added to your pull request. Discuss, then make the -suggested modifications and push additional commits to your feature branch. Be -sure to post a comment after pushing. The new commits will show up in the pull -request automatically, but the reviewers will not be notified unless you -comment. - -Before the pull request is merged, make sure that you squash your commits into -logical units of work using `git rebase -i` and `git push -f`. After every -commit the test suite should be passing. Include documentation changes in the -same commit so that a revert would remove all traces of the feature or fix. - -Commits that fix or close an issue should include a reference like `Closes #XXX` -or `Fixes #XXX`, which will automatically close the issue when merged. - -### Sign your work - -The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as an open-source patch. The rules are pretty simple: if you -can certify the below (from -[developercertificate.org](http://developercertificate.org/)): - -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` - -then you just add a line to every git commit message: - - Signed-off-by: Joe Smith - -using your real name (sorry, no pseudonyms or anonymous contributions.) - -You can add the sign off when creating the git commit via `git commit -s`. -# Audit - -Audit of github repos to check for inconsistencies. -# inflect [![Build Status](https://github.com/go-openapi/inflect/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/inflect/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/inflect/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/inflect) - -[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) -[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/inflect/master/LICENSE) -[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/inflect.svg)](https://pkg.go.dev/github.com/go-openapi/inflect) -[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/inflect)](https://goreportcard.com/report/github.com/go-openapi/inflect) - -A package to pluralize words. - -Originally forked from fork of https://bitbucket.org/pkg/inflect under a MIT License. - -A golang library applying grammar rules to English words. - -> This package provides a basic set of functions applying -> grammar rules to inflect English words, modify case style -> (Capitalize, camelCase, snake_case, etc.). -> -> Acronyms are properly handled. A common use case is word pluralization. - - -This library is not used at all by other go-openapi packages and is somewhat redundant with -go-openapi/swag/mangling (for camelcase etc). - -Currently we have one single dependency in one place in a go-swagger template (used as a funcmap). - -## Note to maintainers - -* Aug. 2025: CI workflows have now moved to a shared repository go-openapi/ci-workflows -## Contribution Guidelines - -### Pull requests are always welcome - -We are always thrilled to receive pull requests, and do our best to -process them as fast as possible. Not sure if that typo is worth a pull -request? Do it! We will appreciate it. - -If your pull request is not accepted on the first try, don't be -discouraged! If there's a problem with the implementation, hopefully you -received feedback on what to improve. - -We're trying very hard to keep go-swagger lean and focused. We don't want it -to do everything for everybody. This means that we might decide against -incorporating a new feature. However, there might be a way to implement -that feature *on top of* go-swagger. - - -### Conventions - -Fork the repo and make changes on your fork in a feature branch: - -- If it's a bugfix branch, name it XXX-something where XXX is the number of the - issue -- If it's a feature branch, create an enhancement issue to announce your - intentions, and name it XXX-something where XXX is the number of the issue. - -Submit unit tests for your changes. Go has a great test framework built in; use -it! Take a look at existing tests for inspiration. Run the full test suite on -your branch before submitting a pull request. - -Update the documentation when creating or modifying features. Test -your documentation changes for clarity, concision, and correctness, as -well as a clean documentation build. See ``docs/README.md`` for more -information on building the docs and how docs get released. - -Write clean code. Universally formatted code promotes ease of writing, reading, -and maintenance. Always run `gofmt -s -w file.go` on each changed file before -committing your changes. Most editors have plugins that do this automatically. - -Pull requests descriptions should be as clear as possible and include a -reference to all the issues that they address. - -Pull requests must not contain commits from other users or branches. - -Commit messages must start with a capitalized and short summary (max. 50 -chars) written in the imperative, followed by an optional, more detailed -explanatory text which is separated from the summary by an empty line. - -Code review comments may be added to your pull request. Discuss, then make the -suggested modifications and push additional commits to your feature branch. Be -sure to post a comment after pushing. The new commits will show up in the pull -request automatically, but the reviewers will not be notified unless you -comment. - -Before the pull request is merged, make sure that you squash your commits into -logical units of work using `git rebase -i` and `git push -f`. After every -commit the test suite should be passing. Include documentation changes in the -same commit so that a revert would remove all traces of the feature or fix. - -Commits that fix or close an issue should include a reference like `Closes #XXX` -or `Fixes #XXX`, which will automatically close the issue when merged. - -### Sign your work - -The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as an open-source patch. The rules are pretty simple: if you -can certify the below (from -[developercertificate.org](http://developercertificate.org/)): - -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` - -then you just add a line to every git commit message: - - Signed-off-by: Joe Smith - -using your real name (sorry, no pseudonyms or anonymous contributions.) - -You can add the sign off when creating the git commit via `git commit -s`. -# Validation helpers [![Build Status](https://github.com/go-openapi/validate/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/validate/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/validate/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/validate) - -[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) -[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/validate/master/LICENSE) -[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/validate.svg)](https://pkg.go.dev/github.com/go-openapi/validate) -[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/validate)](https://goreportcard.com/report/github.com/go-openapi/validate) - -This package provides helpers to validate Swagger 2.0. specification (aka OpenAPI 2.0). - -Reference can be found here: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md. - -## What's inside? - -* A validator for Swagger specifications -* A validator for JSON schemas draft4 -* Helper functions to validate individual values (used by code generated by [go-swagger](https://github.com/go-swagger/go-swagger)). - * Required, RequiredNumber, RequiredString - * ReadOnly - * UniqueItems, MaxItems, MinItems - * Enum, EnumCase - * Pattern, MinLength, MaxLength - * Minimum, Maximum, MultipleOf - * FormatOf - -[Documentation](https://pkg.go.dev/github.com/go-openapi/validate) - -## FAQ - -* Does this library support OpenAPI 3? - -> No. -> This package currently only supports OpenAPI 2.0 (aka Swagger 2.0). -> There is no plan to make it evolve toward supporting OpenAPI 3.x. -> This [discussion thread](https://github.com/go-openapi/spec/issues/21) relates the full story. -> -> An early attempt to support Swagger 3 may be found at: https://github.com/go-openapi/spec3 -# Contributor Covenant Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. - -## Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at ivan+abuse@flanders.co.nz. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] - -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ -## Contribution Guidelines - -### Pull requests are always welcome - -We are always thrilled to receive pull requests, and do our best to -process them as fast as possible. Not sure if that typo is worth a pull -request? Do it! We will appreciate it. - -If your pull request is not accepted on the first try, don't be -discouraged! If there's a problem with the implementation, hopefully you -received feedback on what to improve. - -We're trying very hard to keep go-swagger lean and focused. We don't want it -to do everything for everybody. This means that we might decide against -incorporating a new feature. However, there might be a way to implement -that feature *on top of* go-swagger. - - -### Conventions - -Fork the repo and make changes on your fork in a feature branch: - -- If it's a bugfix branch, name it XXX-something where XXX is the number of the - issue -- If it's a feature branch, create an enhancement issue to announce your - intentions, and name it XXX-something where XXX is the number of the issue. - -Submit unit tests for your changes. Go has a great test framework built in; use -it! Take a look at existing tests for inspiration. Run the full test suite on -your branch before submitting a pull request. - -Update the documentation when creating or modifying features. Test -your documentation changes for clarity, concision, and correctness, as -well as a clean documentation build. See ``docs/README.md`` for more -information on building the docs and how docs get released. - -Write clean code. Universally formatted code promotes ease of writing, reading, -and maintenance. Always run `gofmt -s -w file.go` on each changed file before -committing your changes. Most editors have plugins that do this automatically. - -Pull requests descriptions should be as clear as possible and include a -reference to all the issues that they address. - -Pull requests must not contain commits from other users or branches. - -Commit messages must start with a capitalized and short summary (max. 50 -chars) written in the imperative, followed by an optional, more detailed -explanatory text which is separated from the summary by an empty line. - -Code review comments may be added to your pull request. Discuss, then make the -suggested modifications and push additional commits to your feature branch. Be -sure to post a comment after pushing. The new commits will show up in the pull -request automatically, but the reviewers will not be notified unless you -comment. - -Before the pull request is merged, make sure that you squash your commits into -logical units of work using `git rebase -i` and `git push -f`. After every -commit the test suite should be passing. Include documentation changes in the -same commit so that a revert would remove all traces of the feature or fix. - -Commits that fix or close an issue should include a reference like `Closes #XXX` -or `Fixes #XXX`, which will automatically close the issue when merged. - -### Sign your work - -The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as an open-source patch. The rules are pretty simple: if you -can certify the below (from -[developercertificate.org](http://developercertificate.org/)): - -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` - -then you just add a line to every git commit message: - - Signed-off-by: Joe Smith - -using your real name (sorry, no pseudonyms or anonymous contributions.) - -You can add the sign off when creating the git commit via `git commit -s`. -# Benchmark - -Validating the Kubernetes Swagger API - -## v0.22.6: 60,000,000 allocs -``` -goos: linux -goarch: amd64 -pkg: github.com/go-openapi/validate -cpu: AMD Ryzen 7 5800X 8-Core Processor -Benchmark_KubernetesSpec/validating_kubernetes_API-16 1 8549863982 ns/op 7067424936 B/op 59583275 allocs/op -``` - -## After refact PR: minor but noticable improvements: 25,000,000 allocs -``` -go test -bench Spec -goos: linux -goarch: amd64 -pkg: github.com/go-openapi/validate -cpu: AMD Ryzen 7 5800X 8-Core Processor -Benchmark_KubernetesSpec/validating_kubernetes_API-16 1 4064535557 ns/op 3379715592 B/op 25320330 allocs/op -``` - -## After reduce GC pressure PR: 17,000,000 allocs -``` -goos: linux -goarch: amd64 -pkg: github.com/go-openapi/validate -cpu: AMD Ryzen 7 5800X 8-Core Processor -Benchmark_KubernetesSpec/validating_kubernetes_API-16 1 3758414145 ns/op 2593881496 B/op 17111373 allocs/op -``` -# Denco [![Build Status](https://travis-ci.org/naoina/denco.png?branch=master)](https://travis-ci.org/naoina/denco) - -The fast and flexible HTTP request router for [Go](http://golang.org). - -Denco is based on Double-Array implementation of [Kocha-urlrouter](https://github.com/naoina/kocha-urlrouter). -However, Denco is optimized and some features added. - -## Features - -* Fast (See [go-http-routing-benchmark](https://github.com/naoina/go-http-routing-benchmark)) -* [URL patterns](#url-patterns) (`/foo/:bar` and `/foo/*wildcard`) -* Small (but enough) URL router API -* HTTP request multiplexer like `http.ServeMux` - -## Installation - - go get -u github.com/go-openapi/runtime/middleware/denco - -## Using as HTTP request multiplexer - -```go -package main - -import ( - "fmt" - "log" - "net/http" - - "github.com/go-openapi/runtime/middleware/denco" -) - -func Index(w http.ResponseWriter, r *http.Request, params denco.Params) { - fmt.Fprintf(w, "Welcome to Denco!\n") -} - -func User(w http.ResponseWriter, r *http.Request, params denco.Params) { - fmt.Fprintf(w, "Hello %s!\n", params.Get("name")) -} - -func main() { - mux := denco.NewMux() - handler, err := mux.Build([]denco.Handler{ - mux.GET("/", Index), - mux.GET("/user/:name", User), - mux.POST("/user/:name", User), - }) - if err != nil { - panic(err) - } - log.Fatal(http.ListenAndServe(":8080", handler)) -} -``` - -## Using as URL router - -```go -package main - -import ( - "fmt" - - "github.com/go-openapi/runtime/middleware/denco" -) - -type route struct { - name string -} - -func main() { - router := denco.New() - router.Build([]denco.Record{ - {"/", &route{"root"}}, - {"/user/:id", &route{"user"}}, - {"/user/:name/:id", &route{"username"}}, - {"/static/*filepath", &route{"static"}}, - }) - - data, params, found := router.Lookup("/") - // print `&main.route{name:"root"}, denco.Params(nil), true`. - fmt.Printf("%#v, %#v, %#v\n", data, params, found) - - data, params, found = router.Lookup("/user/hoge") - // print `&main.route{name:"user"}, denco.Params{denco.Param{Name:"id", Value:"hoge"}}, true`. - fmt.Printf("%#v, %#v, %#v\n", data, params, found) - - data, params, found = router.Lookup("/user/hoge/7") - // print `&main.route{name:"username"}, denco.Params{denco.Param{Name:"name", Value:"hoge"}, denco.Param{Name:"id", Value:"7"}}, true`. - fmt.Printf("%#v, %#v, %#v\n", data, params, found) - - data, params, found = router.Lookup("/static/path/to/file") - // print `&main.route{name:"static"}, denco.Params{denco.Param{Name:"filepath", Value:"path/to/file"}}, true`. - fmt.Printf("%#v, %#v, %#v\n", data, params, found) -} -``` - -See [Godoc](http://godoc.org/github.com/go-openapi/runtime/middleware/denco) for more details. - -## Getting the value of path parameter - -You can get the value of path parameter by 2 ways. - -1. Using [`denco.Params.Get`](http://godoc.org/github.com/go-openapi/runtime/middleware/denco#Params.Get) method -2. Find by loop - -```go -package main - -import ( - "fmt" - - "github.com/go-openapi/runtime/middleware/denco" -) - -func main() { - router := denco.New() - if err := router.Build([]denco.Record{ - {"/user/:name/:id", "route1"}, - }); err != nil { - panic(err) - } - - // 1. Using denco.Params.Get method. - _, params, _ := router.Lookup("/user/alice/1") - name := params.Get("name") - if name != "" { - fmt.Printf("Hello %s.\n", name) // prints "Hello alice.". - } - - // 2. Find by loop. - for _, param := range params { - if param.Name == "name" { - fmt.Printf("Hello %s.\n", name) // prints "Hello alice.". - } - } -} -``` - -## URL patterns - -Denco's route matching strategy is "most nearly matching". - -When routes `/:name` and `/alice` have been built, URI `/alice` matches the route `/alice`, not `/:name`. -Because URI `/alice` is more match with the route `/alice` than `/:name`. - -For more example, when routes below have been built: - -``` -/user/alice -/user/:name -/user/:name/:id -/user/alice/:id -/user/:id/bob -``` - -Routes matching are: - -``` -/user/alice => "/user/alice" (no match with "/user/:name") -/user/bob => "/user/:name" -/user/naoina/1 => "/user/:name/1" -/user/alice/1 => "/user/alice/:id" (no match with "/user/:name/:id") -/user/1/bob => "/user/:id/bob" (no match with "/user/:name/:id") -/user/alice/bob => "/user/alice/:id" (no match with "/user/:name/:id" and "/user/:id/bob") -``` - -## Limitation - -Denco has some limitations below. - -* Number of param records (such as `/:name`) must be less than 2^22 -* Number of elements of internal slice must be less than 2^22 - -## Benchmarks - - cd $GOPATH/github.com/go-openapi/runtime/middleware/denco - go test -bench . -benchmem - -## License - -Denco is licensed under the MIT License. -# runtime [![Build Status](https://github.com/go-openapi/runtime/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/runtime/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/runtime/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/runtime) - -[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) -[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/runtime/master/LICENSE) -[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/runtime.svg)](https://pkg.go.dev/github.com/go-openapi/runtime) -[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/runtime)](https://goreportcard.com/report/github.com/go-openapi/runtime) - -# go OpenAPI toolkit runtime - -The runtime component for use in code generation or as untyped usage. -# Contributor Covenant Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. - -## Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at ivan+abuse@flanders.co.nz. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] - -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ -## Contribution Guidelines - -### Pull requests are always welcome - -We are always thrilled to receive pull requests, and do our best to -process them as fast as possible. Not sure if that typo is worth a pull -request? Do it! We will appreciate it. - -If your pull request is not accepted on the first try, don't be -discouraged! If there's a problem with the implementation, hopefully you -received feedback on what to improve. - -We're trying very hard to keep go-swagger lean and focused. We don't want it -to do everything for everybody. This means that we might decide against -incorporating a new feature. However, there might be a way to implement -that feature *on top of* go-swagger. - - -### Conventions - -Fork the repo and make changes on your fork in a feature branch: - -- If it's a bugfix branch, name it XXX-something where XXX is the number of the - issue -- If it's a feature branch, create an enhancement issue to announce your - intentions, and name it XXX-something where XXX is the number of the issue. - -Submit unit tests for your changes. Go has a great test framework built in; use -it! Take a look at existing tests for inspiration. Run the full test suite on -your branch before submitting a pull request. - -Update the documentation when creating or modifying features. Test -your documentation changes for clarity, concision, and correctness, as -well as a clean documentation build. See ``docs/README.md`` for more -information on building the docs and how docs get released. - -Write clean code. Universally formatted code promotes ease of writing, reading, -and maintenance. Always run `gofmt -s -w file.go` on each changed file before -committing your changes. Most editors have plugins that do this automatically. - -Pull requests descriptions should be as clear as possible and include a -reference to all the issues that they address. - -Pull requests must not contain commits from other users or branches. - -Commit messages must start with a capitalized and short summary (max. 50 -chars) written in the imperative, followed by an optional, more detailed -explanatory text which is separated from the summary by an empty line. - -Code review comments may be added to your pull request. Discuss, then make the -suggested modifications and push additional commits to your feature branch. Be -sure to post a comment after pushing. The new commits will show up in the pull -request automatically, but the reviewers will not be notified unless you -comment. - -Before the pull request is merged, make sure that you squash your commits into -logical units of work using `git rebase -i` and `git push -f`. After every -commit the test suite should be passing. Include documentation changes in the -same commit so that a revert would remove all traces of the feature or fix. - -Commits that fix or close an issue should include a reference like `Closes #XXX` -or `Fixes #XXX`, which will automatically close the issue when merged. - -### Sign your work - -The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as an open-source patch. The rules are pretty simple: if you -can certify the below (from -[developercertificate.org](http://developercertificate.org/)): - -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` - -then you just add a line to every git commit message: - - Signed-off-by: Joe Smith - -using your real name (sorry, no pseudonyms or anonymous contributions.) - -You can add the sign off when creating the git commit via `git commit -s`. -# Loads OAI specs [![Build Status](https://github.com/go-openapi/loads/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/loads/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/loads/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/loads) - -[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/loads/master/LICENSE) [![GoDoc](https://godoc.org/github.com/go-openapi/loads?status.svg)](http://godoc.org/github.com/go-openapi/loads) -[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/loads)](https://goreportcard.com/report/github.com/go-openapi/loads) - -Loading of OAI specification documents from local or remote locations. Supports JSON and YAML documents. -# Contributor Covenant Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. - -## Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at ivan+abuse@flanders.co.nz. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] - -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ -## Contribution Guidelines - -### Pull requests are always welcome - -We are always thrilled to receive pull requests, and do our best to -process them as fast as possible. Not sure if that typo is worth a pull -request? Do it! We will appreciate it. - -If your pull request is not accepted on the first try, don't be -discouraged! If there's a problem with the implementation, hopefully you -received feedback on what to improve. - -We're trying very hard to keep go-swagger lean and focused. We don't want it -to do everything for everybody. This means that we might decide against -incorporating a new feature. However, there might be a way to implement -that feature *on top of* go-swagger. - - -### Conventions - -Fork the repo and make changes on your fork in a feature branch: - -- If it's a bugfix branch, name it XXX-something where XXX is the number of the - issue -- If it's a feature branch, create an enhancement issue to announce your - intentions, and name it XXX-something where XXX is the number of the issue. - -Submit unit tests for your changes. Go has a great test framework built in; use -it! Take a look at existing tests for inspiration. Run the full test suite on -your branch before submitting a pull request. - -Update the documentation when creating or modifying features. Test -your documentation changes for clarity, concision, and correctness, as -well as a clean documentation build. See ``docs/README.md`` for more -information on building the docs and how docs get released. - -Write clean code. Universally formatted code promotes ease of writing, reading, -and maintenance. Always run `gofmt -s -w file.go` on each changed file before -committing your changes. Most editors have plugins that do this automatically. - -Pull requests descriptions should be as clear as possible and include a -reference to all the issues that they address. - -Pull requests must not contain commits from other users or branches. - -Commit messages must start with a capitalized and short summary (max. 50 -chars) written in the imperative, followed by an optional, more detailed -explanatory text which is separated from the summary by an empty line. - -Code review comments may be added to your pull request. Discuss, then make the -suggested modifications and push additional commits to your feature branch. Be -sure to post a comment after pushing. The new commits will show up in the pull -request automatically, but the reviewers will not be notified unless you -comment. - -Before the pull request is merged, make sure that you squash your commits into -logical units of work using `git rebase -i` and `git push -f`. After every -commit the test suite should be passing. Include documentation changes in the -same commit so that a revert would remove all traces of the feature or fix. - -Commits that fix or close an issue should include a reference like `Closes #XXX` -or `Fixes #XXX`, which will automatically close the issue when merged. - -### Sign your work - -The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as an open-source patch. The rules are pretty simple: if you -can certify the below (from -[developercertificate.org](http://developercertificate.org/)): - -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` - -then you just add a line to every git commit message: - - Signed-off-by: Joe Smith - -using your real name (sorry, no pseudonyms or anonymous contributions.) - -You can add the sign off when creating the git commit via `git commit -s`. -# OpenAPI analysis [![Build Status](https://github.com/go-openapi/analysis/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/analysis/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/analysis/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/analysis) - -[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) -[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/analysis/master/LICENSE) -[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/analysis.svg)](https://pkg.go.dev/github.com/go-openapi/analysis) -[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/analysis)](https://goreportcard.com/report/github.com/go-openapi/analysis) - - -A foundational library to analyze an OAI specification document for easier reasoning about the content. - -## What's inside? - -* An analyzer providing methods to walk the functional content of a specification -* A spec flattener producing a self-contained document bundle, while preserving `$ref`s -* A spec merger ("mixin") to merge several spec documents into a primary spec -* A spec "fixer" ensuring that response descriptions are non empty - -[Documentation](https://pkg.go.dev/github.com/go-openapi/analysis) - -## FAQ - -* Does this library support OpenAPI 3? - -> No. -> This package currently only supports OpenAPI 2.0 (aka Swagger 2.0). -> There is no plan to make it evolve toward supporting OpenAPI 3.x. -> This [discussion thread](https://github.com/go-openapi/spec/issues/21) relates the full story. -# Contributor Covenant Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. - -## Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at ivan+abuse@flanders.co.nz. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] - -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ -## Contribution Guidelines - -### Pull requests are always welcome - -We are always thrilled to receive pull requests, and do our best to -process them as fast as possible. Not sure if that typo is worth a pull -request? Do it! We will appreciate it. - -If your pull request is not accepted on the first try, don't be -discouraged! If there's a problem with the implementation, hopefully you -received feedback on what to improve. - -We're trying very hard to keep go-swagger lean and focused. We don't want it -to do everything for everybody. This means that we might decide against -incorporating a new feature. However, there might be a way to implement -that feature *on top of* go-swagger. - - -### Conventions - -Fork the repo and make changes on your fork in a feature branch: - -- If it's a bugfix branch, name it XXX-something where XXX is the number of the - issue -- If it's a feature branch, create an enhancement issue to announce your - intentions, and name it XXX-something where XXX is the number of the issue. - -Submit unit tests for your changes. Go has a great test framework built in; use -it! Take a look at existing tests for inspiration. Run the full test suite on -your branch before submitting a pull request. - -Update the documentation when creating or modifying features. Test -your documentation changes for clarity, concision, and correctness, as -well as a clean documentation build. See ``docs/README.md`` for more -information on building the docs and how docs get released. - -Write clean code. Universally formatted code promotes ease of writing, reading, -and maintenance. Always run `gofmt -s -w file.go` on each changed file before -committing your changes. Most editors have plugins that do this automatically. - -Pull requests descriptions should be as clear as possible and include a -reference to all the issues that they address. - -Pull requests must not contain commits from other users or branches. - -Commit messages must start with a capitalized and short summary (max. 50 -chars) written in the imperative, followed by an optional, more detailed -explanatory text which is separated from the summary by an empty line. - -Code review comments may be added to your pull request. Discuss, then make the -suggested modifications and push additional commits to your feature branch. Be -sure to post a comment after pushing. The new commits will show up in the pull -request automatically, but the reviewers will not be notified unless you -comment. - -Before the pull request is merged, make sure that you squash your commits into -logical units of work using `git rebase -i` and `git push -f`. After every -commit the test suite should be passing. Include documentation changes in the -same commit so that a revert would remove all traces of the feature or fix. - -Commits that fix or close an issue should include a reference like `Closes #XXX` -or `Fixes #XXX`, which will automatically close the issue when merged. - -### Sign your work - -The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as an open-source patch. The rules are pretty simple: if you -can certify the below (from -[developercertificate.org](http://developercertificate.org/)): - -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` - -then you just add a line to every git commit message: - - Signed-off-by: Joe Smith - -using your real name (sorry, no pseudonyms or anonymous contributions.) - -You can add the sign off when creating the git commit via `git commit -s`. -# Benchmarking name mangling utilities - -```bash -go test -bench XXX -run XXX -benchtime 30s -``` - -## Benchmarks at b3e7a5386f996177e4808f11acb2aa93a0f660df - -``` -goos: linux -goarch: amd64 -pkg: github.com/go-openapi/swag -cpu: Intel(R) Core(TM) i5-6200U CPU @ 2.30GHz -BenchmarkToXXXName/ToGoName-4 862623 44101 ns/op 10450 B/op 732 allocs/op -BenchmarkToXXXName/ToVarName-4 853656 40728 ns/op 10468 B/op 734 allocs/op -BenchmarkToXXXName/ToFileName-4 1268312 27813 ns/op 9785 B/op 617 allocs/op -BenchmarkToXXXName/ToCommandName-4 1276322 27903 ns/op 9785 B/op 617 allocs/op -BenchmarkToXXXName/ToHumanNameLower-4 895334 40354 ns/op 10472 B/op 731 allocs/op -BenchmarkToXXXName/ToHumanNameTitle-4 882441 40678 ns/op 10566 B/op 749 allocs/op -``` - -## Benchmarks after PR #79 - -~ x10 performance improvement and ~ /100 memory allocations. - -``` -goos: linux -goarch: amd64 -pkg: github.com/go-openapi/swag -cpu: Intel(R) Core(TM) i5-6200U CPU @ 2.30GHz -BenchmarkToXXXName/ToGoName-4 9595830 3991 ns/op 42 B/op 5 allocs/op -BenchmarkToXXXName/ToVarName-4 9194276 3984 ns/op 62 B/op 7 allocs/op -BenchmarkToXXXName/ToFileName-4 17002711 2123 ns/op 147 B/op 7 allocs/op -BenchmarkToXXXName/ToCommandName-4 16772926 2111 ns/op 147 B/op 7 allocs/op -BenchmarkToXXXName/ToHumanNameLower-4 9788331 3749 ns/op 92 B/op 6 allocs/op -BenchmarkToXXXName/ToHumanNameTitle-4 9188260 3941 ns/op 104 B/op 6 allocs/op -``` - -``` -goos: linux -goarch: amd64 -pkg: github.com/go-openapi/swag -cpu: AMD Ryzen 7 5800X 8-Core Processor -BenchmarkToXXXName/ToGoName-16 18527378 1972 ns/op 42 B/op 5 allocs/op -BenchmarkToXXXName/ToVarName-16 15552692 2093 ns/op 62 B/op 7 allocs/op -BenchmarkToXXXName/ToFileName-16 32161176 1117 ns/op 147 B/op 7 allocs/op -BenchmarkToXXXName/ToCommandName-16 32256634 1137 ns/op 147 B/op 7 allocs/op -BenchmarkToXXXName/ToHumanNameLower-16 18599661 1946 ns/op 92 B/op 6 allocs/op -BenchmarkToXXXName/ToHumanNameTitle-16 17581353 2054 ns/op 105 B/op 6 allocs/op -``` - -## Benchmarks at d7d2d1b895f5b6747afaff312dd2a402e69e818b - -go1.24 - -``` -goos: linux -goarch: amd64 -pkg: github.com/go-openapi/swag -cpu: AMD Ryzen 7 5800X 8-Core Processor -BenchmarkToXXXName/ToGoName-16 19757858 1881 ns/op 42 B/op 5 allocs/op -BenchmarkToXXXName/ToVarName-16 17494111 2094 ns/op 74 B/op 7 allocs/op -BenchmarkToXXXName/ToFileName-16 28161226 1492 ns/op 158 B/op 7 allocs/op -BenchmarkToXXXName/ToCommandName-16 23787333 1489 ns/op 158 B/op 7 allocs/op -BenchmarkToXXXName/ToHumanNameLower-16 17537257 2030 ns/op 103 B/op 6 allocs/op -BenchmarkToXXXName/ToHumanNameTitle-16 16977453 2156 ns/op 105 B/op 6 allocs/op -``` - -## Benchmarks after PR #106 - -Moving the scope of everything down to a struct allowed to reduce a bit garbage and pooling. - -On top of that, ToGoName (and thus ToVarName) have been subject to a minor optimization, removing a few allocations. - -Overall timings improve by ~ -10%. - -go1.24 - -``` -goos: linux -goarch: amd64 -pkg: github.com/go-openapi/swag/mangling -cpu: AMD Ryzen 7 5800X 8-Core Processor -BenchmarkToXXXName/ToGoName-16 22496130 1618 ns/op 31 B/op 3 allocs/op -BenchmarkToXXXName/ToVarName-16 22538068 1618 ns/op 33 B/op 3 allocs/op -BenchmarkToXXXName/ToFileName-16 27722977 1236 ns/op 105 B/op 6 allocs/op -BenchmarkToXXXName/ToCommandName-16 27967395 1258 ns/op 105 B/op 6 allocs/op -BenchmarkToXXXName/ToHumanNameLower-16 18587901 1917 ns/op 103 B/op 6 allocs/op -BenchmarkToXXXName/ToHumanNameTitle-16 17193208 2019 ns/op 108 B/op 7 allocs/op -``` -# Swag [![Build Status](https://github.com/go-openapi/swag/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/swag/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/swag/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/swag) - -[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) -[![license](https://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/swag/master/LICENSE) -[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/swag.svg)](https://pkg.go.dev/github.com/go-openapi/swag) -[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/swag)](https://goreportcard.com/report/github.com/go-openapi/swag) - -Package `swag` contains a bunch of helper functions for go-openapi and go-swagger projects. - -You may also use it standalone for your projects. - -> `swag` is one of the foundational building blocks of the go-openapi initiative. -> -> Most repositories in `github.com/go-openapi/...` depend on it in some way. -> So does the CLI tool `github.com/go-swagger/go-swagger`, -> and the code generated by this tool. - -## Contents - -`go-openapi/swag` now exposes a collection of relatively independent modules. - -Here is what is inside: - -* Module `cmdutils` - - * [x] utilities to work with CLIs - -* Module `conv` - - * [x] convert between values and pointers for any types - * [x] convert from string to builtin types (wraps `strconv`) - * [x] require `./typeutils` (test dependency) - -* Module `fileutils` - - * [x] file upload type - * [x] search in path (deprecated) - -* Module `jsonname` - - * [x] infer JSON names from go properties - -* Module `jsonutils` - - * [x] fast json concatenation - * [x] read and write JSON from and to dynamic go data structures - * [x] require `github.com/mailru/easyjson` - -* Module `loading` - - * [x] load from file or http - * [x] require `./yamlutils` - -* Module `mangling` - - * [x] name mangling for go - -* Module `netutils` - - * [x] host, port from address - -* Module `stringutils` - - * [x] search in slice (with case-insensitive) - * [x] split/join query parameters as arrays - -* Module `typeutils` - - * [x] check the zero value for any type - -* Module `yamlutils` - - * [x] converting YAML to JSON - * [x] loading YAML into a dynamic YAML document - * [x] require `./jsonutils` - * [x] require `github.com/mailru/easyjson` - * [x] require `gopkg.in/yaml.v3` - ---- - -The root module `github.com/go-openapi/swag` at the repo level maintains a few -dependencies outside of the standard library: - -* YAML utilities depend on `gopkg.in/yaml.v3` -* JSON utilities `github.com/mailru/easyjson` - -This is not necessarily the case for all sub-modules. - -## Release notes - -### v0.24.0 [Unreleased] - -With this release, we have largely modernized the API of `swag`: - -* The traditional `swag` API is still supported: code that imports `swag` will still - compile and work the same. -* A deprecation notice is published to encourage consumers of this library to adopt - the newer API -* **Deprecation notice** - * configuration through global variables is now deprecated, in favor of options passed as parameters - * all helper functions are moved to more specialized packages, which are exposed as - go modules. Importing such a module would reduce the footprint of dependencies. - * _all_ functions, variables, constants exposed by the deprecated API have now moved, so - that consumers of the new API no longer need to import github.com/go-openapi/swag, but - should import the desired sub-module(s). - -**New with this release**: - -* [x] type converters and pointer to value helpers now support generic types -* [x] name mangling now support pluralized initialisms (issue #46) - Strings like "contact IDs" are now recognized as such a plural form and mangled as a linter would expect. -* [x] performance: small improvements to reduce the overhead of convert/format wrappers (see issues #110, or PR #108) -* [x] performance: name mangling utilities run ~ 10% faster (PR #115) - ---- - -Moving forward, no additional feature will be added to the `swag` API directly. - -However, child modules will continue to evolve or some new ones may be added in the future. - - -#### Note to contributors - -The mono-repo structure comes with some unavoidable extra pains... - -* Testing - -> The usual `go test ./...` command, run from the root of this repo won't work any longer to test all submodules. -> -> Each module constitutes an independant unit of test. So you have to run `go test` inside each module. -> Or you may take a look at how this is achieved by CI -> [here] https://github.com/go-openapi/swag/blob/master/.github/workflows/go-test.yml). -> -> There are also some alternative tricks using `go work`, for local development, if you feel comfortable with -> go workspaces. Perhaps some day, we'll have a `go work test` to run all tests without any hack. - -* Releasing - -> Each module follows its own independant module versioning. -> -> So you have tags like `mangling/v0.24.0`, `fileutils/v0.24.0` etc that are used by `go mod` and `go get` -> to refer to the tagged version of each module specifically. -> -> This means we may release patches etc to each module independently. -> -> We'd like to adopt the rule that modules in this repo would only differ by a patch version -> (e.g. `v0.24.5` vs `v0.24.3`), and we'll level all modules whenever a minor version is introduced. -> -> A script in `./hack` is provided to tag all modules in one go at the same level in one go. - -## Todos, suggestions and plans - -All kinds of contributions are welcome. - -A few ideas: - -* [ ] Complete the split of dependencies to isolate easyjson from the rest -* [ ] Improve mangling utilities (improve readability, support for capitalized words, - better word substitution for non-letter symbols...) -* [ ] Move back to this common shared pot a few of the technical features introduced by go-swagger independently - (e.g. mangle go package names, search package with go modules support, ...) -* [ ] Apply a similar mono-repo approach to go-openapi/strfmt which suffer from similar woes: bloated API, - imposed dependency to some database driver. - -# Contributor Covenant Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. - -## Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at ivan+abuse@flanders.co.nz. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] - -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ -## Contribution Guidelines - -### Pull requests are always welcome - -We are always thrilled to receive pull requests, and do our best to -process them as fast as possible. Not sure if that typo is worth a pull -request? Do it! We will appreciate it. - -If your pull request is not accepted on the first try, don't be -discouraged! If there's a problem with the implementation, hopefully you -received feedback on what to improve. - -We're trying very hard to keep go-swagger lean and focused. We don't want it -to do everything for everybody. This means that we might decide against -incorporating a new feature. However, there might be a way to implement -that feature *on top of* go-swagger. - - -### Conventions - -Fork the repo and make changes on your fork in a feature branch: - -- If it's a bugfix branch, name it XXX-something where XXX is the number of the - issue -- If it's a feature branch, create an enhancement issue to announce your - intentions, and name it XXX-something where XXX is the number of the issue. - -Submit unit tests for your changes. Go has a great test framework built in; use -it! Take a look at existing tests for inspiration. Run the full test suite on -your branch before submitting a pull request. - -Update the documentation when creating or modifying features. Test -your documentation changes for clarity, concision, and correctness, as -well as a clean documentation build. See ``docs/README.md`` for more -information on building the docs and how docs get released. - -Write clean code. Universally formatted code promotes ease of writing, reading, -and maintenance. Always run `gofmt -s -w file.go` on each changed file before -committing your changes. Most editors have plugins that do this automatically. - -Pull requests descriptions should be as clear as possible and include a -reference to all the issues that they address. - -Pull requests must not contain commits from other users or branches. - -Commit messages must start with a capitalized and short summary (max. 50 -chars) written in the imperative, followed by an optional, more detailed -explanatory text which is separated from the summary by an empty line. - -Code review comments may be added to your pull request. Discuss, then make the -suggested modifications and push additional commits to your feature branch. Be -sure to post a comment after pushing. The new commits will show up in the pull -request automatically, but the reviewers will not be notified unless you -comment. - -Before the pull request is merged, make sure that you squash your commits into -logical units of work using `git rebase -i` and `git push -f`. After every -commit the test suite should be passing. Include documentation changes in the -same commit so that a revert would remove all traces of the feature or fix. - -Commits that fix or close an issue should include a reference like `Closes #XXX` -or `Fixes #XXX`, which will automatically close the issue when merged. - -### Sign your work - -The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as an open-source patch. The rules are pretty simple: if you -can certify the below (from -[developercertificate.org](http://developercertificate.org/)): - -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` - -then you just add a line to every git commit message: - - Signed-off-by: Joe Smith - -using your real name (sorry, no pseudonyms or anonymous contributions.) - -You can add the sign off when creating the git commit via `git commit -s`. -# Strfmt [![Build Status](https://github.com/go-openapi/strfmt/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/strfmt/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/strfmt/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/strfmt) -[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) -[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/strfmt/master/LICENSE) -[![GoDoc](https://godoc.org/github.com/go-openapi/strfmt?status.svg)](http://godoc.org/github.com/go-openapi/strfmt) -[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/strfmt)](https://goreportcard.com/report/github.com/go-openapi/strfmt) - -This package exposes a registry of data types to support string formats in the go-openapi toolkit. - -strfmt represents a well known string format such as credit card or email. The go toolkit for OpenAPI specifications knows how to deal with those. - -## Supported data formats -go-openapi/strfmt follows the swagger 2.0 specification with the following formats -defined [here](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types). - -It also provides convenient extensions to go-openapi users. - -- [x] JSON-schema draft 4 formats - - date-time - - email - - hostname - - ipv4 - - ipv6 - - uri -- [x] swagger 2.0 format extensions - - binary - - byte (e.g. base64 encoded string) - - date (e.g. "1970-01-01") - - password -- [x] go-openapi custom format extensions - - bsonobjectid (BSON objectID) - - creditcard - - duration (e.g. "3 weeks", "1ms") - - hexcolor (e.g. "#FFFFFF") - - isbn, isbn10, isbn13 - - mac (e.g "01:02:03:04:05:06") - - rgbcolor (e.g. "rgb(100,100,100)") - - ssn - - uuid, uuid3, uuid4, uuid5 - - cidr (e.g. "192.0.2.1/24", "2001:db8:a0b:12f0::1/32") - - ulid (e.g. "00000PP9HGSBSSDZ1JTEXBJ0PW", [spec](https://github.com/ulid/spec)) - -> NOTE: as the name stands for, this package is intended to support string formatting only. -> It does not provide validation for numerical values with swagger format extension for JSON types "number" or -> "integer" (e.g. float, double, int32...). - -## Type conversion - -All types defined here are stringers and may be converted to strings with `.String()`. -Note that most types defined by this package may be converted directly to string like `string(Email{})`. - -`Date` and `DateTime` may be converted directly to `time.Time` like `time.Time(Time{})`. -Similarly, you can convert `Duration` to `time.Duration` as in `time.Duration(Duration{})` - -## Using pointers - -The `conv` subpackage provides helpers to convert the types to and from pointers, just like `go-openapi/swag` does -with primitive types. - -## Format types -Types defined in strfmt expose marshaling and validation capabilities. - -List of defined types: -- Base64 -- CreditCard -- Date -- DateTime -- Duration -- Email -- HexColor -- Hostname -- IPv4 -- IPv6 -- CIDR -- ISBN -- ISBN10 -- ISBN13 -- MAC -- ObjectId -- Password -- RGBColor -- SSN -- URI -- UUID -- UUID3 -- UUID4 -- UUID5 -- [ULID](https://github.com/ulid/spec) -# Contributor Covenant Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. - -## Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at ivan+abuse@flanders.co.nz. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] - -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ -## Contribution Guidelines - -### Pull requests are always welcome - -We are always thrilled to receive pull requests, and do our best to -process them as fast as possible. Not sure if that typo is worth a pull -request? Do it! We will appreciate it. - -If your pull request is not accepted on the first try, don't be -discouraged! If there's a problem with the implementation, hopefully you -received feedback on what to improve. - -We're trying very hard to keep go-swagger lean and focused. We don't want it -to do everything for everybody. This means that we might decide against -incorporating a new feature. However, there might be a way to implement -that feature *on top of* go-swagger. - - -### Conventions - -Fork the repo and make changes on your fork in a feature branch: - -- If it's a bugfix branch, name it XXX-something where XXX is the number of the - issue -- If it's a feature branch, create an enhancement issue to announce your - intentions, and name it XXX-something where XXX is the number of the issue. - -Submit unit tests for your changes. Go has a great test framework built in; use -it! Take a look at existing tests for inspiration. Run the full test suite on -your branch before submitting a pull request. - -Update the documentation when creating or modifying features. Test -your documentation changes for clarity, concision, and correctness, as -well as a clean documentation build. See ``docs/README.md`` for more -information on building the docs and how docs get released. - -Write clean code. Universally formatted code promotes ease of writing, reading, -and maintenance. Always run `gofmt -s -w file.go` on each changed file before -committing your changes. Most editors have plugins that do this automatically. - -Pull requests descriptions should be as clear as possible and include a -reference to all the issues that they address. - -Pull requests must not contain commits from other users or branches. - -Commit messages must start with a capitalized and short summary (max. 50 -chars) written in the imperative, followed by an optional, more detailed -explanatory text which is separated from the summary by an empty line. - -Code review comments may be added to your pull request. Discuss, then make the -suggested modifications and push additional commits to your feature branch. Be -sure to post a comment after pushing. The new commits will show up in the pull -request automatically, but the reviewers will not be notified unless you -comment. - -Before the pull request is merged, make sure that you squash your commits into -logical units of work using `git rebase -i` and `git push -f`. After every -commit the test suite should be passing. Include documentation changes in the -same commit so that a revert would remove all traces of the feature or fix. - -Commits that fix or close an issue should include a reference like `Closes #XXX` -or `Fixes #XXX`, which will automatically close the issue when merged. - -### Sign your work - -The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as an open-source patch. The rules are pretty simple: if you -can certify the below (from -[developercertificate.org](http://developercertificate.org/)): - -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` - -then you just add a line to every git commit message: - - Signed-off-by: Joe Smith - -using your real name (sorry, no pseudonyms or anonymous contributions.) - -You can add the sign off when creating the git commit via `git commit -s`. -# blag blah -# blag blah - -Ordered list: - - 1. xyz - 2. abc - -First list: - - - a - - b - - c - -Second list: - - * A - * B - * C - -Another Ordered list: - - 0. xyz - 0. abc -# OpenAPI errors [![Build Status](https://github.com/go-openapi/errors/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/errors/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/errors/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/errors) - -[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) -[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/errors/master/LICENSE) -[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/errors.svg)](https://pkg.go.dev/github.com/go-openapi/errors) -[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/errors)](https://goreportcard.com/report/github.com/go-openapi/errors) - -Shared errors and error interface used throughout the various libraries found in the go-openapi toolkit. -# Contributor Covenant Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. - -## Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at ivan+abuse@flanders.co.nz. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] - -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ -## Contribution Guidelines - -### Pull requests are always welcome - -We are always thrilled to receive pull requests, and do our best to -process them as fast as possible. Not sure if that typo is worth a pull -request? Do it! We will appreciate it. - -If your pull request is not accepted on the first try, don't be -discouraged! If there's a problem with the implementation, hopefully you -received feedback on what to improve. - -We're trying very hard to keep go-swagger lean and focused. We don't want it -to do everything for everybody. This means that we might decide against -incorporating a new feature. However, there might be a way to implement -that feature *on top of* go-swagger. - - -### Conventions - -Fork the repo and make changes on your fork in a feature branch: - -- If it's a bugfix branch, name it XXX-something where XXX is the number of the - issue -- If it's a feature branch, create an enhancement issue to announce your - intentions, and name it XXX-something where XXX is the number of the issue. - -Submit unit tests for your changes. Go has a great test framework built in; use -it! Take a look at existing tests for inspiration. Run the full test suite on -your branch before submitting a pull request. - -Update the documentation when creating or modifying features. Test -your documentation changes for clarity, concision, and correctness, as -well as a clean documentation build. See ``docs/README.md`` for more -information on building the docs and how docs get released. - -Write clean code. Universally formatted code promotes ease of writing, reading, -and maintenance. Always run `gofmt -s -w file.go` on each changed file before -committing your changes. Most editors have plugins that do this automatically. - -Pull requests descriptions should be as clear as possible and include a -reference to all the issues that they address. - -Pull requests must not contain commits from other users or branches. - -Commit messages must start with a capitalized and short summary (max. 50 -chars) written in the imperative, followed by an optional, more detailed -explanatory text which is separated from the summary by an empty line. - -Code review comments may be added to your pull request. Discuss, then make the -suggested modifications and push additional commits to your feature branch. Be -sure to post a comment after pushing. The new commits will show up in the pull -request automatically, but the reviewers will not be notified unless you -comment. - -Before the pull request is merged, make sure that you squash your commits into -logical units of work using `git rebase -i` and `git push -f`. After every -commit the test suite should be passing. Include documentation changes in the -same commit so that a revert would remove all traces of the feature or fix. - -Commits that fix or close an issue should include a reference like `Closes #XXX` -or `Fixes #XXX`, which will automatically close the issue when merged. - -### Sign your work - -The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as an open-source patch. The rules are pretty simple: if you -can certify the below (from -[developercertificate.org](http://developercertificate.org/)): - -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` - -then you just add a line to every git commit message: - - Signed-off-by: Joe Smith - -using your real name (sorry, no pseudonyms or anonymous contributions.) - -You can add the sign off when creating the git commit via `git commit -s`. -Evaluate: - -* markdownlint - * assessment: go - * used by opentelemetry/opentelemetry-go - * packaged as github action -* misspell -* spellcheck -* govulncheck -* [x] godoc-lint: - * assessment: no go - * too simplistic: no real value added - * not integrated into golangci's suite of linters - * no packaged github action -

dfkjfkfj

- - -ERGGLGKLK -========== -this is a title -# .github -Default github settings for go-openapi repositories ---- -name: '❓ Question' -about: I have a question about this project -title: '' -labels: [question] -assignees: '' - ---- - -**Question** - - -**Additional context** - ---- -name: '➕ Feature request' -about: Suggest an idea for this project -title: '' -labels: [enhancement] -assignees: '' - ---- - -**Is your feature request related to a problem? Please describe.** - - -**Describe the solution you'd like** - - -**Describe alternatives you've considered** - - -**Additional context** - ---- -name: '🐞 Bug report' -about: Create a report to help us make go-openapi a great project -title: '' -labels: [bug] -assignees: '' - ---- - -**Describe the bug** - - -**Steps to Reproduce** - - - - -**Expected behavior** - - -**Actual behavior** - - -**Environment** - - -**Additional context** - -## Change type - -Please select: 🆕 New feature or enhancement|🔧 Bug fix'|📃 Documentation update - -## Short description - - -## Fixes - - -## Full description - - - - -## Checklist - - - -* [ ] I have signed all my commits with my name and email (see [DCO](https://github.com/apps/dco). **This does not require a PGP-signed commit** -* [ ] I have rebased and squashed my work, so only one commit remains -* [ ] I have added tests to cover my changes. -* [ ] I have properly enriched go doc comments in code. -* [ ] I have properly documented any breaking change. -## Change type: 📃 Documentation update - -## Short description - - -## Fixes - - -## Checklist - - - -* [ ] I have signed all my commits with my name and email (see [DCO](https://github.com/apps/dco). **This does not require a PGP-signed commit** -* [ ] I have rebased and squashed my work, so only one commit remains -* [ ] I have signed all my commits with my name and email (see DCO: https://github.com/apps/dco). **This does not require a PGP-signed commit** -* [ ] I have rebased and squash my work, so only one commit remains -* [ ] I have only modified comments in code or markdown files -## Change type: 🆕 New feature or enhancement - -## Short description - - -## Fixes - - -## Checklist - - - -* [ ] I have signed all my commits with my name and email (see [DCO](https://github.com/apps/dco). **This does not require a PGP-signed commit** -* [ ] I have rebased and squashed my work, so only one commit remains -* [ ] I have added tests to cover my changes. -* [ ] I have properly enriched go doc comments in code. -* [ ] I have properly documented any breaking change. -## Change type: 🔧 Bug fix - -## Short description - - -## Fixes - - -## Full description - - - - -## Checklist - - - -* [ ] I have signed all my commits with my name and email (see [DCO](https://github.com/apps/dco). **This does not require a PGP-signed commit** -* [ ] I have rebased and squashed my work, so only one commit remains -* [ ] I have added tests to cover my changes. -* [ ] I have made sure that my code remains portable -* [ ] I have properly enriched go doc comments in code. -* [ ] I have properly documented any breaking change. -# OpenAPI initiative random data generator [![Build Status](https://travis-ci.org/go-openapi/stubs.svg?branch=master)](https://travis-ci.org/go-openapi/stubs) [![codecov](https://codecov.io/gh/go-openapi/stubs/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/stubs) [![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) - -[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/stubs/master/LICENSE) [![GoDoc](https://godoc.org/github.com/go-openapi/stubs?status.svg)](http://godoc.org/github.com/go-openapi/stubs) - - -A library to generate random data for a swagger specification. -This is a building block for generating stubs for your API as well as tests. -# Contributor Covenant Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. - -## Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at ivan+abuse@flanders.co.nz. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] - -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ -# Stubs design - -The goal of this library is to be able to generate somewhat good looking random data for structures defined in an openapi or jsonschema document. -These can be used to provide an api with stubs so that you can verify valid and invalid request/responses without an actually meaningful implementation. -Some areas where this is useful are collaboration between different teams so that all teams can do work without having to wait on the delivery of the completed implementation of the API. -A second area where this is obviously useful is for doing automated tests and filling up datastructures for use in those tests. - - -In the openapi 2.0 specification there are 2 families of types that can be used as targets for a random data generator. - -1. Path Item related types - 1. Non-Schema Parameters - 2. Response headers - 3. Collection Items on parameters or headers -2. Schemas - -These 2 families warrant slightly different strategies for getting the necessary parameters for a datagenerator. - -## Functionality - -To generate meaningful random data the library looks at the schema and based on properties for that schema it picks an appropriate random value generator. -This means that when it is generating a string for an object property that represents a first name it should pick a data generator that generates first names. -Similarly should a property be called city it should generate a city name. - -It's possible that the validity of a particular property is dependent on the value of another property, for example a creation date is typically never larger than a modified date. - -A data generator for a schema should be able to generate valid and invalid data, ideally there is control for specifying the value is invalid for a particular validation. This will help in tests to validate error codes - -## How does it work - -The main components in this library are a registry of datagenerators so they are addressable by keys, aliases for those keys to aid with inferring which datagenerator to use. -And of course a value generator, which will generate either a valid or an invalid value. - -In the openapi API document and in a json schema document there is a vendor extension that can be used to customize the generation process. - -### Value generator function - -There are 2 types of data generators but they both have the same function signature. -There are value generators and there are composite value generators. - -* A value generator generates a single value for a simple type. -* A composite generator generates a value that is built out of one or more generators eg. object schemas with properties. - -The signature for the value generator is: - -```go -type ValueGenerator func(GeneratorOpts) (interface{}, error) -``` - -A value generator is the innermost component in the library and the arguments to the function are used to configure the generator. -The generation process for a generator is configured through a GeneratorOpts interface. - -### GeneratorOpts interface - -The generator options describe the type and potentially the format for the value that needs to be generated. -In addition to the type information it also captures the field name or definition name of the value that needs to be generated. - -### StubMode - -The stubmode bitmask allows for configuring which validations should fail for a given value generator. - -### Generator - -The generator is the main entry point for the library and its Generate method is what will generate the random value for the descriptor. -# Use cases for stubs - -The stubs package is intended to support the following use cases: - -1. Generate unit test cases for code generated by go-swagger, especially validation code -2. Generate test cases for API servers and clients -3. Generate realistic examples - -## Supported swagger 2.0 constructs - -- parameter -- header -- response -- schema, including support for: - - [] AllOf - - [] Not - - [] additionalProperties - - [] patternProperties - - [] additionalItems - -Formated strings and numbers support go-openapi/strfmt formats, including: - - [] binary (strfmt.Base64) - - [] bsonobjectid - -The "file" datatype is not supported at the moment. - -The generation assumes the provide swagger spec is valid. - -Warnings regarding test case (2): -- stubs is not concerned about security definitions and credentials -- stubs generates values independently for each parameter, or response: it does not know about consistent sets of values beyond validation constraints, let alone - proper chaining of request with responses. - -## Sample applications for stubs - -- process a spec to include examples -- generate fixtures for codegen unit testing -- generate fixtures for API server benchmarking -- ... - -# Reproducible stubs - -Generated stubs may be regenerated using the same initial seed. - -There are two seeding modes to run the stubs generator: - -- AutoSeed: reseeds itself based on current timestamp -- SetSeed: generation occurs with a single seed, provided by the caller - -The package uses a default seeder to carry on this task. Alternate seeders might be provided. - -This also allows for unit testing this very package... - -# Setting generation goals - -Goals select the general use case and allow for fine tuning of the sample generation. - -We use GenerateMode and StubMode flags to define goals. - -Stubmode is used to tune individually every single generated value. - -GenerateMode sets general directives and may define StubMode autonomously according to the generation goal. - -## GenerateMode - -target: -- unitTest: any value value may be produced, not necessarily a realistic definevalue. - By default in the UnitTest mode, non-formated strings are loren ipsums, numbers, dates and times may be very small or very large -- examples: the generator attempts to figure out realistic values to be used as examples - -GenerateMode accepts arguments to further specify the expected generation: - -args: -- valid: all generated values are valid. This is the default. - - count: number of samples to be generated. May be zero to get only default, examples, edge cases or validation checks. Default is 1. -- invalid: all generated values are invalid, with failures chosen at random. - - count: number of samples to be generated. Default is 1. -- skipTilting: tilting rules are omitted (only applies to invalid values). Default is true in unit test mode and false in example mode. -- skipFuzzying: fuzzying rules are omitted -- withTilting: add tilted invalid values, with failures chosen at random. This forces a tilting strategy on a new set of values. - - count: number of tilted samples to be generated. Default is 1. -- withValidationCheck: for each validation, an invalid value against this validation is generated (e.g. if min and max are specified, we have one value below min and one value above max) - - count: this sets a limit on the count of generated values. If you have n validations, that makes n generated values. With the limit set, validations are checked width-first (outermost validations come first) -- withAllValidationChecks: all combinations of failed validations are generated. This includes one valid value and single failure from withValidation. - - count: this sets a limit on the count of generated values. If you have n validations, that makes 2^n generated values, which may raise quickly when nesting schema structures. With the limit set, validations are checked width-first (outermost validations come first) -- withDefault: add default value to sample values (not included in "count"). This simulates a user providing exactly the same value as the default. Since defaults may be set at different levels of the structure, a new value is generated for each applicable default. -- withExample: add example value to sample values (not included in "count"), whenever applicable. Examples are assumed valid, but may be invalid. - - tiltDefault: constructs invalid values by tilting default - - tiltExample: constructs invalid values by tilting examples - - count: number of title -- withEdgeCase: - - standard: standard preconfigured edge cases (e.g. boundary value for min constraint with boundary included, Feb 29th dates for date types, ...) - - value: a customizable value added as an edge case. May be any value, array or object. Severa values may be specified. -- max: an upper limit on number generation (floats, ints, ...). By default, the full range of the data type is used. -- min: a lower limit on number generation. -- precision: rounding specification for floats -- multipleOf: a multiple specification for numbers -- length: - - on string values: an upper limit on string size, to avoid long texts being unwittingly generated - - on array values: an upper limit on the number of generated items - - on additionalProperties: an upper limit on the number of generated additionalProperties - - on patternProperties: an upper limit on the number of generated patternProperties -- words: a limit on the number of words in generated texts, paragraphs and sentences -- lang: specifies the target language(s) for strings and text. - - [lang] - - all: special value to tell the generator to pick text at random from all supported languages - -This sets an overall target for all generations. For every single spec object, you may hint further and override global settings on a case by case basis. - -# Hinting - -The `x-datagen` extension may be used in the swagger spec to hint the stubs generator. - -Examples: -``` -parameters: - phone: - in: query - required: true - type: string - x-datagen: - name: mobile -``` -will generate a mobile phone number for query parameter "phone". - -``` -parameters: - price: - in: query - required: true - type: string - x-datagen: - name: float -``` -will generate float numbers for the price parameter. -It might be not realistic to have 3.1344344E35 as a price, but it is a valid value... - -`x-datagen` accepts args to further hint the generator. -All Args accepted by GenerateMode or StubMode may be used here to locally override generation options. - -Example: -``` -parameters: - vat: - in: query - required: true - type: number - x-datagen: - args: - min: 100 - max: 10000 - -``` -will generate floats between 100 and 10000. -Again, it might not be realistic to have prices such as 503.14561434566... - -Some generators are already configured to suit some targeted usage. - -Example: -``` -parameters: - price: - in: query - required: true - type: string - x-datagen: - name: small-amounts -``` -and you get more realistic values like 3.23, 104.30... - -## x-datagen args - -- name: overrides the generator's name - -Supported args, not already mentioned in the GenerateMode section: -- args: - -# Fuzzying - -The generation takes basic decisions based on type and available validation constraints. -Obviously, this does not work well when the goal is to generate realistic samples for your data. -Of course, everyhing may be fine-tuned by using the x-datagen extension. -But this is tedious work on large specs. - -We introduce fuzzying as a way to carry on some of the guesswork when deciding which kind of fake value would best match expectations. -Fuzzying relies on names, titles and description to look for recognizable keywords, then elects an adequate random generator. - -Examples for the above samples: -- with name "price", the fuzzying guesses that it is not some arbitrary float to be generated, but a decimal between 0 and 1,000,000 (max overrides this limit). -- with a description such as "The item price expressed in USD. Items are sold at a low price", fuzzying rules should guess that we want to generate small-amount values (so between 0 and 1,000). - -Fuzzying also works for non-strings data: -- a date field named "birthday" would hint toward the birthdate value generator (hence dates are not in the future and only in a recent past) -- a datetime named "timestamp" or described as "The update date" would generate a recent datetime value. Further, edge cases with this guess would add 01/01/1970 to the generated value - -# Tilting - -Tilting is a strategy to generate invalid values, by tilting a valid value just enough so it becomes invalid. -This generates interesting test cases since values are supposed to be "almost" valid but actually are not. - -Tilting strategies depend on validations. - -Examples: -- tilting on max will generate a value at or slightly above the lowest invalid value -- tilting on regexp will change the smallest number of characters in a string so the regexp no more matches -- tilting on enum will slightly modify a valid value and make it invalid -- ... - -Options skipTilting and withTilting tune the generator behavior regarding tilting. -# gojsonpointer [![Build Status](https://github.com/go-openapi/jsonpointer/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/jsonpointer/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/jsonpointer/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/jsonpointer) - -[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) -[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/jsonpointer/master/LICENSE) -[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/jsonpointer.svg)](https://pkg.go.dev/github.com/go-openapi/jsonpointer) -[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/jsonpointer)](https://goreportcard.com/report/github.com/go-openapi/jsonpointer) - -An implementation of JSON Pointer - Go language - -## Status -Completed YES - -Tested YES - -## References -http://tools.ietf.org/html/draft-ietf-appsawg-json-pointer-07 - -### Note -The 4.Evaluation part of the previous reference, starting with 'If the currently referenced value is a JSON array, the reference token MUST contain either...' is not implemented. -# Contributor Covenant Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. - -## Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at ivan+abuse@flanders.co.nz. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] - -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ -## Contribution Guidelines - -### Pull requests are always welcome - -We are always thrilled to receive pull requests, and do our best to -process them as fast as possible. Not sure if that typo is worth a pull -request? Do it! We will appreciate it. - -If your pull request is not accepted on the first try, don't be -discouraged! If there's a problem with the implementation, hopefully you -received feedback on what to improve. - -We're trying very hard to keep go-swagger lean and focused. We don't want it -to do everything for everybody. This means that we might decide against -incorporating a new feature. However, there might be a way to implement -that feature *on top of* go-swagger. - - -### Conventions - -Fork the repo and make changes on your fork in a feature branch: - -- If it's a bugfix branch, name it XXX-something where XXX is the number of the - issue -- If it's a feature branch, create an enhancement issue to announce your - intentions, and name it XXX-something where XXX is the number of the issue. - -Submit unit tests for your changes. Go has a great test framework built in; use -it! Take a look at existing tests for inspiration. Run the full test suite on -your branch before submitting a pull request. - -Update the documentation when creating or modifying features. Test -your documentation changes for clarity, concision, and correctness, as -well as a clean documentation build. See ``docs/README.md`` for more -information on building the docs and how docs get released. - -Write clean code. Universally formatted code promotes ease of writing, reading, -and maintenance. Always run `gofmt -s -w file.go` on each changed file before -committing your changes. Most editors have plugins that do this automatically. - -Pull requests descriptions should be as clear as possible and include a -reference to all the issues that they address. - -Pull requests must not contain commits from other users or branches. - -Commit messages must start with a capitalized and short summary (max. 50 -chars) written in the imperative, followed by an optional, more detailed -explanatory text which is separated from the summary by an empty line. - -Code review comments may be added to your pull request. Discuss, then make the -suggested modifications and push additional commits to your feature branch. Be -sure to post a comment after pushing. The new commits will show up in the pull -request automatically, but the reviewers will not be notified unless you -comment. - -Before the pull request is merged, make sure that you squash your commits into -logical units of work using `git rebase -i` and `git push -f`. After every -commit the test suite should be passing. Include documentation changes in the -same commit so that a revert would remove all traces of the feature or fix. - -Commits that fix or close an issue should include a reference like `Closes #XXX` -or `Fixes #XXX`, which will automatically close the issue when merged. - -### Sign your work - -The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as an open-source patch. The rules are pretty simple: if you -can certify the below (from -[developercertificate.org](http://developercertificate.org/)): - -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` - -then you just add a line to every git commit message: - - Signed-off-by: Joe Smith - -using your real name (sorry, no pseudonyms or anonymous contributions.) - -You can add the sign off when creating the git commit via `git commit -s`. From d74e411ab4edc12106bb13c02d707219453f1200 Mon Sep 17 00:00:00 2001 From: Frederic BIDON Date: Sun, 31 Aug 2025 11:16:52 +0200 Subject: [PATCH 23/28] more wordlist Signed-off-by: Frederic BIDON --- .github/.wordlist.txt | 2 ++ .github/workflows/doc-update.yml | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/.wordlist.txt b/.github/.wordlist.txt index f6d9f97..fab8e7c 100644 --- a/.github/.wordlist.txt +++ b/.github/.wordlist.txt @@ -82,6 +82,8 @@ marshaling mixin oai openapi +rebase +rebased repo repos schema diff --git a/.github/workflows/doc-update.yml b/.github/workflows/doc-update.yml index 25f9749..43336f3 100644 --- a/.github/workflows/doc-update.yml +++ b/.github/workflows/doc-update.yml @@ -430,7 +430,7 @@ jobs: "text": ${{ toJSON(needs.markdown-spelling.outputs.report) }} } template-text: | - ### ${{ env.spelling_comment_title }} + ### ${{ env.spellcheck_comment_title }} Some mispelled words were detected in the modified .md files. ⚠ī¸ From e5d8f1ca5b00bd8a9ca288805d815da595761817 Mon Sep 17 00:00:00 2001 From: Frederic BIDON Date: Sun, 31 Aug 2025 11:23:31 +0200 Subject: [PATCH 24/28] fixed checkout on pr head Signed-off-by: Frederic BIDON --- .github/workflows/doc-update.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/doc-update.yml b/.github/workflows/doc-update.yml index 43336f3..f7c8c67 100644 --- a/.github/workflows/doc-update.yml +++ b/.github/workflows/doc-update.yml @@ -153,6 +153,8 @@ jobs: report: ${{ steps.report-exists.outputs.report }} steps: - uses: actions/checkout@v5 + with: + ref: ${{ github.event.pull_request.head.sha }} - name: Checkout spellcheck config uses: actions/checkout@v5 From df466a80b14560e26cb45aa9ca23f94e15b64fed Mon Sep 17 00:00:00 2001 From: Frederic BIDON Date: Sun, 31 Aug 2025 17:25:22 +0200 Subject: [PATCH 25/28] pre-processed spellcheck output Signed-off-by: Frederic BIDON --- .github/workflows/doc-update.yml | 25 ++++++++++++- .github/workflows/filter.sed | 60 ++++++++++++++++++++++++++++++++ .github/workflows/merge.jq | 4 +++ 3 files changed, 88 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/filter.sed create mode 100644 .github/workflows/merge.jq diff --git a/.github/workflows/doc-update.yml b/.github/workflows/doc-update.yml index f7c8c67..8cde395 100644 --- a/.github/workflows/doc-update.yml +++ b/.github/workflows/doc-update.yml @@ -25,6 +25,7 @@ name: doc update check # * [ ] should be able to retrieve config files and dictionary from the called ref, not master. # * [ ] should be able to merge config files and dictionary with local definitions on target repo. # * [ ] should be able to work on diff +# * [ ] should format the output of spellcheck report on: workflow_call: @@ -122,6 +123,7 @@ jobs: if: ${{ steps.markdownlint.outcome != 'success' && hashFiles(env.lintreport) != '' }} id: report-exists run: | + # summarizes a bit the output from spellcheck echo 'report<> $GITHUB_OUTPUT cat ${{ env.lintreport }}|sed -e '$a\' >> $GITHUB_OUTPUT echo 'EOF' >> $GITHUB_OUTPUT @@ -423,13 +425,33 @@ jobs: reactions: ${{ steps.notify_spelling_report.outputs.reactions }} runs-on: ubuntu-latest steps: + - name: Pre-process spellcheck report + id: preprocess + env: + MSG: ${{ needs.markdown-spelling.outputs.report }} + SED_CMD: .github/workflows/filter.sed # a sed script to parse and reformat the spellcheck report + JQ_CMD: .github/workflows/merge.jq # a jq script to dedupe spellcheck reports by file + TMPFILE: /tmp/spellcheck-report.txt + run: | + export MSG + printenv MSG > "${TMPFILE}" + # produces a JSON object: + # { + # "file.md": [ mispelled word [, ...]] + # } + cat "${TMPFILE}" | sed -n -f "${SED_CMD}" | jq -s "${JQ_CMD}" > /tmp/preprocessed.txt + + echo 'report<> $GITHUB_OUTPUT + cat /tmp/preprocessed.txt|sed -e '$a\' >> $GITHUB_OUTPUT + echo 'EOF' >> $GITHUB_OUTPUT + - name: Format PR comment id: comment_formatter uses: skills/action-text-variables@v3 with: template-vars: > { - "text": ${{ toJSON(needs.markdown-spelling.outputs.report) }} + "text": ${{ steps.preprocess.outputs.report) }} } template-text: | ### ${{ env.spellcheck_comment_title }} @@ -442,6 +464,7 @@ jobs:
``` + ### TODO: range json {{ text }} ``` diff --git a/.github/workflows/filter.sed b/.github/workflows/filter.sed new file mode 100644 index 0000000..3445b3b --- /dev/null +++ b/.github/workflows/filter.sed @@ -0,0 +1,60 @@ +:scan_input { + # main scanner loop, looking for "Misspelled words:" entries + /^Misspelled words:/,/^-\{5,\}/ { + /^<html\(attribute\|content\)>\;/ { + # Extract the file name + # TODO: be less strict here + s/^<html\(attribute\|content\)>\;\s\+\(.\+\.md\):.*$/"\2": [/ + h + n # skip current match + n # skip next line + + # go decode a section of single words, enclosed between "=====..." lines + b parse_section + } + + n + + b scan_input + } +} + +# Back to main loop (cycles) +d + +:parse_section { + :word /^[^-]/ { + # Append words to the previous line + # Trim space around words + s/\s\+//g + # Quote word + s/^/"/ + s/$/"/ + + # Add comma separator + s/$/, / + H + n + + b word + } + + /^-\{5,\}$/ { + # Print the collected words as a comma-separated array of words + x + + s/^/{/g + s/\n/ /g + s/\s\+/ /g + s/\s\+$//g + s/\(,\s*\)\?$/ ]/ + s/$/}/g + + p + + # Start a new cycle + d + } +} + +d diff --git a/.github/workflows/merge.jq b/.github/workflows/merge.jq new file mode 100644 index 0000000..cd63ab5 --- /dev/null +++ b/.github/workflows/merge.jq @@ -0,0 +1,4 @@ +reduce (.[] | to_entries | .[]) as {$key, $value} ( + {} ; + .[$key] += $value +) | .[] |= unique From dc5c5aa562c8ff86bf141045b468b909b01e9f15 Mon Sep 17 00:00:00 2001 From: Frederic BIDON Date: Mon, 17 Nov 2025 23:24:03 +0100 Subject: [PATCH 26/28] ci: backported workflows & docs from go-openapi/jsonpoint to the common pot Signed-off-by: Frederic BIDON --- .github/CONTRIBUTING.md | 247 ++++++++---- .github/DCO.md | 40 ++ .github/all-mispelled.txt | 93 ----- .github/workflows/auto-merge.yml | 67 +++- .github/workflows/codeql.yml | 34 ++ .github/workflows/contributors.yml | 45 +++ .github/workflows/doc-update.yml | 142 +++---- .github/workflows/go-test.yml | 422 ++++++++++++++------- .github/workflows/local-auto-merge.yml | 10 +- .github/workflows/local-codeql.yml | 22 ++ .github/workflows/local-contributors.yml | 18 + .github/workflows/local-go-test.yml | 6 +- .github/workflows/local-release.yml | 16 + .github/workflows/local-scanner.yml | 18 + .github/workflows/release.yml | 56 +++ .github/workflows/scanner.yml | 65 ++++ .github/workflows/{ => scripts}/filter.sed | 0 .github/workflows/{ => scripts}/merge.jq | 0 README.md | 88 ++++- SECURITY.md | 19 + config-templates/.cliff.toml | 181 +++++++++ config-templates/.editorconfig | 26 ++ config-templates/.golangci.yml | 66 ++++ doc-templates/.github/CONTRIBUTING.md | 214 +++++++++++ doc-templates/.github/DCO.md | 40 ++ doc-templates/CODE_OF_CONDUCT.md | 74 ++++ doc-templates/README.md | 89 +++++ doc-templates/SECURITY.md | 19 + doc-templates/docs/MAINTAINERS.md | 157 ++++++++ doc-templates/docs/STYLE.md | 83 ++++ doc/README.md | 3 - docs/README.md | 5 + go.mod | 10 +- go.sum | 12 +- sample/pkg/pkg_test.go | 2 +- sample/sample_test.go | 2 +- 36 files changed, 1952 insertions(+), 439 deletions(-) create mode 100644 .github/DCO.md delete mode 100644 .github/all-mispelled.txt create mode 100644 .github/workflows/codeql.yml create mode 100644 .github/workflows/contributors.yml create mode 100644 .github/workflows/local-codeql.yml create mode 100644 .github/workflows/local-contributors.yml create mode 100644 .github/workflows/local-release.yml create mode 100644 .github/workflows/local-scanner.yml create mode 100644 .github/workflows/release.yml create mode 100644 .github/workflows/scanner.yml rename .github/workflows/{ => scripts}/filter.sed (100%) rename .github/workflows/{ => scripts}/merge.jq (100%) create mode 100644 SECURITY.md create mode 100644 config-templates/.cliff.toml create mode 100644 config-templates/.editorconfig create mode 100644 config-templates/.golangci.yml create mode 100644 doc-templates/.github/CONTRIBUTING.md create mode 100644 doc-templates/.github/DCO.md create mode 100644 doc-templates/CODE_OF_CONDUCT.md create mode 100644 doc-templates/README.md create mode 100644 doc-templates/SECURITY.md create mode 100644 doc-templates/docs/MAINTAINERS.md create mode 100644 doc-templates/docs/STYLE.md delete mode 100644 doc/README.md create mode 100644 docs/README.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 7dea424..b02b363 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,114 +1,211 @@ ## Contribution Guidelines +You'll find below general guidelines, which mostly correspond to standard practices for open sourced repositories. + +>**TL;DR** +> +> If you're already an experience go developer on github, then you should just feel at home with us +> and you may well skip the rest of this document. +> +> You'll essentially find the usual guideline for a go library project on github. + +These guidelines are general to all libraries published on github by the `go-openapi` organization. + +You'll find more detailed (or repo-specific) instructions in the [maintainer's docs](../docs). + +## How can I contribute? + +There are many ways in which you can contribute. Here are a few ideas: + + * Reporting Issues / Bugs + * Suggesting Improvements + * Code + * bug fixes and new features that are within the main project scope + * improving test coverage + * addressing code quality issues + * Documentation + * Art work that makes the project look great + +## Questions & issues + +### Asking questions + +You may inquire about anything about this library by reporting a "Question" issue on github. + +### Reporting issues + +Reporting a problem with our libraries _is_ a valuable contribution. + +You can do this on the github issues page of this repository. + +Please be as specific as possible when describing your issue. + +Whenever relevant, please provide information about your environment (go version, OS). + +Adding a code snippet to reproduce the issue is great, and as a big time saver for maintainers. + +### Triaging issues + +You can help triage issues which may include: + +* reproducing bug reports +* asking for important information, such as version numbers or reproduction instructions +* answering questions and sharing your insight in issue comments + +## Code contributions + ### Pull requests are always welcome -We are always thrilled to receive pull requests, and do our best to -process them as fast as possible. Not sure if that typo is worth a pull -request? Do it! We will appreciate it. +We are always thrilled to receive pull requests, and we do our best to +process them as fast as possible. + +Not sure if that typo is worth a pull request? Do it! We will appreciate it. + +If your pull request is not accepted on the first try, don't be discouraged! +If there's a problem with the implementation, hopefully you received feedback on what to improve. + +If you have a lot of ideas or a lot of issues to solve, try to refrain a bit and post focused +pull requests. +Think that they must be reviewed by a maintainer and it is easy to lost track of things on big PRs. + +We're trying very hard to keep the go-openapi packages lean and focused. +These packages constitute a toolkit: it won't do everything for everybody out of the box, +but everybody can use it to do just about everything related to OpenAPI. + +This means that we might decide against incorporating a new feature. + +However, there might be a way to implement that feature *on top of* our libraries. + +### Environment + +You just need a `go` compiler to be installed. No special tools are needed to work with our libraries. + +The go compiler version required is always the old stable (latest minor go version - 1). -If your pull request is not accepted on the first try, don't be -discouraged! If there's a problem with the implementation, hopefully you -received feedback on what to improve. +If you're already used to work with `go` you should already have everything in place. -We're trying very hard to keep go-swagger lean and focused. We don't want it -to do everything for everybody. This means that we might decide against -incorporating a new feature. However, there might be a way to implement -that feature *on top of* go-swagger. +Although not required, you'll be certainly more productive with a local installation of `golangci-lint`, +the meta-linter our CI uses. +If you don't have it, you may install it like so: + +```sh +go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest +``` ### Conventions -Fork the repo and make changes on your fork in a feature branch: +#### Git flow + +Fork the repo and make changes to your fork in a feature branch. + +To submit a pull request, push your branch to your fork (e.g. `upstream` remote): +github will propose to open a pull request on the original repository. + +Typically you'd follow some common naming conventions: + +- if it's a bugfix branch, name it `fix/XXX-something`where XXX is the number of the + issue on github +- if it's a feature branch, create an enhancement issue to announce your + intentions, and name it `feature/XXX-something` where XXX is the number of the issue. + +> NOTE: we don't enforce naming conventions on branches: it's your fork after all. + +#### Tests + +Submit unit tests for your changes. + +Go has a great built-in test framework ; use it! + +Take a look at existing tests for inspiration, and run the full test suite on your branch +before submitting a pull request. + +Our CI measures test coverage and the test coverage of every patch. +Although not a blocking step - because there are so many special cases - +this is an indicator that maintainers consider when approving a PR. + +Please try your best to cover about 80% of your patch. + +#### Code style -- If it's a bugfix branch, name it XXX-something where XXX is the number of the - issue -- If it's a feature branch, create an enhancement issue to announce your - intentions, and name it XXX-something where XXX is the number of the issue. +You may read our stance on code style [there](../docs/STYLE.md). -Submit unit tests for your changes. Go has a great test framework built in; use -it! Take a look at existing tests for inspiration. Run the full test suite on -your branch before submitting a pull request. +#### Documentation -Update the documentation when creating or modifying features. Test -your documentation changes for clarity, concision, and correctness, as -well as a clean documentation build. See ``docs/README.md`` for more -information on building the docs and how docs get released. +Don't forget to update the documentation when creating or modifying features. -Write clean code. Universally formatted code promotes ease of writing, reading, -and maintenance. Always run `gofmt -s -w file.go` on each changed file before -committing your changes. Most editors have plugins that do this automatically. +Most documentation for this library is directly found in code as comments for godoc. + +The documentation for the go-openapi packages is published on the public go docs site: + + + +Check your documentation changes for clarity, concision, and correctness. + +If you want to assess the rendering of your changes when published to `pkg.go.dev`, you may +want to install the `pkgsite` tool proposed by `golang.org`. + +```sh +go install golang.org/x/pkgsite/cmd/pkgsite@latest +``` + +Then run on the repository folder: +```sh +pkgsite . +``` + +This wil run a godoc server locally where you may see the documentation generated from your local repository. + +#### Commit messages Pull requests descriptions should be as clear as possible and include a reference to all the issues that they address. Pull requests must not contain commits from other users or branches. -Commit messages must start with a capitalized and short summary (max. 50 -chars) written in the imperative, followed by an optional, more detailed -explanatory text which is separated from the summary by an empty line. +Commit messages are not required to follow the "conventional commit" rule, but it's certainly a good +thing to follow this guidelinea (e.g. "fix: blah blah", "ci: did this", "feat: did that" ...). -Code review comments may be added to your pull request. Discuss, then make the -suggested modifications and push additional commits to your feature branch. Be -sure to post a comment after pushing. The new commits will show up in the pull -request automatically, but the reviewers will not be notified unless you -comment. +The title in your commit message is used directly to produce our release notes: try to keep them neat. -Before the pull request is merged, make sure that you squash your commits into -logical units of work using `git rebase -i` and `git push -f`. After every -commit the test suite should be passing. Include documentation changes in the -same commit so that a revert would remove all traces of the feature or fix. +The commit message body should detail your changes. -Commits that fix or close an issue should include a reference like `Closes #XXX` -or `Fixes #XXX`, which will automatically close the issue when merged. +If an issue should be closed by a commit, please add this reference in the commit body: -### Sign your work +``` +* fixes #{issue number} +``` -The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as an open-source patch. The rules are pretty simple: if you -can certify the below (from -[developercertificate.org](http://developercertificate.org/)): +#### Code review -``` -Developer Certificate of Origin -Version 1.1 +Code review comments may be added to your pull request. -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA +Discuss, then make the suggested modifications and push additional commits to your feature branch. -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. +Be sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you comment. +Before the pull request is merged, +**make sure that you squash your commits into logical units of work** +using `git rebase -i` and `git push -f`. -Developer's Certificate of Origin 1.1 +After every commit the test suite should be passing. -By making a contribution to this project, I certify that: +Include documentation changes in the same commit so that a revert would remove all traces of the feature or fix. -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or +#### Sign your work -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or +The sign-off is a simple line at the end of your commit message, +which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. +We require the simple DCO below with an email signing your commit. +PGP-signed commit are greatly appreciated but not required. -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` +The rules are pretty simple: -then you just add a line to every git commit message: +* read our [DCO](./DCO.md) (from [developercertificate.org](http://developercertificate.org/)) +* if you agree with these terms, then you just add a line to every git commit message Signed-off-by: Joe Smith diff --git a/.github/DCO.md b/.github/DCO.md new file mode 100644 index 0000000..e168dc4 --- /dev/null +++ b/.github/DCO.md @@ -0,0 +1,40 @@ + # Developer's Certificate of Origin + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` diff --git a/.github/all-mispelled.txt b/.github/all-mispelled.txt deleted file mode 100644 index af64690..0000000 --- a/.github/all-mispelled.txt +++ /dev/null @@ -1,93 +0,0 @@ -AllOf -Args -AutoSeed -DCO -ERGGLGKLK -Formated -Fuzzying -GenerateMode -GeneratorOpts -GoDoc -JSON -README -Schemas -SetSeed -Severa -StubMode -Stubmode -USD -UnitTest -additionalItems -additionalProperties -appsawg -args -assignees -benchmarking -birthdate -bitmask -bsonobjectid -bugfix -codegen -customizable -datagen -datagenerator -datagenerators -datastructures -datetime -dco -definevalue -dev -developercertificate -eg -enum -everyhing -flanders -formated -fuzzying -gh -githubusercontent -godoc -gofmt -gojsonpointer -goreportcard -goswagger -html -ietf -img -ints -io -ipsums -ivan -json -jsonpointer -jsonschema -lang -loren -md -multipleOf -nz -patternProperties -preconfigured -rebase -rebased -schemas -sexualized -skipFuzzying -skipTilting -slackin -strfmt -stubmode -svg -th -tiltDefault -tiltExample -travis -unitTest -withAllValidationChecks -withDefault -withEdgeCase -withExample -withTilting -withValidation -withValidationCheck -yml diff --git a/.github/workflows/auto-merge.yml b/.github/workflows/auto-merge.yml index d1b2d9c..506a086 100644 --- a/.github/workflows/auto-merge.yml +++ b/.github/workflows/auto-merge.yml @@ -4,42 +4,73 @@ on: workflow_call: permissions: - contents: write - pull-requests: write + contents: read jobs: dependabot: + permissions: + contents: write + pull-requests: write runs-on: ubuntu-latest - if: github.event.pull_request.user.login == 'dependabot[bot]' + if: ${{ github.event.pull_request.user.login == 'dependabot[bot]' }} steps: - - name: Dependabot metadata + - + name: Dependabot metadata id: metadata - uses: dependabot/fetch-metadata@v2 - - - name: Auto-approve all dependabot PRs - run: gh pr review --approve "$PR_URL" + uses: dependabot/fetch-metadata@08eff52bf64351f401fb50d4972fa95b9f2c2d1b # v2.4.0 + - + name: Auto-approve all dependabot PRs env: PR_URL: ${{github.event.pull_request.html_url}} GH_TOKEN: ${{secrets.GITHUB_TOKEN}} - - - name: Auto-merge dependabot PRs for development dependencies - if: contains(steps.metadata.outputs.dependency-group, 'development-dependencies') - run: gh pr merge --auto --rebase "$PR_URL" + run: gh pr review --approve "$PR_URL" + - + name: Auto-merge dependabot PRs for development dependencies + if: ${{ contains(steps.metadata.outputs.dependency-group, 'development-dependencies') }} env: PR_URL: ${{github.event.pull_request.html_url}} GH_TOKEN: ${{secrets.GITHUB_TOKEN}} - - - name: Auto-merge dependabot PRs for go-openapi patches - if: contains(steps.metadata.outputs.dependency-group, 'go-openapi-dependencies') && (steps.metadata.outputs.update-type == 'version-update:semver-minor' || steps.metadata.outputs.update-type == 'version-update:semver-patch') run: gh pr merge --auto --rebase "$PR_URL" + - + name: Auto-merge dependabot PRs for go-openapi patches + if: >- + ${{ + contains(steps.metadata.outputs.dependency-group, 'go-openapi-dependencies') && + ( + steps.metadata.outputs.update-type == 'version-update:semver-minor' || + steps.metadata.outputs.update-type == 'version-update:semver-patch' + ) + }} env: PR_URL: ${{github.event.pull_request.html_url}} GH_TOKEN: ${{secrets.GITHUB_TOKEN}} - - - name: Auto-merge dependabot PRs for golang.org updates - if: contains(steps.metadata.outputs.dependency-group, 'golang-org-dependencies') run: gh pr merge --auto --rebase "$PR_URL" + - + name: Auto-merge dependabot PRs for golang.org updates + if: ${{ contains(steps.metadata.outputs.dependency-group, 'golang-org-dependencies') }} env: PR_URL: ${{github.event.pull_request.html_url}} GH_TOKEN: ${{secrets.GITHUB_TOKEN}} + run: gh pr merge --auto --rebase "$PR_URL" + # Auto merge is current disabled: we need automatic PRs to swap identity (e.g. using a Github App), + # so the pull_request event is properly captured and the PR can validate. + #actions-bot: + # permissions: + # contents: write + # pull-requests: write + # runs-on: ubuntu-latest + # if: ${{ github.event.pull_request.user.login == 'github-actions[bot]' }} + # steps: + # - + # name: Auto-approve all github-actions bot PRs + # env: + # PR_URL: ${{github.event.pull_request.html_url}} + # GH_TOKEN: ${{secrets.GITHUB_TOKEN}} + # run: gh pr review --approve "$PR_URL" + # - + # name: Auto-merge github-actions bot PRs + # env: + # PR_URL: ${{github.event.pull_request.html_url}} + # GH_TOKEN: ${{secrets.GITHUB_TOKEN}} + # run: gh pr merge --auto --rebase "$PR_URL" diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml new file mode 100644 index 0000000..a3d1c59 --- /dev/null +++ b/.github/workflows/codeql.yml @@ -0,0 +1,34 @@ +name: "CodeQL" + +on: + workflow_call: + +permissions: + contents: read + +jobs: + analyze: + name: Analyze. + runs-on: ubuntu-latest + timeout-minutes: 360 + permissions: + contents: read + security-events: write + # actions: read # <- is needed only for private repositories + strategy: + fail-fast: false + matrix: + language: ['go','actions'] + steps: + - + name: Checkout repository + uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + - + # Initializes the CodeQL tools for scanning. + name: Initialize CodeQL + uses: github/codeql-action/init@014f16e7ab1402f30e7c3329d33797e7948572db # v4.31.3 + with: + languages: ${{ matrix.language }} + - + name: Analyze ${{ matrix.language }} + uses: github/codeql-action/analyze@014f16e7ab1402f30e7c3329d33797e7948572db # v4.31.3 diff --git a/.github/workflows/contributors.yml b/.github/workflows/contributors.yml new file mode 100644 index 0000000..79a7047 --- /dev/null +++ b/.github/workflows/contributors.yml @@ -0,0 +1,45 @@ +name: Contributors + +on: + workflow_call: + +permissions: + contents: read + +jobs: + update-contributors: + name: all-time contributors + permissions: + pull-requests: write + contents: write + runs-on: ubuntu-latest + steps: + - + name: Checkout repository + uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + - + name: Identify all-time contributors to this repository + uses: github/contributors@8b7586939baa0af4e801dbd22c88adf6e0db8915 # v1.7.5 + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + REPOSITORY: ${{ github.repository }} + LINK_TO_PROFILE: 'True' + - + name: Rename contributor file + run: | + rm -rf contributors.json + mv contributors.md CONTRIBUTORS.md + - + name: Create a PR + id: create-pull-request + uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e # v7.0.8 + with: + commit-message: "doc: updated contributors file" + branch: doc/contributors-bot + delete-branch: true + title: "doc: updated contributors file" + token: ${{ secrets.GITHUB_TOKEN }} + labels: "bot" + assignees: fredbi + reviewers: fredbi + sign-commits: true diff --git a/.github/workflows/doc-update.yml b/.github/workflows/doc-update.yml index 8cde395..e343a4d 100644 --- a/.github/workflows/doc-update.yml +++ b/.github/workflows/doc-update.yml @@ -55,18 +55,19 @@ jobs: proceed: ${{ steps.changed-markdown-files.outputs.any_changed }} all_changed_files: ${{ steps.changed-markdown-files.outputs.all_changed_files }} steps: - - name: Originating repo checkout (e.g. public fork) - uses: actions/checkout@v5 + - + name: Originating repo checkout (e.g. public fork) + uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 with: ref: ${{ github.event.pull_request.head.sha }} - - - name: Get changed markdown files - uses: tj-actions/changed-files@v46 + - + name: Get changed markdown files + uses: tj-actions/changed-files@24d32ffd492484c1d75e0c0b894501ddb9d30d62 # v4.7.0 id: changed-markdown-files with: files: '**/*.md' - - - name: Notify + - + name: Notify run: | echo "::notice::Detected some changed markdown files" echo "${{ steps.changed-markdown-files.outputs.all_changed_files }}" @@ -81,15 +82,15 @@ jobs: proceed: ${{ steps.report-exists.outputs.proceed }} congrats: ${{ steps.congrats.outputs.proceed }} report: ${{ steps.report-exists.outputs.report }} - steps: - - name: Originating repo checkout (e.g. public fork) - uses: actions/checkout@v5 + - + name: Originating repo checkout (e.g. public fork) + uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 with: ref: ${{ github.event.pull_request.head.sha }} - - - name: Checkout markdown config - uses: actions/checkout@v5 + - + name: Checkout markdown config + uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 with: repository: go-openapi/ci-workflows ref: master # TODO: retrieve workflow ref @@ -97,13 +98,13 @@ jobs: ${{ env.markdown_config }} sparse-checkout-cone-mode: false path: ci-tools - - - name: Copy markdown config + - + name: Copy markdown config # TODO: merge with local if present run: | cp ci-tools/"${{ env.markdown_config}}" "${{ env.markdown_config }}" - - - name: Run markdown linter + - + name: Run markdown linter continue-on-error: true id: markdownlint uses: docker://avtodev/markdown-lint:v1.5 @@ -111,15 +112,15 @@ jobs: config: ./${{ env.markdown_config }} args: '${{ needs.markdown-changed.outputs.all_changed_files }}' output: '${{ env.lintreport }}' - - - name: Comment on success + - + name: Comment on success if: ${{ steps.markdownlint.outcome == 'success' }} id: congrats run: | echo "::notice:: no linting issue with changed markdown" echo "proceed=true" >> $GITHUB_OUTPUT - - - name: Comment on markdown lint complaining + - + name: Comment on markdown lint complaining if: ${{ steps.markdownlint.outcome != 'success' && hashFiles(env.lintreport) != '' }} id: report-exists run: | @@ -136,8 +137,8 @@ jobs: echo "proceed=false" >> $GITHUB_OUTPUT echo "::notice::No linting issues with changed markdown" fi - - - name: Other linter errors + - + name: Other linter errors if: ${{ steps.markdownlint.outcome != 'success' && hashFiles(env.lintreport) == '' }} run: | echo "::error::markdown linter encountered an error" @@ -154,12 +155,13 @@ jobs: congrats: ${{ steps.congrats.outputs.proceed }} report: ${{ steps.report-exists.outputs.report }} steps: - - uses: actions/checkout@v5 + - + uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 with: ref: ${{ github.event.pull_request.head.sha }} - - - name: Checkout spellcheck config - uses: actions/checkout@v5 + - + name: Checkout spellcheck config + uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 with: repository: go-openapi/ci-workflows ref: master # TODO: retrieve workflow ref @@ -168,14 +170,14 @@ jobs: ${{ env.spellcheck_dict }} sparse-checkout-cone-mode: false path: ci-tools - - - name: Copy spellcheck config + - + name: Copy spellcheck config # TODO: merge with local if present run: | cp ci-tools/${{ env.spellcheck_config }} ${{ env.spellcheck_config }} cp ci-tools/${{ env.spellcheck_dict }} ${{ env.spellcheck_dict }} - - - name: Spellcheck + - + name: Spellcheck uses: rojopolis/spellcheck-github-actions@0.51.0 continue-on-error: true id: spellcheck @@ -184,8 +186,8 @@ jobs: source_files: '${{ needs.markdown-changed.outputs.all_changed_files }}' task_name: markdown output_file: ${{ env.spellcheckreport }} - - - name: Comment on success + - + name: Comment on success if: ${{ steps.spellcheck.outcome == 'success' }} id: congrats run: | @@ -195,8 +197,8 @@ jobs: echo "### Your changes to markdown docs show impeccable spelling. 👍" >> $GITHUB_STEP_SUMMARY echo "" >> $GITHUB_STEP_SUMMARY echo "> ℹī¸ INFO: we use [rojopolis/spellcheck-github-actions](https://github.com/rojopolis/spellcheck-github-actions)" >> $GITHUB_STEP_SUMMARY - - - name: Comment on spellcheck complaining + - + name: Comment on spellcheck complaining if: ${{ steps.spellcheck.outcome != 'success' && hashFiles(env.spellcheckreport) != '' }} id: report-exists run: | @@ -212,8 +214,8 @@ jobs: echo "proceed=false" >> $GITHUB_OUTPUT echo "::notice::No spelling issues with changed markdown" fi - - - name: Other linter errors + - + name: Other linter errors if: ${{ steps.spellcheck.outcome != 'success' && hashFiles(env.spellcheckreport) == '' }} run: | echo "::error::spellcheck encountered an error" @@ -232,13 +234,14 @@ jobs: comment_title: ${{ steps.notify_markdown_congrats.outputs.comment_title }} reactions: ${{ steps.notify_markdown_congrats.outputs.reactions }} steps: - - name: Congrats + - + name: Congrats id: notify_markdown_congrats run: | mkdir -p "${{ env.artifacts_dir }}" read -d '' MSG<> "$GITHUB_OUTPUT" echo "comment_title=${{ env.markdown_comment_title }}" >> "$GITHUB_OUTPUT" echo "reactions=hooray" >> "$GITHUB_OUTPUT" - - - name: Upload comment as artifact + - + name: Upload comment as artifact uses: actions/upload-artifact@v4 with: path: ${{ env.artifacts_dir }}/${{ env.markdown_artifact }} @@ -290,7 +293,8 @@ jobs: reactions: ${{ steps.notify_markdown_report.outputs.reactions }} runs-on: ubuntu-latest steps: - - name: Format PR comment + - + name: Format PR comment id: comment_formatter uses: skills/action-text-variables@v3 with: @@ -300,7 +304,7 @@ jobs: } template-text: | ### ${{ env.markdown_comment_title }} - + Some markdown linting issues were detected in the modified .md files. ⚠ī¸ Perhaps they were already there before your changes. @@ -308,13 +312,13 @@ jobs: This check is advisory only and not blocking. Please help us adopt a nice markdown style. Markdown formatting rules are documented [here](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md). -
+
``` {{ text }} ``` - - - name: Slap on the wrist + - + name: Slap on the wrist env: OUTPUT: "${{ steps.comment_formatter.outputs.updated-text }}" run: | @@ -324,14 +328,14 @@ jobs: echo "### Changed markdown docs need some formatting. ⚠ī¸" >> $GITHUB_STEP_SUMMARY echo "" >> $GITHUB_STEP_SUMMARY echo "> ℹī¸ INFO: we use [avtodev/markdown-lint action](https://github.com/avto-dev/markdown-lint)" >> $GITHUB_STEP_SUMMARY - - - name: Upload comment as artifact + - + name: Upload comment as artifact uses: actions/upload-artifact@v4 with: path: ${{ env.artifacts_dir }}/${{ env.markdown_artifact }} name: ${{ env.markdown_artifact }} - - - name: Notify + - + name: Notify id: notify_markdown_report run: | echo "::notice::Commented pull request ${{ github.event.pull_request.number }}" @@ -371,13 +375,14 @@ jobs: reactions: ${{ steps.notify_spelling_congrats.outputs.reactions }} runs-on: ubuntu-latest steps: - - name: Congrats + - + name: Congrats id: notify_spelling_congrats run: | mkdir -p artifacts read -d '' MSG<> "$GITHUB_OUTPUT" echo "comment_title=${{ env.spellcheck_comment_title }}" >> "$GITHUB_OUTPUT" echo "reactions=hooray" >> "$GITHUB_OUTPUT" - - - name: Upload comment as artifact + - + name: Upload comment as artifact uses: actions/upload-artifact@v4 with: path: ${{ env.artifacts_dir }}/${{ env.spellcheck_artifact }} @@ -425,12 +430,13 @@ jobs: reactions: ${{ steps.notify_spelling_report.outputs.reactions }} runs-on: ubuntu-latest steps: - - name: Pre-process spellcheck report + - + name: Pre-process spellcheck report id: preprocess - env: + env: MSG: ${{ needs.markdown-spelling.outputs.report }} - SED_CMD: .github/workflows/filter.sed # a sed script to parse and reformat the spellcheck report - JQ_CMD: .github/workflows/merge.jq # a jq script to dedupe spellcheck reports by file + SED_CMD: .github/workflows/scripts/filter.sed # a sed script to parse and reformat the spellcheck report + JQ_CMD: .github/workflows/scripts/merge.jq # a jq script to dedupe spellcheck reports by file TMPFILE: /tmp/spellcheck-report.txt run: | export MSG @@ -444,8 +450,8 @@ jobs: echo 'report<> $GITHUB_OUTPUT cat /tmp/preprocessed.txt|sed -e '$a\' >> $GITHUB_OUTPUT echo 'EOF' >> $GITHUB_OUTPUT - - - name: Format PR comment + - + name: Format PR comment id: comment_formatter uses: skills/action-text-variables@v3 with: @@ -455,20 +461,20 @@ jobs: } template-text: | ### ${{ env.spellcheck_comment_title }} - + Some mispelled words were detected in the modified .md files. ⚠ī¸ Perhaps they were already there before your changes. This check is advisory only and not blocking. Please help us improve our documentation. -
+
``` ### TODO: range json {{ text }} ``` - - - name: Slap on the wrist + - + name: Slap on the wrist env: OUTPUT: "${{ steps.comment_formatter.outputs.updated-text }}" run: | @@ -480,8 +486,8 @@ jobs: echo "> ℹī¸ INFO: we use [rojopolis/spellcheck-github-actions](https://github.com/rojopolis/spellcheck-github-actions)." >> $GITHUB_STEP_SUMMARY echo ">" >> $GITHUB_STEP_SUMMARY echo "> As a general rule, technical terms or acronyms and references to code objects should be backquoted in markdown" >> $GITHUB_STEP_SUMMARY - - - name: Upload comment as artifact + - + name: Upload comment as artifact # description: | # Calls a trusted shared workflow that temporarily elevates the caller's privileges # to write a comment in the PR. @@ -489,8 +495,8 @@ jobs: with: path: ${{ env.artifacts_dir }}/${{ env.spellcheck_artifact }} name: ${{ env.spellcheck_artifact }} - - - name: Notify + - + name: Notify id: notify_spelling_report run: | echo "::notice::Commented pull request ${{ github.event.pull_request.number }}" diff --git a/.github/workflows/go-test.yml b/.github/workflows/go-test.yml index c7fecd8..5dddca1 100644 --- a/.github/workflows/go-test.yml +++ b/.github/workflows/go-test.yml @@ -1,178 +1,308 @@ -name: go test -# description: | -# This workflow to run unit tests on a repo that contains a single go module. -# -# ## Usage of github action features -# -# * shared workflow -# * matrix job -# * job summary (on actions UI) -# -# ## Limitations of github action features -# -# * [ ] needed to hardcode all matrix job entries as outputs. No way to make this dynamic. -# -# ## TODO -# -# * [ ] perhaps implement in golangci-lint the "extends" or "include" functionality to merge -# config files from a remote location. We don't want to push configs from CI as we'd -# like all repos to allow users to fork, lint and run just like they were independent, -# and not impose some "invisible linter" check. -# * [ ] we need to make a specific version for mono-repos. For now, only go-openapi swag is a mono-repo. -# * [ ] detect minimum required go version in go.mod and run a test for that one +name: go-test on: - workflow_call: + push: + branches: + - master + + pull_request: + +permissions: + pull-requests: read + contents: read jobs: lint: name: Lint - # description: | - # Lint uses golangci-lint github action and lints only changes from master. - # - # It will run on the latest go version. - # - # We rely on golangci-lint to automatically disable linters that do not apply to the minimum required go version - # currently defined in go.mod. - # - # At this moment, .golangci.yml configuration files are not shared: each repository must have its configuration. runs-on: ubuntu-latest steps: - - uses: actions/checkout@v5 - - uses: actions/setup-go@v5 + - + uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + - + uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00 # v6.0.0 with: go-version: stable check-latest: true cache: true - - name: golangci-lint - uses: golangci/golangci-lint-action@v8 + - + name: golangci-lint + uses: golangci/golangci-lint-action@0a35821d5c230e903fcfe077583637dea1b27b47 # v9.0.0 with: version: latest only-new-issues: true - skip-cache: false - - name: Linting complete # <- report summary when we have good news to report - run: | - echo "### Your changes to the go code look good. 👍" >> $GITHUB_STEP_SUMMARY - echo "" >> $GITHUB_STEP_SUMMARY - echo "> ℹī¸ INFO: we use [golangci-lint action](https://github.com/golangci/golangci-lint-action)" >> $GITHUB_STEP_SUMMARY - echo "> to lint any change to go code from master." >> $GITHUB_STEP_SUMMARY + skip-cache: true - unit_tests: + test: name: Unit tests - # description: | - # Run go unit tests x6 on linux, mac & windows for the 2 latest go versions. - # - # * Run tests with the -race flag. - # * Captures test coverage and uploads it to codecov.com. - # - # > NOTE: coverage uploads to codecov are authorized thanks to an organization token that is - # > managed on [codecov admin console](https://app.codecov.io/account/gh/go-openapi). runs-on: ${{ matrix.os }} - outputs: - # NOTE(fredbi): as of Aug. 2025, there is no way to have github actions declare outputs dynamically - test_result_oldstable_ubuntu_latest: "${{ steps.goreport.outputs.test_result_oldstable_ubuntu_latest }}" - test_result_oldstable_macos_latest: "${{ steps.goreport.outputs.test_result_oldstable_macos_latest }}" - test_result_oldstable_windows_latest: "${{ steps.goreport.outputs.test_result_oldstable_windows_latest }}" - test_result_stable_ubuntu_latest: "${{ steps.goreport.outputs.test_result_stable_ubuntu_latest }}" - test_result_stable_macos_latest: "${{ steps.goreport.outputs.test_result_stable_macos_latest }}" - test_result_stable_windows_latest: "${{ steps.goreport.outputs.test_result_stable_windows_latest }}" + needs: [lint] strategy: matrix: os: [ ubuntu-latest, macos-latest, windows-latest ] - go_version: ['oldstable', 'stable' ] + go: ['oldstable', 'stable' ] steps: - - uses: actions/setup-go@v5 - with: - go-version: '${{ matrix.go_version }}' - check-latest: true - cache: true # <- cache key is go.sum - - - uses: actions/checkout@v5 - - - name: Run unit tests - # description: | - # Runs unit tests with test coverage assuming that this repository contains only one module, - # with a go.mod located at the root. - # - # > NOTE - # > The -coverpkg option is important to have all coverage files containing - # > an appropriate reference to source files, so coverage may be followed accuratelt - # > on codecov UI. - id: gotest - shell: bash - run: | - go test -v \ - -race \ - -coverprofile="coverage-${{ matrix.os }}.${{ matrix.go_version }}.out" \ - -covermode=atomic \ - -coverpkg=$(go list ./... |paste -sd ",") \ - ./... - - - name: Report test - # description: | - # This is reporting the job summary (github UI). - if: ${{ success() || failure() }} - id: goreport - shell: bash - run: | - icon="✅" - if [[ "${{ steps.gotest.outcome }}" != "success" ]] ; then - icon="đŸšĢ" - fi - echo "test_result_${{ matrix.go_version }}_$(echo "${{ matrix.os }}"|tr '-' '_')='| ${{ matrix.go_version }} | ${{ matrix.os }} | ${icon} ${{ steps.gotest.outcome }} |'" >> "$GITHUB_OUTPUT" - - - name: Upload coverage to codecov - uses: codecov/codecov-action@v5 - with: - files: './coverage-${{ matrix.os }}.${{ matrix.go_version }}.out' - flags: '${{ matrix.go_version }}-${{ matrix.os }}' - fail_ci_if_error: false - verbose: false - - all_tests: - name: All tests - # description: | - # This job regroups all tests launched as a matrix, so we may define a branch protection rule - # just on that job rather than each matrix job independently. - needs: [ unit_tests ] # <- requires all unit_tests jobs to be successful. + - + uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + - + uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00 # v6.0.0 + with: + go-version: '${{ matrix.go }}' + check-latest: true + cache: true + - + name: Install Tools + # TODO: pin version -> fork + update dedicated github action + run: | + go install gotest.tools/gotestsum@latest + - + name: Run unit tests + shell: bash + run: > + gotestsum + --jsonfile 'unit.report.${{ matrix.os }}-${{ matrix.go }}.json' + -- + -race + -p 2 + -count 1 + -timeout=20m + -coverprofile='unit.coverage.${{ matrix.os }}-${{ matrix.go }}.out' + -covermode=atomic + -coverpkg=$(go list)/... + ./... + - + name: Upload coverage artifacts + uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0 + with: + # *.coverage.* pattern is automatically detected by codecov + path: '**/*.coverage.*.out' + name: 'unit.coverage.${{ matrix.os }}-${{ matrix.go }}' + retention-days: 1 + - + name: Upload test report artifacts + # upload report even if test fail. BTW, this is when they are valuable. + if: ${{ !cancelled() }} + uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0 + with: + path: '**/unit.report.*.json' + name: 'unit.report.${{ matrix.os }}-${{ matrix.go }}' + retention-days: 1 + + fuzz-test: + name: fuzz test + runs-on: ubuntu-latest env: - test_result: '${{ join(needs.unit_tests.outputs.*) }}' # <- this is a comma-separated list of quoted strings + CORPUS_MAX_SIZE_MB: 100 + steps: + - + uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + - + uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00 # v6.0.0 + with: + go-version: stable + check-latest: true + cache: true + - + name: Locate go fuzz cache + run: | + GOCACHE=$(go env GOCACHE) + echo "CORPUS_DIR=${GOCACHE}/fuzz" >> "${GITHUB_ENV}" + - + name: Retrieve fuzz corpus from cache + uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0 + with: + key: ${{ runner.os }}-go-fuzz + path: + ${{ env.CORPUS_DIR }} + - + name: Manage fuzz corpus cache size + run: | + mkdir -p "${CORPUS_DIR}" + CURRENT_SIZE=$(du -sm "${CORPUS_DIR}"|cut -f1) + echo "corpus size: ${CURRENT_SIZE}MB" + if [[ "${CURRENT_SIZE}" -gt "${CORPUS_MAX_SIZE}" ]] ; then + # remove the 50 oldest corpus files + echo "::warning:Large fuzz corpus pruned" + find "${CORPUS_DIR}" -type f|ls -t|tail -n +50|xargs rm -f + fi + - + name: Run go fuzz tests + run: > + go test + -fuzz=Fuzz + -run=Fuzz + -fuzztime=1m30s + -fuzzminimizetime=5m + ./... + - + name: Upload failed corpus + if: ${{ failure() }} + uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0 + with: + path: ${{ env.CORPUS_DIR }} + name: '${{ runner.os }}-fuzz-corpus-failure' + retention-days: 60 + - + name: Report fuzz corpus cache size + run: | + FINAL_SIZE=$(du -m "${CORPUS_DIR}"|cut -f1) + echo "::notice title=fuzz corpus size:${FINAL_SIZE}MB" + + + test-complete: + # description: | + # Be explicit about all tests being passed. This allows for setting up only a few status checks on PRs. + name: tests completed + needs: [test,fuzz-test] runs-on: ubuntu-latest steps: - - name: Tests complete + - + name: Tests completed run: | - echo "### All tests completed. 👍" >> $GITHUB_STEP_SUMMARY - echo "" >> $GITHUB_STEP_SUMMARY - echo "> ℹī¸ INFO: we run unit tests in 6 different configurations of OS and go version." >> $GITHUB_STEP_SUMMARY - echo "> At this moment, we don't run architecture-specific tests." >> $GITHUB_STEP_SUMMARY - echo "" >> $GITHUB_STEP_SUMMARY - echo "| go version | OS | Result |" >> $GITHUB_STEP_SUMMARY - echo "|------------|----|--------|" >> $GITHUB_STEP_SUMMARY - declare -a lines - eval "lines=($(echo $test_result|tr ',' ' '))" - for line in "${lines[@]}";do echo "${line}" ; done >> $GITHUB_STEP_SUMMARY - - some_failed_tests: - name: Some tests have failed + echo "::notice title=Success:All tests passed" + + collect-coverage: # description: | - # This job is only here to report a summary of failed tests in the github actions UI. - needs: [ unit_tests ] # <- requires all unit_tests jobs to be completed, but not all where successfull. - if: ${{ failure() }} - env: - test_result: '${{ join(needs.unit_tests.outputs.*) }}' + # Gather, merge then uploads test coverage files from all test jobs (this includes integration tests, + # like codegen-test). This reduces the number of failures due to codecov hitting github API rate limit. + name: collect test coverage + needs: [test-complete] + if: ${{ !cancelled() && needs.test-complete.result == 'success' }} runs-on: ubuntu-latest steps: - - name: Tests failed + - + uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + with: + ref: ${{ github.event.pull_request.head.ref }} + repository: ${{ github.event.pull_request.head.repo.full_name }} + - + name: Download coverage artifacts + uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0 + with: + run-id: "${{ github.run_id }}" + pattern: "*.coverage.*" + # artifacts resolve as folders + path: coverage/ + - + name: Upload coverage to codecov + uses: codecov/codecov-action@5a1091511ad55cbe89839c7260b706298ca349f7 # v5.5.1 + with: + name: Aggregated coverage + # All *.coverage.*.out files uploaded should be detected by the codecov action. + # NOTE: we lose the flags on individual test reports (e.g. by os, by go version, unit vs integration tests) + fail_ci_if_error: false + verbose: false + + collect-reports: + # description: | + # Gather, merge then uploads test report files from unit test jobs. + # + # At this moment test reports are published on both codecov + # (see ) and the github actions UI + # (see ). + name: collect test reports + needs: [test] + if: ${{ !cancelled() }} + runs-on: ubuntu-latest + steps: + - + uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00 # v6.0.0 + with: + go-version: stable + check-latest: true + cache: true + - + name: Download test report artifacts + uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0 + with: + run-id: "${{ github.run_id }}" + pattern: "*.report.*" + # artifacts resolve as folders + path: reports/ + - + name: Convert test reports to a merged JUnit XML + # NOTE: codecov test reports only support JUnit format at this moment. See https://docs.codecov.com/docs/test-analytics. + # Ideally, codecov improve a bit their platform, so we may only need a single pass to CTRF format. + # + # As a contemplated alternative, we could use gotestsum above to produce the JUnit XML directly. + # At this moment, we keep a json format to dispatch test reports to codecov as well as to CTRF reports. + # + # TODO(fredbi): sec compliance - pin go-junit-report + # TODO(fredbi): investigate - use mikepenz/action-junit-report@v5, that packages most of the following scripts + # in a single action. Alternative: for that action. + run: | + go install github.com/jstemmer/go-junit-report/v2@latest + go-junit-report -version + + find reports/ -name \*.json | xargs cat | go-junit-report -parser gojson -out=reports/junit_report.xml + - + name: Upload test results to Codecov + # This allows for using the test results UI on codecov + uses: codecov/codecov-action@5a1091511ad55cbe89839c7260b706298ca349f7 # v5.5.1 + with: + files: '**/junit_report.xml' + report_type: 'test_results' + fail_ci_if_error: false + handle_no_reports_found: true + verbose: true + - + name: Convert test reports to CTRF JSON + # description: | + # This step publishes CTRF test reports on github UI (actions) + # TODO: pin this dependency run: | - echo "### Some tests have failed. đŸšĢ" >> $GITHUB_STEP_SUMMARY - echo "" >> $GITHUB_STEP_SUMMARY - echo "> ℹī¸ INFO: testing halted on first encountered failure." >> $GITHUB_STEP_SUMMARY - echo "> Some configurations may not have been tested yet." >> $GITHUB_STEP_SUMMARY - echo "" >> $GITHUB_STEP_SUMMARY - echo "| go version | OS | Result |" >> $GITHUB_STEP_SUMMARY - echo "|------------|----|--------|" >> $GITHUB_STEP_SUMMARY - declare -a lines - eval "lines=($(echo $test_result|tr ',' ' '))" - for line in "${lines[@]}";do echo "${line}" ; done >> $GITHUB_STEP_SUMMARY + go install github.com/ctrf-io/go-ctrf-json-reporter/cmd/go-ctrf-json-reporter@v0.0.10 + + appName="${{ github.repository }}" + buildNumber="${{ github.run_id }}" + appVersion="${{ github.event.pull_request.head.sha }}" + if [[ -z "${appVersion}" ]] ; then + # for push events + appVersion="${{ github.sha }}" + fi + + # reconstruct platform information from the file name + # set -x + while read report ; do + # 'unit.report.${{ matrix.os }}-${{ matrix.go }}.json' + reformated=$(echo "${report##*/}"|sed -E 's/(go)([[:digit:]]+)\.([[:digit:]]+)/\1\2\3/') # e.g. go1.24 becomes go124 + mapfile -d'.' -t -s 2 -n 2 split < <(echo $reformated) # skip the first 2 parts, stop on 2 more parts + envstring="${split[0]}" + osPlatform="${envstring%-*}" + osRelease="${envstring##*-}" + + # this is a best effort only: tests may be cancelled upstream and produce incorrect reports + go-ctrf-json-reporter \ + -quiet \ + -appName "${appName}" \ + -appVersion "${appVersion}" \ + -buildNumber "${buildNumber}" \ + -osPlatform "${osPlatform}" \ + -osRelease "${osRelease}" \ + -output "./reports/ctrf_report_${osPlatform}_${osRelease}.json" < "${report}" || true + done < <(find reports -name \*.json) + + # NOTE: at this moment, we don't upload CTRF reports as artifacts. + # Some of the CTRF reports are therefore not available (flaky tests, history, ...). + # + # See https://github.com/ctrf-io/github-test-reporter?tab=readme-ov-file#report-showcase + # for more reporting possibilities. At the moment, we keep it simple, as most advanced features + # require a github token (thus adding the complexity of a separate workflow starting on pull_request_target). + # + # For the moment, we are contented with these simple reports. This is an opportunity to compare the insight they + # provide as compared to what is uploaded to codecov. + # + # Codecov analytics are pretty poor at this moment. On the other hand, they manage the bot that pushes back + # PR comments. + # + # They also handle the storage of past test reports, so as to assess flaky tests. + - + name: Publish Test Summary Results + uses: ctrf-io/github-test-reporter@024bc4b64d997ca9da86833c6b9548c55c620e40 # v1.0.26 + with: + report-path: 'reports/ctrf_report_*.json' + use-suite-name: true + summary-report: true # post a report to the github actions summary + github-report: true + failed-folded-report: true diff --git a/.github/workflows/local-auto-merge.yml b/.github/workflows/local-auto-merge.yml index 8cd8751..56a981c 100644 --- a/.github/workflows/local-auto-merge.yml +++ b/.github/workflows/local-auto-merge.yml @@ -1,14 +1,16 @@ name: Dependabot auto-merge # description: This workflow mimics how a go-openapi repo would typically invoke the common workflow. -on: pull_request - +on: + pull_request: permissions: - contents: write - pull-requests: write + contents: read jobs: dependabot: + permissions: + contents: write + pull-requests: write uses: ./.github/workflows/auto-merge.yml secrets: inherit diff --git a/.github/workflows/local-codeql.yml b/.github/workflows/local-codeql.yml new file mode 100644 index 0000000..3b2728e --- /dev/null +++ b/.github/workflows/local-codeql.yml @@ -0,0 +1,22 @@ +name: "CodeQL" + +on: + push: + branches: [ "master" ] + pull_request: + branches: [ "master" ] + path-ignore: + - '**/*.md' + schedule: + - cron: '39 19 * * 5' + +permissions: + contents: read + +jobs: + codeql: + permissions: + contents: read + security-events: write + uses: ./.github/workflows/codeql.yml + secrets: inherit diff --git a/.github/workflows/local-contributors.yml b/.github/workflows/local-contributors.yml new file mode 100644 index 0000000..41c731e --- /dev/null +++ b/.github/workflows/local-contributors.yml @@ -0,0 +1,18 @@ +name: Contributors + +on: + schedule: + - cron: '18 4 * * 6' + + workflow_dispatch: + +permissions: + contents: read + +jobs: + contributors: + permissions: + pull-requests: write + contents: write + uses: ./.github/workflows/contributors.yml + secrets: inherit diff --git a/.github/workflows/local-go-test.yml b/.github/workflows/local-go-test.yml index d96d250..44ebd24 100644 --- a/.github/workflows/local-go-test.yml +++ b/.github/workflows/local-go-test.yml @@ -3,13 +3,15 @@ name: go test on: push: - tags: - - v* branches: - master pull_request: +permissions: + pull-requests: read + contents: read + jobs: test: uses: ./.github/workflows/go-test.yml diff --git a/.github/workflows/local-release.yml b/.github/workflows/local-release.yml new file mode 100644 index 0000000..45beed7 --- /dev/null +++ b/.github/workflows/local-release.yml @@ -0,0 +1,16 @@ +name: Release + +on: + push: + tags: + - v[0-9]+* + +permissions: + contents: read + +jobs: + release: + permissions: + contents: write + uses: ./.github/workflows/release.yml + secrets: inherit diff --git a/.github/workflows/local-scanner.yml b/.github/workflows/local-scanner.yml new file mode 100644 index 0000000..3e1a0cc --- /dev/null +++ b/.github/workflows/local-scanner.yml @@ -0,0 +1,18 @@ +name: Vulnerability scans + +on: + branch_protection_rule: + push: + branches: [ "master" ] + schedule: + - cron: '18 4 * * 3' + +permissions: read-all + +jobs: + release: + permissions: + contents: read + security-events: write + uses: ./.github/workflows/scanner.yml + secrets: inherit diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..1e79ad9 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,56 @@ +name: Release + +on: + workflow_call: + +permissions: + contents: read + +# description: | +# Build a github release on pushed tag. +# +# The only available asset is a release note. + +jobs: + gh-release: + name: Create release + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - + name: Checkout code + uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + with: + fetch-depth: 0 + - + name: Extract tag message + id: get_message + # git-cliff may or may not pick the current tag message, difficult to tell when + # this works. We extract the tag message explicitly. + run: | + MESSAGE=$(git tag -l '${{ github.ref_name }}' --format='%(contents:subject) + + %(contents:body) + ') + export MESSAGE + echo "message<> "${GITHUB_OUTPUT}" + printenv MESSAGE >> "${GITHUB_OUTPUT}" + echo 'EOF' >> "${GITHUB_OUTPUT}" + - + name: Generate release notes + id: notes + env: + GITHUB_TOKEN: ${{ github.token }} + GITHUB_REPO: ${{ github.repository }} + uses: orhun/git-cliff-action@d77b37db2e3f7398432d34b72a12aa3e2ba87e51 # v4.6.0 + with: + config: '.cliff.toml' + args: >- + --current + --with-tag-message '${{ steps.get_message.outputs.message }}' + - + name: Create github release + uses: softprops/action-gh-release@5be0e66d93ac7ed76da52eca8bb058f665c3a5fe # v2.4.2 + with: + body: ${{ steps.notes.outputs.content }} diff --git a/.github/workflows/scanner.yml b/.github/workflows/scanner.yml new file mode 100644 index 0000000..2f34e48 --- /dev/null +++ b/.github/workflows/scanner.yml @@ -0,0 +1,65 @@ +name: Vulnerability scans + +on: + workflow_call: + +permissions: read-all + +# description: | +# A fast vulnerability scan on the repo that effectively supplements ossf scorecard and codesql +# and may run every day. +# +# * trivy reports are often more easily actionable than codeql reports. +# * govumnscan supplements this analysis with a more go-specific approach +# +# NOTE: at this moment, we don't want to adopt snyk, which requires a token, provides an extra dashboard etc. +# Most likely, snyk would be redundant with trivy. + +jobs: + analysis: + name: Vulnerability scan + runs-on: ubuntu-latest + permissions: + contents: read + security-events: write + steps: + - + uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + with: + persist-credentials: false + - + name: Vulnerability scan by trivy + uses: aquasecurity/trivy-action@b6643a29fecd7f34b3597bc6acb0a98b03d33ff8 # v0.33.1 + with: + scan-type: repo + format: sarif + hide-progress: false + output: trivy-code-report.sarif + scanners: vuln,secret + exit-code: 0 + - + name: Upload trivy findings to code scanning dashboard + uses: github/codeql-action/upload-sarif@014f16e7ab1402f30e7c3329d33797e7948572db # v4.31.3 + with: + category: trivy + sarif_file: trivy-code-report.sarif + + govulnscan: + name: go vulnerability scan + runs-on: ubuntu-latest + permissions: + contents: read + security-events: write + steps: + - + id: govulncheck + uses: golang/govulncheck-action@b625fbe08f3bccbe446d94fbf87fcc875a4f50ee # v1.0.4 + with: + output-format: sarif + output-file: govulnscan-report.sarif + - + name: Upload govulnscan findings to code scanning dashboard + uses: github/codeql-action/upload-sarif@014f16e7ab1402f30e7c3329d33797e7948572db # v4.31.3 + with: + category: govulnscan + sarif_file: govulnscan-report.sarif diff --git a/.github/workflows/filter.sed b/.github/workflows/scripts/filter.sed similarity index 100% rename from .github/workflows/filter.sed rename to .github/workflows/scripts/filter.sed diff --git a/.github/workflows/merge.jq b/.github/workflows/scripts/merge.jq similarity index 100% rename from .github/workflows/merge.jq rename to .github/workflows/scripts/merge.jq diff --git a/README.md b/README.md index 9631908..44e5be7 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,42 @@ -# ci-workflows[![Build Status](https://github.com/go-openapi/ci-workflows/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/ci-workflows/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/ci-workflows/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/ci-workflows) +# ci-workflows -[![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) -[![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/ci-workflows/master/LICENSE) -[![Go Reference](https://pkg.go.dev/badge/github.com/go-openapi/ci-workflows.svg)](https://pkg.go.dev/github.com/go-openapi/ci-workflows) -[![Go Report Card](https://goreportcard.com/badge/github.com/go-openapi/ci-workflows)](https://goreportcard.com/report/github.com/go-openapi/ci-workflows) + +[![Tests][test-badge]][test-url] [![Coverage][cov-badge]][cov-url] [![CI vuln scan][vuln-scan-badge]][vuln-scan-url] [![CodeQL][codeql-badge]][codeql-url] + + + +[![Release][release-badge]][release-url] [![Go Report Card][gocard-badge]][gocard-url] [![CodeFactor Grade][codefactor-badge]][codefactor-url] [![License][license-badge]][license-url] + + + +[![GoDoc][godoc-badge]][godoc-url] [![go version][goversion-badge]][goversion-url] ![Top language][top-badge] ![Commits since latest release][commits-badge] + +--- Common Continuous Integration (`CI`) workflows and setup for go-openapi repos. * shared github action workflows -* shared `dependabot` configuration (TODO) +* shared `dependabot` configuration (**BLOCKED**) * shared `golangci-lint` configuration (**BLOCKED**) -> NOTE: at this moment, it is difficult to share the golangci-lint config, -> so that one is not shared yet. +## Status + +Unreleased. + +Initial setup. Content may evolve with breaking changes. + +> NOTE: at this moment, it is difficult to share the dependabot and golangci-lint configurations, +> so these are not shared yet. + +## Basic usage ## Motivation -It took a while, but we eventually managed to align all checks, tests and +It took a while (well a something like 10 years...), but we eventually managed to align all checks, tests and dependabot rules declared in the family of go-openapi repos. Now we'd like to be able to maintain, enrich and improve these checks without -worrying too much about the burden to replicate it about a dozen times. +worrying too much about the burden of replicating it about a dozen times. ## Contemplated enhancements @@ -52,3 +68,55 @@ In no particular order: * [ ] doc: experiment LLM from github model, using embeddings ( -> * [ ] issues: experiment LLM from github model, using embeddings ( -> show related issues) * [ ] github pages w/ hugo (like go-swagger, experiment another theme and json data) + +## Change log + +See + +## Licensing + +This content ships under the [SPDX-License-Identifier: Apache-2.0](./LICENSE). + + + +## Other documentation + +* [All-time contributors](./CONTRIBUTORS.md) +* [Contributing guidelines](.github/CONTRIBUTING.md) +* [Maintainers documentation](docs/MAINTAINERS.md) +* [Code style](docs/STYLE.md) + + +[test-badge]: https://github.com/go-openapi/ci-workflows/actions/workflows/go-test.yml/badge.svg +[test-url]: https://github.com/go-openapi/ci-workflows/actions/workflows/go-test.yml +[cov-badge]: https://codecov.io/gh/go-openapi/ci-workflows/branch/master/graph/badge.svg +[cov-url]: https://codecov.io/gh/go-openapi/ci-workflows +[vuln-scan-badge]: https://github.com/go-openapi/ci-workflows/actions/workflows/scanner.yml/badge.svg +[vuln-scan-url]: https://github.com/go-openapi/ci-workflows/actions/workflows/scanner.yml +[codeql-badge]: https://github.com/go-openapi/ci-workflows/actions/workflows/codeql.yml/badge.svg +[codeql-url]: https://github.com/go-openapi/ci-workflows/actions/workflows/codeql.yml + +[release-badge]: https://badge.fury.io/go/github.com%2Fgo-openapi%2Fci-workflows.svg +[release-url]: https://badge.fury.io/go/github.com%2Fgo-openapi%2Fci-workflows + +[gocard-badge]: https://goreportcard.com/badge/github.com/go-openapi/ci-workflows +[gocard-url]: https://goreportcard.com/report/github.com/go-openapi/ci-workflows +[codefactor-badge]: https://img.shields.io/codefactor/grade/github/go-openapi/ci-workflows +[codefactor-url]: https://www.codefactor.io/repository/github/go-openapi/ci-workflows + +[doc-badge]: https://img.shields.io/badge/doc-site-blue?link=https%3A%2F%2Fgoswagger.io%2Fgo-openapi%2F +[doc-url]: https://goswagger.io/go-openapi +[godoc-badge]: https://pkg.go.dev/badge/github.com/go-openapi/ci-workflows +[godoc-url]: http://pkg.go.dev/github.com/go-openapi/ci-workflows +[slack-badge]: https://slackin.goswagger.io/badge.svg +[slack-url]: https://slackin.goswagger.io + +[license-badge]: http://img.shields.io/badge/license-Apache%20v2-orange.svg +[license-url]: https://github.com/go-openapi/ci-workflows/?tab=Apache-2.0-1-ov-file#readme + +[goversion-badge]: https://img.shields.io/github/go-mod/go-version/go-openapi/ci-workflows +[goversion-url]: https://github.com/go-openapi/ci-workflows/blob/master/go.mod +[top-badge]: https://img.shields.io/github/languages/top/go-openapi/ci-workflows +[commits-badge]: https://img.shields.io/github/commits-since/go-openapi/ci-workflows/latest diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..2a7b6f0 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,19 @@ +# Security Policy + +This policy outlines the commitment and practices of the go-openapi maintainers regarding security. + +## Supported Versions + +| Version | Supported | +| ------- | ------------------ | +| 0.22.x | :white_check_mark: | + +## Reporting a vulnerability + +If you become aware of a security vulnerability that affects the current repository, +please report it privately to the maintainers. + +Please follow the instructions provided by github to +[Privately report a security vulnerability](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability#privately-reporting-a-security-vulnerability). + +TL;DR: on Github, navigate to the project's "Security" tab then click on "Report a vulnerability". diff --git a/config-templates/.cliff.toml b/config-templates/.cliff.toml new file mode 100644 index 0000000..702629f --- /dev/null +++ b/config-templates/.cliff.toml @@ -0,0 +1,181 @@ +# git-cliff ~ configuration file +# https://git-cliff.org/docs/configuration + +[changelog] +header = """ +""" + +footer = """ + +----- + +**[{{ remote.github.repo }}]({{ self::remote_url() }}) license terms** + +[![License][license-badge]][license-url] + +[license-badge]: http://img.shields.io/badge/license-Apache%20v2-orange.svg +[license-url]: {{ self::remote_url() }}/?tab=Apache-2.0-1-ov-file#readme + +{%- macro remote_url() -%} + https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }} +{%- endmacro -%} +""" + +body = """ +{%- if version %} +## [{{ version | trim_start_matches(pat="v") }}]({{ self::remote_url() }}/tree/{{ version }}) - {{ timestamp | date(format="%Y-%m-%d") }} +{%- else %} +## [unreleased] +{%- endif %} +{%- if message %} + {%- raw %}\n{% endraw %} +{{ message }} + {%- raw %}\n{% endraw %} +{%- endif %} +{%- if version %} + {%- if previous.version %} + +**Full Changelog**: <{{ self::remote_url() }}/compare/{{ previous.version }}...{{ version }}> + {%- endif %} +{%- else %} + {%- raw %}\n{% endraw %} +{%- endif %} + +{%- if statistics %}{% if statistics.commit_count %} + {%- raw %}\n{% endraw %} +{{ statistics.commit_count }} commits in this release. + {%- raw %}\n{% endraw %} +{%- endif %}{% endif %} +----- + +{%- for group, commits in commits | group_by(attribute="group") %} + {%- raw %}\n{% endraw %} +### {{ group | upper_first }} + {%- raw %}\n{% endraw %} + {%- for commit in commits %} + {%- if commit.remote.pr_title %} + {%- set commit_message = commit.remote.pr_title %} + {%- else %} + {%- set commit_message = commit.message %} + {%- endif %} +* {{ commit_message | split(pat="\n") | first | trim }} + {%- if commit.remote.username %} +{%- raw %} {% endraw %}by [@{{ commit.remote.username }}](https://github.com/{{ commit.remote.username }}) + {%- endif %} + {%- if commit.remote.pr_number %} +{%- raw %} {% endraw %}in [#{{ commit.remote.pr_number }}]({{ self::remote_url() }}/pull/{{ commit.remote.pr_number }}) + {%- endif %} +{%- raw %} {% endraw %}[...]({{ self::remote_url() }}/commit/{{ commit.id }}) + {%- endfor %} +{%- endfor %} + +{%- if github %} +{%- raw %}\n{% endraw -%} + {%- set all_contributors = github.contributors | length %} + {%- if github.contributors | filter(attribute="username", value="dependabot[bot]") | length < all_contributors %} +----- + +### People who contributed to this release + {% endif %} + {%- for contributor in github.contributors | filter(attribute="username") | sort(attribute="username") %} + {%- if contributor.username != "dependabot[bot]" and contributor.username != "github-actions[bot]" %} +* [@{{ contributor.username }}](https://github.com/{{ contributor.username }}) + {%- endif %} + {%- endfor %} + + {% if github.contributors | filter(attribute="is_first_time", value=true) | length != 0 %} +----- + {%- raw %}\n{% endraw %} + +### New Contributors + {%- endif %} + + {%- for contributor in github.contributors | filter(attribute="is_first_time", value=true) %} + {%- if contributor.username != "dependabot[bot]" and contributor.username != "github-actions[bot]" %} +* @{{ contributor.username }} made their first contribution + {%- if contributor.pr_number %} + in [#{{ contributor.pr_number }}]({{ self::remote_url() }}/pull/{{ contributor.pr_number }}) \ + {%- endif %} + {%- endif %} + {%- endfor %} +{%- endif %} + +{%- raw %}\n{% endraw %} + +{%- macro remote_url() -%} + https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }} +{%- endmacro -%} +""" +# Remove leading and trailing whitespaces from the changelog's body. +trim = true +# Render body even when there are no releases to process. +render_always = true +# An array of regex based postprocessors to modify the changelog. +postprocessors = [ + # Replace the placeholder with a URL. + #{ pattern = '', replace = "https://github.com/orhun/git-cliff" }, +] +# output file path +# output = "test.md" + +[git] +# Parse commits according to the conventional commits specification. +# See https://www.conventionalcommits.org +conventional_commits = false +# Exclude commits that do not match the conventional commits specification. +filter_unconventional = false +# Require all commits to be conventional. +# Takes precedence over filter_unconventional. +require_conventional = false +# Split commits on newlines, treating each line as an individual commit. +split_commits = false +# An array of regex based parsers to modify commit messages prior to further processing. +commit_preprocessors = [ + # Replace issue numbers with link templates to be updated in `changelog.postprocessors`. + #{ pattern = '\((\w+\s)?#([0-9]+)\)', replace = "([#${2}](/issues/${2}))"}, + # Check spelling of the commit message using https://github.com/crate-ci/typos. + # If the spelling is incorrect, it will be fixed automatically. + #{ pattern = '.*', replace_command = 'typos --write-changes -' } +] +# Prevent commits that are breaking from being excluded by commit parsers. +protect_breaking_commits = false +# An array of regex based parsers for extracting data from the commit message. +# Assigns commits to groups. +# Optionally sets the commit's scope and can decide to exclude commits from further processing. +commit_parsers = [ + { message = "^[Cc]hore\\([Rr]elease\\): prepare for", skip = true }, + { message = "(^[Mm]erge)|([Mm]erge conflict)", skip = true }, + { field = "author.name", pattern = "dependabot*", group = "Updates" }, + { message = "([Ss]ecurity)|([Vv]uln)", group = "Security" }, + { body = "(.*[Ss]ecurity)|([Vv]uln)", group = "Security" }, + { message = "([Cc]hore\\(lint\\))|(style)|(lint)|(codeql)|(golangci)", group = "Code quality" }, + { message = "(^[Dd]oc)|((?i)readme)|(badge)|(typo)|(documentation)", group = "Documentation" }, + { message = "(^[Ff]eat)|(^[Ee]nhancement)", group = "Implemented enhancements" }, + { message = "(^ci)|(\\(ci\\))|(fixup\\s+ci)|(fix\\s+ci)|(license)|(example)", group = "Miscellaneous tasks" }, + { message = "^test", group = "Testing" }, + { message = "(^fix)|(panic)", group = "Fixed bugs" }, + { message = "(^refact)|(rework)", group = "Refactor" }, + { message = "(^[Pp]erf)|(performance)", group = "Performance" }, + { message = "(^[Cc]hore)", group = "Miscellaneous tasks" }, + { message = "^[Rr]evert", group = "Reverted changes" }, + { message = "(upgrade.*?go)|(go\\s+version)", group = "Updates" }, + { message = ".*", group = "Other" }, +] +# Exclude commits that are not matched by any commit parser. +filter_commits = false +# An array of link parsers for extracting external references, and turning them into URLs, using regex. +link_parsers = [] +# Include only the tags that belong to the current branch. +use_branch_tags = false +# Order releases topologically instead of chronologically. +topo_order = false +# Order releases topologically instead of chronologically. +topo_order_commits = true +# Order of commits in each group/release within the changelog. +# Allowed values: newest, oldest +sort_commits = "newest" +# Process submodules commits +recurse_submodules = false + +#[remote.github] +#owner = "go-openapi" diff --git a/config-templates/.editorconfig b/config-templates/.editorconfig new file mode 100644 index 0000000..3152da6 --- /dev/null +++ b/config-templates/.editorconfig @@ -0,0 +1,26 @@ +# top-most EditorConfig file +root = true + +# Unix-style newlines with a newline ending every file +[*] +end_of_line = lf +insert_final_newline = true +indent_style = space +indent_size = 2 +trim_trailing_whitespace = true + +# Set default charset +[*.{js,py,go,scala,rb,java,html,css,less,sass,md}] +charset = utf-8 + +# Tab indentation (no size specified) +[*.go] +indent_style = tab + +[*.md] +trim_trailing_whitespace = false + +# Matches the exact files either package.json or .travis.yml +[{package.json,.travis.yml}] +indent_style = space +indent_size = 2 diff --git a/config-templates/.golangci.yml b/config-templates/.golangci.yml new file mode 100644 index 0000000..fdae591 --- /dev/null +++ b/config-templates/.golangci.yml @@ -0,0 +1,66 @@ +version: "2" +linters: + default: all + disable: + - depguard + - funlen + - godox + - exhaustruct + - nlreturn + - nonamedreturns + - noinlineerr + - paralleltest + - recvcheck + - testpackage + - tparallel + - varnamelen + - whitespace + - wrapcheck + - wsl + - wsl_v5 + settings: + dupl: + threshold: 200 + goconst: + min-len: 2 + min-occurrences: 3 + cyclop: + max-complexity: 20 + gocyclo: + min-complexity: 20 + exhaustive: + default-signifies-exhaustive: true + default-case-required: true + lll: + line-length: 180 + exclusions: + generated: lax + presets: + - comments + - common-false-positives + - legacy + - std-error-handling + paths: + - third_party$ + - builtin$ + - examples$ +formatters: + enable: + - gofmt + - goimports + - gofumpt + exclusions: + generated: lax + paths: + - third_party$ + - builtin$ + - examples$ +issues: + # Maximum issues count per one linter. + # Set to 0 to disable. + # Default: 50 + max-issues-per-linter: 0 + # Maximum count of issues with the same text. + # Set to 0 to disable. + # Default: 3 + max-same-issues: 0 diff --git a/doc-templates/.github/CONTRIBUTING.md b/doc-templates/.github/CONTRIBUTING.md new file mode 100644 index 0000000..b02b363 --- /dev/null +++ b/doc-templates/.github/CONTRIBUTING.md @@ -0,0 +1,214 @@ +## Contribution Guidelines + +You'll find below general guidelines, which mostly correspond to standard practices for open sourced repositories. + +>**TL;DR** +> +> If you're already an experience go developer on github, then you should just feel at home with us +> and you may well skip the rest of this document. +> +> You'll essentially find the usual guideline for a go library project on github. + +These guidelines are general to all libraries published on github by the `go-openapi` organization. + +You'll find more detailed (or repo-specific) instructions in the [maintainer's docs](../docs). + +## How can I contribute? + +There are many ways in which you can contribute. Here are a few ideas: + + * Reporting Issues / Bugs + * Suggesting Improvements + * Code + * bug fixes and new features that are within the main project scope + * improving test coverage + * addressing code quality issues + * Documentation + * Art work that makes the project look great + +## Questions & issues + +### Asking questions + +You may inquire about anything about this library by reporting a "Question" issue on github. + +### Reporting issues + +Reporting a problem with our libraries _is_ a valuable contribution. + +You can do this on the github issues page of this repository. + +Please be as specific as possible when describing your issue. + +Whenever relevant, please provide information about your environment (go version, OS). + +Adding a code snippet to reproduce the issue is great, and as a big time saver for maintainers. + +### Triaging issues + +You can help triage issues which may include: + +* reproducing bug reports +* asking for important information, such as version numbers or reproduction instructions +* answering questions and sharing your insight in issue comments + +## Code contributions + +### Pull requests are always welcome + +We are always thrilled to receive pull requests, and we do our best to +process them as fast as possible. + +Not sure if that typo is worth a pull request? Do it! We will appreciate it. + +If your pull request is not accepted on the first try, don't be discouraged! +If there's a problem with the implementation, hopefully you received feedback on what to improve. + +If you have a lot of ideas or a lot of issues to solve, try to refrain a bit and post focused +pull requests. +Think that they must be reviewed by a maintainer and it is easy to lost track of things on big PRs. + +We're trying very hard to keep the go-openapi packages lean and focused. +These packages constitute a toolkit: it won't do everything for everybody out of the box, +but everybody can use it to do just about everything related to OpenAPI. + +This means that we might decide against incorporating a new feature. + +However, there might be a way to implement that feature *on top of* our libraries. + +### Environment + +You just need a `go` compiler to be installed. No special tools are needed to work with our libraries. + +The go compiler version required is always the old stable (latest minor go version - 1). + +If you're already used to work with `go` you should already have everything in place. + +Although not required, you'll be certainly more productive with a local installation of `golangci-lint`, +the meta-linter our CI uses. + +If you don't have it, you may install it like so: + +```sh +go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest +``` + +### Conventions + +#### Git flow + +Fork the repo and make changes to your fork in a feature branch. + +To submit a pull request, push your branch to your fork (e.g. `upstream` remote): +github will propose to open a pull request on the original repository. + +Typically you'd follow some common naming conventions: + +- if it's a bugfix branch, name it `fix/XXX-something`where XXX is the number of the + issue on github +- if it's a feature branch, create an enhancement issue to announce your + intentions, and name it `feature/XXX-something` where XXX is the number of the issue. + +> NOTE: we don't enforce naming conventions on branches: it's your fork after all. + +#### Tests + +Submit unit tests for your changes. + +Go has a great built-in test framework ; use it! + +Take a look at existing tests for inspiration, and run the full test suite on your branch +before submitting a pull request. + +Our CI measures test coverage and the test coverage of every patch. +Although not a blocking step - because there are so many special cases - +this is an indicator that maintainers consider when approving a PR. + +Please try your best to cover about 80% of your patch. + +#### Code style + +You may read our stance on code style [there](../docs/STYLE.md). + +#### Documentation + +Don't forget to update the documentation when creating or modifying features. + +Most documentation for this library is directly found in code as comments for godoc. + +The documentation for the go-openapi packages is published on the public go docs site: + + + +Check your documentation changes for clarity, concision, and correctness. + +If you want to assess the rendering of your changes when published to `pkg.go.dev`, you may +want to install the `pkgsite` tool proposed by `golang.org`. + +```sh +go install golang.org/x/pkgsite/cmd/pkgsite@latest +``` + +Then run on the repository folder: +```sh +pkgsite . +``` + +This wil run a godoc server locally where you may see the documentation generated from your local repository. + +#### Commit messages + +Pull requests descriptions should be as clear as possible and include a +reference to all the issues that they address. + +Pull requests must not contain commits from other users or branches. + +Commit messages are not required to follow the "conventional commit" rule, but it's certainly a good +thing to follow this guidelinea (e.g. "fix: blah blah", "ci: did this", "feat: did that" ...). + +The title in your commit message is used directly to produce our release notes: try to keep them neat. + +The commit message body should detail your changes. + +If an issue should be closed by a commit, please add this reference in the commit body: + +``` +* fixes #{issue number} +``` + +#### Code review + +Code review comments may be added to your pull request. + +Discuss, then make the suggested modifications and push additional commits to your feature branch. + +Be sure to post a comment after pushing. The new commits will show up in the pull +request automatically, but the reviewers will not be notified unless you comment. + +Before the pull request is merged, +**make sure that you squash your commits into logical units of work** +using `git rebase -i` and `git push -f`. + +After every commit the test suite should be passing. + +Include documentation changes in the same commit so that a revert would remove all traces of the feature or fix. + +#### Sign your work + +The sign-off is a simple line at the end of your commit message, +which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. + +We require the simple DCO below with an email signing your commit. +PGP-signed commit are greatly appreciated but not required. + +The rules are pretty simple: + +* read our [DCO](./DCO.md) (from [developercertificate.org](http://developercertificate.org/)) +* if you agree with these terms, then you just add a line to every git commit message + + Signed-off-by: Joe Smith + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign off when creating the git commit via `git commit -s`. diff --git a/doc-templates/.github/DCO.md b/doc-templates/.github/DCO.md new file mode 100644 index 0000000..e168dc4 --- /dev/null +++ b/doc-templates/.github/DCO.md @@ -0,0 +1,40 @@ + # Developer's Certificate of Origin + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` diff --git a/doc-templates/CODE_OF_CONDUCT.md b/doc-templates/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..9322b06 --- /dev/null +++ b/doc-templates/CODE_OF_CONDUCT.md @@ -0,0 +1,74 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at ivan+abuse@flanders.co.nz. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ diff --git a/doc-templates/README.md b/doc-templates/README.md new file mode 100644 index 0000000..2cf2fb5 --- /dev/null +++ b/doc-templates/README.md @@ -0,0 +1,89 @@ +# {{ .Repo }} + + +[![Tests][test-badge]][test-url] [![Coverage][cov-badge]][cov-url] [![CI vuln scan][vuln-scan-badge]][vuln-scan-url] [![CodeQL][codeql-badge]][codeql-url] + + + +[![Release][release-badge]][release-url] [![Go Report Card][gocard-badge]][gocard-url] [![CodeFactor Grade][codefactor-badge]][codefactor-url] [![License][license-badge]][license-url] + + + +[![GoDoc][godoc-badge]][godoc-url] [![go version][goversion-badge]][goversion-url] ![Top language][top-badge] ![Commits since latest release][commits-badge] + +--- + +{{ .Title }} + +## Status + +{{ .Status }}. + +## Import this library in your project + +```cmd +go get github.com/{{ .Owner }}/{{ .Repo }} +``` + +## Basic usage + +## Change log + +See + + + +## Licensing + +This library ships under the [SPDX-License-Identifier: Apache-2.0](./LICENSE). + + + + + +## Other documentation + +* [All-time contributors](./CONTRIBUTORS.md) +* [Contributing guidelines](.github/CONTRIBUTING.md) +* [Maintainers documentation](docs/MAINTAINERS.md) +* [Code style](docs/STYLE.md) + + +[test-badge]: https://github.com/{{ .Owner }}/{{ .Repo }}/actions/workflows/go-test.yml/badge.svg +[test-url]: https://github.com/{{ .Owner }}/{{ .Repo }}/actions/workflows/go-test.yml +[cov-badge]: https://codecov.io/gh/{{ .Owner }}/{{ .Repo }}/branch/master/graph/badge.svg +[cov-url]: https://codecov.io/gh/{{ .Owner }}/{{ .Repo }} +[vuln-scan-badge]: https://github.com/{{ .Owner }}/{{ .Repo }}/actions/workflows/scanner.yml/badge.svg +[vuln-scan-url]: https://github.com/{{ .Owner }}/{{ .Repo }}/actions/workflows/scanner.yml +[codeql-badge]: https://github.com/{{ .Owner }}/{{ .Repo }}/actions/workflows/codeql.yml/badge.svg +[codeql-url]: https://github.com/{{ .Owner }}/{{ .Repo }}/actions/workflows/codeql.yml + +[release-badge]: https://badge.fury.io/go/github.com%2F{{ .Owner }}%2F{{ .Repo }}.svg +[release-url]: https://badge.fury.io/go/github.com%2F{{ .Owner }}%2F{{ .Repo }} + +[gocard-badge]: https://goreportcard.com/badge/github.com/{{ .Owner }}/{{ .Repo }} +[gocard-url]: https://goreportcard.com/report/github.com/{{ .Owner }}/{{ .Repo }} +[codefactor-badge]: https://img.shields.io/codefactor/grade/github/{{ .Owner }}/{{ .Repo }} +[codefactor-url]: https://www.codefactor.io/repository/github/{{ .Owner }}/{{ .Repo }} + +[doc-badge]: https://img.shields.io/badge/doc-site-blue?link=https%3A%2F%2Fgoswagger.io%2F{{ .Owner }}%2F +[doc-url]: https://goswagger.io/{{ .Owner }} +[godoc-badge]: https://pkg.go.dev/badge/github.com/{{ .Owner }}/{{ .Repo }} +[godoc-url]: http://pkg.go.dev/github.com/{{ .Owner }}/{{ .Repo }} +[slack-badge]: https://slackin.goswagger.io/badge.svg +[slack-url]: https://slackin.goswagger.io + +[license-badge]: http://img.shields.io/badge/license-Apache%20v2-orange.svg +[license-url]: https://github.com/{{ .Owner }}/{{ .Repo }}/?tab=Apache-2.0-1-ov-file#readme + +[goversion-badge]: https://img.shields.io/github/go-mod/go-version/{{ .Owner }}/{{ .Repo }} +[goversion-url]: https://github.com/{{ .Owner }}/{{ .Repo }}/blob/master/go.mod +[top-badge]: https://img.shields.io/github/languages/top/{{ .Owner }}/{{ .Repo }} +[commits-badge]: https://img.shields.io/github/commits-since/{{ .Owner }}/{{ .Repo }}/latest diff --git a/doc-templates/SECURITY.md b/doc-templates/SECURITY.md new file mode 100644 index 0000000..2a7b6f0 --- /dev/null +++ b/doc-templates/SECURITY.md @@ -0,0 +1,19 @@ +# Security Policy + +This policy outlines the commitment and practices of the go-openapi maintainers regarding security. + +## Supported Versions + +| Version | Supported | +| ------- | ------------------ | +| 0.22.x | :white_check_mark: | + +## Reporting a vulnerability + +If you become aware of a security vulnerability that affects the current repository, +please report it privately to the maintainers. + +Please follow the instructions provided by github to +[Privately report a security vulnerability](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability#privately-reporting-a-security-vulnerability). + +TL;DR: on Github, navigate to the project's "Security" tab then click on "Report a vulnerability". diff --git a/doc-templates/docs/MAINTAINERS.md b/doc-templates/docs/MAINTAINERS.md new file mode 100644 index 0000000..f83496b --- /dev/null +++ b/doc-templates/docs/MAINTAINERS.md @@ -0,0 +1,157 @@ +# Maintainer's guide + +## Repo structure + +Single go module. + +> **NOTE** +> +> Some `{{ .Owner }}` repos are mono-repos with multiple modules, +> with adapted CI workflows. + +## Repo configuration + +* default branch: master +* protected branches: master +* branch protection rules: + * require pull requests and approval + * required status checks: + - DCO (simple email sign-off) + - Lint + - tests completed +* auto-merge enabled (used for dependabot updates) + +## Continuous Integration + +### Code Quality checks + +* meta-linter: golangci-lint +* linter config: [`.golangci.yml`](../.golangci.yml) (see our [posture](./STYLE.md) on linters) + +* Code quality assessment: [CodeFactor](https://www.codefactor.io/dashboard) +* Code quality badges + * go report card: + * CodeFactor: + +> **NOTES** +> +> codefactor inherits roles from github. There is no need to create a dedicated account. +> +> The codefactor app is installed at the organization level (`github.com/{{ .Owner }}`). +> +> There is no special token to setup in github for CI usage. + +### Testing + +* Test reports + * Uploaded to codecov: +* Test coverage reports + * Uploaded to codecov: + +* Fuzz testing + * Fuzz tests are handled separately by CI and may reuse a cached version of the fuzzing corpus. + At this moment, cache may not be shared between feature branches or feature branch and master. + The minimized corpus produced on failure is uploaded as an artifact and should be added manually + to `testdata/fuzz/...`. + +Coverage threshold status is informative and not blocking. +This is because the thresholds are difficult to tune and codecov oftentimes reports false negatives +or may fail to upload coverage. + +All tests use our fork of `stretchr/testify`: `github.com/{{ .Owner }}/testify`. +This allows for minimal test dependencies. + +> **NOTES** +> +> codecov inherits roles from github. There is no need to create a dedicated account. +> However, there is only 1 maintainer allowed to be the admin of the organization on codecov +> with their free plan. +> +> The codecov app is installed at the organization level (`github.com/{{ .Owner }}`). +> +> There is no special token to setup in github for CI usage. +> A organization-level token used to upload coverage and test reports is managed at codecov: +> no setup is required on github. + +### Automated updates + +* dependabot + * configuration: [`dependabot.yaml`](../.github/dependabot.yaml) + + Principle: + + * codecov applies updates and security patches to the github-actions and golang ecosystems. + * all updates from "trusted" dependencies (github actions, golang.org packages, {{ .Owner }} packages + are auto-merged if they successfully pass CI. + +* go version udpates + + Principle: + + * we support the 2 latest minor versions of the go compiler (`stable`, `oldstable`) + * `go.mod` should be updated (manually) whenever there is a new go minor release + (e.g. every 6 months). + +* contributors + * a [`CONTRIBUTORS.md`](../CONTRIBUTORS.md) file is updated weekly, with all-time contributors to the repository + * the `github-actions[bot]` posts a pull request to do that automatically + * at this moment, this pull request is not auto-approved/auto-merged (bot cannot approve its own PRs) + +### Vulnerability scanners + +There are 3 complementary scanners - obviously, there is some overlap, but each has a different focus. + +* github `CodeQL` +* `trivy` +* `govulnscan` + +None of these tools require an additional account or token. + +Github CodeQL configuration is set to "Advanced", so we may collect a CI status for this check (e.g. for badges). + +Scanners run on every commit to master and at least once a week. + +Reports are centralized in github security reports for code scanning tools. + +## Releases + +The release process is minimalist: + +* push a semver tag (i.e v{major}.{minor}.{patch}) to the master branch. +* the CI handles this to generate a github release with release notes + +* release notes generator: git-cliff +* configuration: [`cliff.toml`](../.cliff.toml) + +Tags are preferably PGP-signed. + +The tag message introduces the release notes (e.g. a summary of this release). + +The release notes generator does not assume that commits are necessarily "conventional commits". + +## Other files + +Standard documentation: + +* [`CONTRIBUTING.md`](../.github/CONTRIBUTING.md) guidelines +* [`DCO.md`](../.github/DCO.md) terms for first-time contributors to read +* [`CODE_OF_CONDUCT.md`](../CODE_OF_CONDUCT.md) +* [`SECURIY.md`](../SECURITY.md) policy: how to report vulnerabilities privately +* [`LICENSE`](../LICENSE) terms +* [`NOTICE`](../NOTICE) on supplementary license terms (original authors, copied code etc) + +Reference documentation (released): + +* [godoc](https://pkg.go/dev/{{ .Owner }}/{{ .Repo }}) + +## TODOs & other ideas + +A few things remain ahead to ease a bit a maintainer's job: + +* [ ] reuse CI workflows (e.g. in `github.com/{{ .Owner }}/workflows`) +* [ ] reusable actions with custom tools pinned (e.g. in `github.com/{{ .Owner }}/gh-actions`) +* [ ] open-source license checks +* [ ] auto-merge for CONTRIBUTORS.md (requires a github app to produce tokens) +* [ ] more automated code renovation / relinting work (possibly built with CLAUDE) +* [ ] organization-level documentation web site +* ... diff --git a/doc-templates/docs/STYLE.md b/doc-templates/docs/STYLE.md new file mode 100644 index 0000000..a82dad4 --- /dev/null +++ b/doc-templates/docs/STYLE.md @@ -0,0 +1,83 @@ +# Coding style at `go-openapi` + +> **TL;DR** +> +> Let's be honest: at `go-openapi` and `go-swagger` we've never been super-strict on code style etc. +> +> But perhaps now (2025) is the time to adopt a different stance. + +Even though our repos have been early adopters of `golangci-lint` years ago +(we used some other metalinter before), our decade-old codebase is only realigned to new rules from time to time. + +Now go-openapi and go-swagger make up a really large codebase, which is taxing to maintain and keep afloat. + +Code quality and the harmonization of rules have thus become things that we need now. + +## Meta-linter + +Universally formatted go code promotes ease of writing, reading, and maintenance. + +You should run `golangci-lint run` before committing your changes. + +Many editors have plugins that do that automatically. + +> We use the `golangci-lint` meta-linter. The configuration lies in [`.golangci.yml`](../.golangci.yml). +> You may read for additional reference. + +## Linting rules posture + +Thanks to go's original design, we developers don't have to waste much time arguing about code figures of style. + +However, the number of available linters has been growing to the point that we need to pick a choice. + +We enable all linters published by `golangci-lint` by default, then disable a few ones. + +Here are the reasons why they are disabled (update: Nov. 2025, `golangci-lint v2.6.1`): + +```yaml + disable: + - depguard # we don't want to configure rules to constrain import. That's the reviewer's job + - exhaustruct # we don't want to configure regexp's to check type name. That's the reviewer's job + - funlen # we accept cognitive complexity as a meaningful metric, but function length is relevant + - godox # we don't see any value in forbidding TODO's etc in code + - nlreturn # we usually apply this "blank line" rule to make code less compact. We just don't want to enforce it + - nonamedreturns # we don't see any valid reason why we couldn't used named returns + - noinlineerr # there is no value added forbidding inlined err + - paralleltest # we like parallel tests. We just don't want them to be enforced everywhere + - recvcheck # we like the idea of having pointer and non-pointer receivers + - testpackage # we like test packages. We just don't want them to be enforced everywhere + - tparallel # see paralleltest + - varnamelen # sometimes, we like short variables. The linter doesn't catch cases when a short name is good + - whitespace # no added value + - wrapcheck # although there is some sense with this linter's general idea, it produces too much noise + - wsl # no added value. Noise + - wsl_v5 # no added value. Noise +``` + +As you may see, we agree with the objectives of most linters, at least the principle they are supposed to enforce. +But all linters do not support fine-grained tuning to tolerate some cases and not some others. + +When this is possible, we enable linters with relaxed constraints: + +```yaml + settings: + dupl: + threshold: 200 # in a older code base such as ours, we have to be tolerant with a little redundancy + # Hopefully, we'll be able to gradually get rid of those. + goconst: + min-len: 2 + min-occurrences: 3 + cyclop: + max-complexity: 20 # the default is too low for most of our functions. 20 is a nicer trade-off + gocyclo: + min-complexity: 20 + exhaustive: # when using default in switch, this should be good enough + default-signifies-exhaustive: true + default-case-required: true + lll: + line-length: 180 # we just want to avoid extremely long lines. + # It is no big deal if a line or two don't fit on your terminal. +``` + +Final note: since we have switched to a forked version of `stretchr/testify`, +we no longer benefit from the great `testifylint` linter for tests. diff --git a/doc/README.md b/doc/README.md deleted file mode 100644 index 19577ee..0000000 --- a/doc/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# doc - -Documentation check and generation tools. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..9cc9f00 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,5 @@ +# Share workflows documentation + +** DRAFT ** + +Documentation check and generation tools. diff --git a/go.mod b/go.mod index dd46419..2891bf1 100644 --- a/go.mod +++ b/go.mod @@ -1,11 +1,5 @@ module github.com/go-openapi/ci-workflows -go 1.24.2 +go 1.24.0 -require github.com/stretchr/testify v1.11.1 - -require ( - github.com/davecgh/go-spew v1.1.1 // indirect - github.com/pmezard/go-difflib v1.0.0 // indirect - gopkg.in/yaml.v3 v3.0.1 // indirect -) +require github.com/go-openapi/testify/v2 v2.0.2 diff --git a/go.sum b/go.sum index c4c1710..1876434 100644 --- a/go.sum +++ b/go.sum @@ -1,10 +1,2 @@ -github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= -github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= -github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= -github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= -github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U= -github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U= -gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM= -gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= -gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= -gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= +github.com/go-openapi/testify/v2 v2.0.2 h1:X999g3jeLcoY8qctY/c/Z8iBHTbwLz7R2WXd6Ub6wls= +github.com/go-openapi/testify/v2 v2.0.2/go.mod h1:HCPmvFFnheKK2BuwSA0TbbdxJ3I16pjwMkYkP4Ywn54= diff --git a/sample/pkg/pkg_test.go b/sample/pkg/pkg_test.go index 6979d22..e381219 100644 --- a/sample/pkg/pkg_test.go +++ b/sample/pkg/pkg_test.go @@ -3,7 +3,7 @@ package pkg import ( "testing" - "github.com/stretchr/testify/assert" + "github.com/go-openapi/testify/v2/assert" ) func TestPkg(t *testing.T) { diff --git a/sample/sample_test.go b/sample/sample_test.go index b4f2063..e5adc7b 100644 --- a/sample/sample_test.go +++ b/sample/sample_test.go @@ -3,7 +3,7 @@ package sample import ( "testing" - "github.com/stretchr/testify/require" + "github.com/go-openapi/testify/v2/require" ) func TestSample(t *testing.T) { From 7f785da23438cb8a5716f000eb59237254ebc4a3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20BIDON?= Date: Sat, 29 Nov 2025 23:46:25 +0100 Subject: [PATCH 27/28] complete rework MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: FrÊdÊric BIDON --- .cliff.toml | 181 ++++++ .github/workflows/README.md | 58 ++ .github/workflows/auto-merge.yml | 62 +-- .github/workflows/bump-release.yml | 133 +++++ .github/workflows/codeql.yml | 6 +- .github/workflows/collect-coverage.yml | 39 ++ .github/workflows/collect-reports.yml | 115 ++++ .github/workflows/contributors.yml | 48 +- .github/workflows/doc-update.yml | 524 ------------------ .github/workflows/fuzz-test.yml | 123 ++++ .github/workflows/gists.md | 11 - .github/workflows/go-test.yml | 232 +------- .github/workflows/local-auto-merge.yml | 10 +- .github/workflows/local-bump-release.yml | 53 ++ .github/workflows/local-codeql.yml | 2 +- .github/workflows/local-go-test.yml | 12 +- .github/workflows/local-release.yml | 2 + .github/workflows/local-tag-release.yml | 24 + .github/workflows/markdown-changed.yml | 33 ++ .github/workflows/release.yml | 42 +- .github/workflows/scanner.yml | 2 +- .github/workflows/tag-release.yml | 29 + README.md | 6 +- doc-templates/README.md | 8 +- experimental/go-test-monorepo.yml | 156 ++++++ .../local-doc-update.yml | 0 experimental/local-monorepo-go-test.yml | 19 + experimental/markdown-lint.yml | 272 +++++++++ experimental/markdown-spellcheck.yml | 270 +++++++++ .../workflows => experimental}/pr-comment.yml | 0 30 files changed, 1646 insertions(+), 826 deletions(-) create mode 100644 .cliff.toml create mode 100644 .github/workflows/README.md create mode 100644 .github/workflows/bump-release.yml create mode 100644 .github/workflows/collect-coverage.yml create mode 100644 .github/workflows/collect-reports.yml delete mode 100644 .github/workflows/doc-update.yml create mode 100644 .github/workflows/fuzz-test.yml delete mode 100644 .github/workflows/gists.md create mode 100644 .github/workflows/local-bump-release.yml create mode 100644 .github/workflows/local-tag-release.yml create mode 100644 .github/workflows/markdown-changed.yml create mode 100644 .github/workflows/tag-release.yml create mode 100644 experimental/go-test-monorepo.yml rename {.github/workflows => experimental}/local-doc-update.yml (100%) create mode 100644 experimental/local-monorepo-go-test.yml create mode 100644 experimental/markdown-lint.yml create mode 100644 experimental/markdown-spellcheck.yml rename {.github/workflows => experimental}/pr-comment.yml (100%) diff --git a/.cliff.toml b/.cliff.toml new file mode 100644 index 0000000..702629f --- /dev/null +++ b/.cliff.toml @@ -0,0 +1,181 @@ +# git-cliff ~ configuration file +# https://git-cliff.org/docs/configuration + +[changelog] +header = """ +""" + +footer = """ + +----- + +**[{{ remote.github.repo }}]({{ self::remote_url() }}) license terms** + +[![License][license-badge]][license-url] + +[license-badge]: http://img.shields.io/badge/license-Apache%20v2-orange.svg +[license-url]: {{ self::remote_url() }}/?tab=Apache-2.0-1-ov-file#readme + +{%- macro remote_url() -%} + https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }} +{%- endmacro -%} +""" + +body = """ +{%- if version %} +## [{{ version | trim_start_matches(pat="v") }}]({{ self::remote_url() }}/tree/{{ version }}) - {{ timestamp | date(format="%Y-%m-%d") }} +{%- else %} +## [unreleased] +{%- endif %} +{%- if message %} + {%- raw %}\n{% endraw %} +{{ message }} + {%- raw %}\n{% endraw %} +{%- endif %} +{%- if version %} + {%- if previous.version %} + +**Full Changelog**: <{{ self::remote_url() }}/compare/{{ previous.version }}...{{ version }}> + {%- endif %} +{%- else %} + {%- raw %}\n{% endraw %} +{%- endif %} + +{%- if statistics %}{% if statistics.commit_count %} + {%- raw %}\n{% endraw %} +{{ statistics.commit_count }} commits in this release. + {%- raw %}\n{% endraw %} +{%- endif %}{% endif %} +----- + +{%- for group, commits in commits | group_by(attribute="group") %} + {%- raw %}\n{% endraw %} +### {{ group | upper_first }} + {%- raw %}\n{% endraw %} + {%- for commit in commits %} + {%- if commit.remote.pr_title %} + {%- set commit_message = commit.remote.pr_title %} + {%- else %} + {%- set commit_message = commit.message %} + {%- endif %} +* {{ commit_message | split(pat="\n") | first | trim }} + {%- if commit.remote.username %} +{%- raw %} {% endraw %}by [@{{ commit.remote.username }}](https://github.com/{{ commit.remote.username }}) + {%- endif %} + {%- if commit.remote.pr_number %} +{%- raw %} {% endraw %}in [#{{ commit.remote.pr_number }}]({{ self::remote_url() }}/pull/{{ commit.remote.pr_number }}) + {%- endif %} +{%- raw %} {% endraw %}[...]({{ self::remote_url() }}/commit/{{ commit.id }}) + {%- endfor %} +{%- endfor %} + +{%- if github %} +{%- raw %}\n{% endraw -%} + {%- set all_contributors = github.contributors | length %} + {%- if github.contributors | filter(attribute="username", value="dependabot[bot]") | length < all_contributors %} +----- + +### People who contributed to this release + {% endif %} + {%- for contributor in github.contributors | filter(attribute="username") | sort(attribute="username") %} + {%- if contributor.username != "dependabot[bot]" and contributor.username != "github-actions[bot]" %} +* [@{{ contributor.username }}](https://github.com/{{ contributor.username }}) + {%- endif %} + {%- endfor %} + + {% if github.contributors | filter(attribute="is_first_time", value=true) | length != 0 %} +----- + {%- raw %}\n{% endraw %} + +### New Contributors + {%- endif %} + + {%- for contributor in github.contributors | filter(attribute="is_first_time", value=true) %} + {%- if contributor.username != "dependabot[bot]" and contributor.username != "github-actions[bot]" %} +* @{{ contributor.username }} made their first contribution + {%- if contributor.pr_number %} + in [#{{ contributor.pr_number }}]({{ self::remote_url() }}/pull/{{ contributor.pr_number }}) \ + {%- endif %} + {%- endif %} + {%- endfor %} +{%- endif %} + +{%- raw %}\n{% endraw %} + +{%- macro remote_url() -%} + https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }} +{%- endmacro -%} +""" +# Remove leading and trailing whitespaces from the changelog's body. +trim = true +# Render body even when there are no releases to process. +render_always = true +# An array of regex based postprocessors to modify the changelog. +postprocessors = [ + # Replace the placeholder with a URL. + #{ pattern = '', replace = "https://github.com/orhun/git-cliff" }, +] +# output file path +# output = "test.md" + +[git] +# Parse commits according to the conventional commits specification. +# See https://www.conventionalcommits.org +conventional_commits = false +# Exclude commits that do not match the conventional commits specification. +filter_unconventional = false +# Require all commits to be conventional. +# Takes precedence over filter_unconventional. +require_conventional = false +# Split commits on newlines, treating each line as an individual commit. +split_commits = false +# An array of regex based parsers to modify commit messages prior to further processing. +commit_preprocessors = [ + # Replace issue numbers with link templates to be updated in `changelog.postprocessors`. + #{ pattern = '\((\w+\s)?#([0-9]+)\)', replace = "([#${2}](/issues/${2}))"}, + # Check spelling of the commit message using https://github.com/crate-ci/typos. + # If the spelling is incorrect, it will be fixed automatically. + #{ pattern = '.*', replace_command = 'typos --write-changes -' } +] +# Prevent commits that are breaking from being excluded by commit parsers. +protect_breaking_commits = false +# An array of regex based parsers for extracting data from the commit message. +# Assigns commits to groups. +# Optionally sets the commit's scope and can decide to exclude commits from further processing. +commit_parsers = [ + { message = "^[Cc]hore\\([Rr]elease\\): prepare for", skip = true }, + { message = "(^[Mm]erge)|([Mm]erge conflict)", skip = true }, + { field = "author.name", pattern = "dependabot*", group = "Updates" }, + { message = "([Ss]ecurity)|([Vv]uln)", group = "Security" }, + { body = "(.*[Ss]ecurity)|([Vv]uln)", group = "Security" }, + { message = "([Cc]hore\\(lint\\))|(style)|(lint)|(codeql)|(golangci)", group = "Code quality" }, + { message = "(^[Dd]oc)|((?i)readme)|(badge)|(typo)|(documentation)", group = "Documentation" }, + { message = "(^[Ff]eat)|(^[Ee]nhancement)", group = "Implemented enhancements" }, + { message = "(^ci)|(\\(ci\\))|(fixup\\s+ci)|(fix\\s+ci)|(license)|(example)", group = "Miscellaneous tasks" }, + { message = "^test", group = "Testing" }, + { message = "(^fix)|(panic)", group = "Fixed bugs" }, + { message = "(^refact)|(rework)", group = "Refactor" }, + { message = "(^[Pp]erf)|(performance)", group = "Performance" }, + { message = "(^[Cc]hore)", group = "Miscellaneous tasks" }, + { message = "^[Rr]evert", group = "Reverted changes" }, + { message = "(upgrade.*?go)|(go\\s+version)", group = "Updates" }, + { message = ".*", group = "Other" }, +] +# Exclude commits that are not matched by any commit parser. +filter_commits = false +# An array of link parsers for extracting external references, and turning them into URLs, using regex. +link_parsers = [] +# Include only the tags that belong to the current branch. +use_branch_tags = false +# Order releases topologically instead of chronologically. +topo_order = false +# Order releases topologically instead of chronologically. +topo_order_commits = true +# Order of commits in each group/release within the changelog. +# Allowed values: newest, oldest +sort_commits = "newest" +# Process submodules commits +recurse_submodules = false + +#[remote.github] +#owner = "go-openapi" diff --git a/.github/workflows/README.md b/.github/workflows/README.md new file mode 100644 index 0000000..1213e34 --- /dev/null +++ b/.github/workflows/README.md @@ -0,0 +1,58 @@ +# CI workflows + +## Shared workflows + +### Dependencies automation + +* auto-merge.yml: + * auto-merge dependabot updates, with dependency group rules + * auto-merge go-openapi bot updates + +### Test automation + +* go-test.yml: go unit tests +* monorepo-go-test.yml: go unit tests for monorepos + +* collect-coverage.yml: (common) collect & publish test coverage (to codecov) +* collect-reports.yml: (common) collect & publish test reports (to codecov and github) + +### Security + +* codeql.yml: CodeQL workflow for go and github actions +* scanner.yml: trivy & govulncheck scans + +### Release automation + +* bump-release.yml: manually triggered workflow to cut a release +* tag-release.yml: cut a release on push tag +* release.yml: (common) release & release notes build + +### Code quality + +* collect-coverage.yml: common collect & publish test coverage (to codecov) +* collect-reports.yml: common collect & publish test reports (to codecov and github) + +### Documentation quality + +* contributors.yml: updates CONTRIBUTORS.md +* doc-update.yml: lint & spellcheck on markdown updates +* pr-comment.yml: common PR commment workflow + +## Test workflows + +* local-auto-merge.yml +* local-bump-release.yml +* local-codeql.yml +* local-contributors.yml +* local-doc-update.yml +* local-go-test.yml +* local-monorepo-go-test.yml +* local-release.yml +* local-scanner.yml +* local-tag-release.yml + +## Configuration files + +* .cliff + +scripts diff --git a/.github/workflows/auto-merge.yml b/.github/workflows/auto-merge.yml index 506a086..7272f72 100644 --- a/.github/workflows/auto-merge.yml +++ b/.github/workflows/auto-merge.yml @@ -6,6 +6,10 @@ on: permissions: contents: read +defaults: + run: + shell: bash + jobs: dependabot: permissions: @@ -31,46 +35,24 @@ jobs: PR_URL: ${{github.event.pull_request.html_url}} GH_TOKEN: ${{secrets.GITHUB_TOKEN}} run: gh pr merge --auto --rebase "$PR_URL" + + actions-bot: + # description: | + # Auto merge for go-openapi bot. + # The regular actions-bot user cannot approve and merge its own pull requests, + # We use another bot user to update content to be approved/auto-merged by actions-bot. + permissions: + contents: write + pull-requests: write + runs-on: ubuntu-latest + if: ${{ github.event.pull_request.user.login == 'bot-go-openapi[bot]' }} + env: + PR_URL: ${{github.event.pull_request.html_url}} + GH_TOKEN: ${{secrets.GITHUB_TOKEN}} + steps: - - name: Auto-merge dependabot PRs for go-openapi patches - if: >- - ${{ - contains(steps.metadata.outputs.dependency-group, 'go-openapi-dependencies') && - ( - steps.metadata.outputs.update-type == 'version-update:semver-minor' || - steps.metadata.outputs.update-type == 'version-update:semver-patch' - ) - }} - env: - PR_URL: ${{github.event.pull_request.html_url}} - GH_TOKEN: ${{secrets.GITHUB_TOKEN}} - run: gh pr merge --auto --rebase "$PR_URL" + name: Auto-approve all bot-go-openapi PRs + run: gh pr review --approve "$PR_URL" - - name: Auto-merge dependabot PRs for golang.org updates - if: ${{ contains(steps.metadata.outputs.dependency-group, 'golang-org-dependencies') }} - env: - PR_URL: ${{github.event.pull_request.html_url}} - GH_TOKEN: ${{secrets.GITHUB_TOKEN}} + name: Auto-merge bot-go-openapi PRs run: gh pr merge --auto --rebase "$PR_URL" - - # Auto merge is current disabled: we need automatic PRs to swap identity (e.g. using a Github App), - # so the pull_request event is properly captured and the PR can validate. - #actions-bot: - # permissions: - # contents: write - # pull-requests: write - # runs-on: ubuntu-latest - # if: ${{ github.event.pull_request.user.login == 'github-actions[bot]' }} - # steps: - # - - # name: Auto-approve all github-actions bot PRs - # env: - # PR_URL: ${{github.event.pull_request.html_url}} - # GH_TOKEN: ${{secrets.GITHUB_TOKEN}} - # run: gh pr review --approve "$PR_URL" - # - - # name: Auto-merge github-actions bot PRs - # env: - # PR_URL: ${{github.event.pull_request.html_url}} - # GH_TOKEN: ${{secrets.GITHUB_TOKEN}} - # run: gh pr merge --auto --rebase "$PR_URL" diff --git a/.github/workflows/bump-release.yml b/.github/workflows/bump-release.yml new file mode 100644 index 0000000..f476da6 --- /dev/null +++ b/.github/workflows/bump-release.yml @@ -0,0 +1,133 @@ +name: Bump Release + +permissions: + contents: read + +# description: | +# Manual action to bump the current version and cut a release. +# +# Determine which version to bump. +# Push corresponding tag, with comment. +# Build a github release on pushed tag. + +defaults: + run: + shell: bash + +on: + workflow_call: + inputs: + bump-patch: + description: Bump a patch version release + type: boolean + required: false + default: true + bump-minor: + description: Bump a minor version release + type: boolean + required: false + default: false + bump-major: + description: Bump a major version release + type: boolean + required: false + default: false + tag-message-title: + description: Tag message title to prepend to the release notes + required: false + type: string + tag-message-body: + description: | + Tag message body to prepend to the release notes. + (use "|" to replace end of line). + required: false + type: string + +jobs: + tag-release: + runs-on: ubuntu-latest + permissions: + contents: write + outputs: + next-tag: ${{ steps.bump-release.outputs.next-tag }} + steps: + - + name: Checkout code + uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0 + with: + fetch-depth: 0 + - + name: install svu + uses: go-openapi/gh-actions/install/svu@00fc74b63fc83dd6031018ecbeac387ca9131fe2 # v0.1.0 + - + name: Bump release + id: bump-release + run: | + # determine next tag to push + NEXT_TAG="" + if [[ '${{ inputs.bump-patch }}' == 'true' ]] ; then + NEXT_TAG=$(svu patch) + elif [[ '${{ inputs.bump-minor }}' == 'true' ]] ; then + NEXT_TAG=$(svu minor) + elif [[ '${{ inputs.bump-major }}' == 'true' ]] ; then + NEXT_TAG=$(svu major) + else + echo "::error::invalid options::One of bump-patch, bump-minor or bump-major must be true" + exit 1 + fi + + if [[ -z "${NEXT_TAG}" ]] ; then + echo "::error::something went wrong and no tag has been determined. Stopping here" + exit 1 + fi + + echo "next-tag=${NEXT_TAG}" >> "$GITHUB_OUTPUT" + echo "::notice title=next-tag:${NEXT_TAG}" + - + name: Import GPG key + uses: crazy-max/ghaction-import-gpg@e89d40939c28e39f97cf32126055eeae86ba74ec # v6.3.0 + # This is using the GPG signature of bot-go-openapi. + # + # CI_BOT_GPG_PRIVATE_KEY: the bot gpg key, armored + # CI_BOT_GPG_PASSPHRASE: the bot gpg passphrase + # CI_BOT_SIGNING_KEY: the fingerprint of the subkey used (space removed) + # NOTE(fredbi): extracted w/ gpg -K --homedir gnupg --keyid-format LONG --with-keygrip --fingerprint --with-subkey-fingerprint + with: + gpg_private_key: ${{ secrets.CI_BOT_GPG_PRIVATE_KEY }} + passphrase: ${{ secrets.CI_BOT_GPG_PASSPHRASE }} + fingerprint: ${{ secrets.CI_BOT_SIGNING_KEY }} + git_user_signingkey: true + git_commit_gpgsign: true + git_tag_gpgsign: true + - + name: Create and sign tag + env: + NEXT_TAG: ${{ steps.bump-release.outputs.next-tag }} + MESSAGE_TITLE: ${{ inputs.tag-message-title }} + MESSAGE_BODY: ${{ inputs.tag-message-body }} + run: | + # construct the tag message + set -x + MESSAGE="${MESSAGE_TITLE}" + if [[ -n "${MESSAGE_BODY}" ]] ; then + BODY=$(echo "${MESSAGE_BODY}"|tr '|' '\n') + MESSAGE=$(printf "%s\n%s\n" "${MESSAGE}" "${BODY}") + fi + echo "::notice title=tag-message:${MESSAGE}" + + git tag -s -m "${MESSAGE}" "${NEXT_TAG}" + git tag -v "${NEXT_TAG}" + git push origin "${NEXT_TAG}" + + gh-release: + # trigger release creation explictly. + # The previous tagging action does not trigger the normal release workflow + # (github prevents cascading triggers from happening). + name: Create release + needs: [ tag-release ] + permissions: + contents: write + uses: ./.github/workflows/release.yml + with: + tag: ${{ needs.tag-release.outputs.next-tag}} + secrets: inherit diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index a3d1c59..e8cbfa4 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -22,13 +22,13 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0 - # Initializes the CodeQL tools for scanning. name: Initialize CodeQL - uses: github/codeql-action/init@014f16e7ab1402f30e7c3329d33797e7948572db # v4.31.3 + uses: github/codeql-action/init@fdbfb4d2750291e159f0156def62b853c2798ca2 # v4.31.5 with: languages: ${{ matrix.language }} - name: Analyze ${{ matrix.language }} - uses: github/codeql-action/analyze@014f16e7ab1402f30e7c3329d33797e7948572db # v4.31.3 + uses: github/codeql-action/analyze@fdbfb4d2750291e159f0156def62b853c2798ca2 # v4.31.5 diff --git a/.github/workflows/collect-coverage.yml b/.github/workflows/collect-coverage.yml new file mode 100644 index 0000000..66443e9 --- /dev/null +++ b/.github/workflows/collect-coverage.yml @@ -0,0 +1,39 @@ +name: Collect coverage + +permissions: + pull-requests: read + contents: read + +on: + workflow_call: + +jobs: + collect-coverage: + # description: | + # Gather, merge then uploads test coverage files from all test jobs (this includes integration tests, + # like codegen-test). This reduces the number of failures due to codecov hitting github API rate limit. + name: collect test coverage + runs-on: ubuntu-latest + steps: + - + uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0 + with: + ref: ${{ github.event.pull_request.head.ref }} + repository: ${{ github.event.pull_request.head.repo.full_name }} + - + name: Download coverage artifacts + uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0 + with: + run-id: "${{ github.run_id }}" + pattern: "*.coverage.*" + # artifacts resolve as folders + path: coverage/ + - + name: Upload coverage to codecov + uses: codecov/codecov-action@5a1091511ad55cbe89839c7260b706298ca349f7 # v5.5.1 + with: + name: Aggregated coverage + # All *.coverage.*.out files uploaded should be detected by the codecov action. + # NOTE: we lose the flags on individual test reports (e.g. by os, by go version, unit vs integration tests) + fail_ci_if_error: false + verbose: false diff --git a/.github/workflows/collect-reports.yml b/.github/workflows/collect-reports.yml new file mode 100644 index 0000000..9da967b --- /dev/null +++ b/.github/workflows/collect-reports.yml @@ -0,0 +1,115 @@ +name: Collect test reports + +permissions: + pull-requests: read + contents: read + +on: + workflow_call: + +defaults: + run: + shell: bash + +jobs: + # description: | + # Gather, merge then uploads test report files from unit test jobs. + # + # At this moment test reports are published on both codecov + # (see ) and the github actions UI + # (see ). + collect-reports: + name: collect test reports + runs-on: ubuntu-latest + steps: + - + name: Download test report artifacts + uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0 + with: + run-id: "${{ github.run_id }}" + pattern: "*.report.*" + # artifacts resolve as folders + path: reports/ + - + name: Install go-junit-report + uses: go-openapi/gh-actions/install/go-junit-report@2c8f8152814933c4cead92a51558699238ee9565 + - + name: Convert test reports to a merged JUnit XML + # NOTE: codecov test reports only support JUnit format at this moment. See https://docs.codecov.com/docs/test-analytics. + # Ideally, codecov improve a bit their platform, so we may only need a single pass to CTRF format. + # + # As a contemplated alternative, we could use gotestsum above to produce the JUnit XML directly. + # At this moment, we keep a json format to dispatch test reports to codecov as well as to CTRF reports. + # + # TODO(fredbi): investigate - use mikepenz/action-junit-report@v5, that packages most of the following scripts + # in a single action. Alternative: for that action. + run: | + find reports/ -name \*.json -print0 | xargs -0 cat | go-junit-report -parser gojson -out=reports/junit_report.xml + - + name: Upload test results to Codecov + # This allows for using the test results UI on codecov + uses: codecov/codecov-action@5a1091511ad55cbe89839c7260b706298ca349f7 # v5.5.1 + with: + files: '**/junit_report.xml' + report_type: 'test_results' + fail_ci_if_error: false + handle_no_reports_found: true + verbose: true + - + name: Install go-ctrf-json-reporter + uses: go-openapi/gh-actions/install/go-ctrf-json-reporter@2c8f8152814933c4cead92a51558699238ee9565 + - + name: Convert test reports to CTRF JSON + # description: | + # This step publishes CTRF test reports on github UI (actions) + run: | + appName="${{ github.repository }}" + buildNumber="${{ github.run_id }}" + appVersion="${{ github.event.pull_request.head.sha }}" + if [[ -z "${appVersion}" ]] ; then + # for push events + appVersion="${{ github.sha }}" + fi + + # reconstruct platform information from the file name + while read -r report ; do + reformated=$(echo "${report##*/}"|sed -E 's/(go)([[:digit:]]+)\.([[:digit:]]+)/\1\2\3/') # e.g. go1.24 becomes go124 + mapfile -d'.' -t -s 2 -n 2 split < <(echo "$reformated") # skip the first 2 parts, stop on 2 more parts + envstring="${split[0]}" + osPlatform="${envstring%-*}" + osRelease="${envstring##*-}" + + # this is a best effort only: tests may be cancelled upstream and produce incorrect reports + go-ctrf-json-reporter \ + -quiet \ + -appName "${appName}" \ + -appVersion "${appVersion}" \ + -buildNumber "${buildNumber}" \ + -osPlatform "${osPlatform}" \ + -osRelease "${osRelease}" \ + -output "./reports/ctrf_report_${osPlatform}_${osRelease}.json" < "${report}" || true + done < <(find reports -name \*.json) + + # NOTE: at this moment, we don't upload CTRF reports as artifacts. + # Some of the CTRF reports are therefore not available (flaky tests, history, ...). + # + # See https://github.com/ctrf-io/github-test-reporter?tab=readme-ov-file#report-showcase + # for more reporting possibilities. At the moment, we keep it simple, as most advanced features + # require a github token (thus adding the complexity of a separate workflow starting on pull_request_target). + # + # For the moment, we are contented with these simple reports. This is an opportunity to compare the insight they + # provide as compared to what is uploaded to codecov. + # + # Codecov analytics are pretty poor at this moment. On the other hand, they manage the bot that pushes back + # PR comments. + # + # They also handle the storage of past test reports, so as to assess flaky tests. + - + name: Publish Test Summary Results + uses: ctrf-io/github-test-reporter@024bc4b64d997ca9da86833c6b9548c55c620e40 # v1.0.26 + with: + report-path: 'reports/ctrf_report_*.json' + use-suite-name: true + summary-report: true # post a report to the github actions summary + github-report: true + failed-folded-report: true diff --git a/.github/workflows/contributors.yml b/.github/workflows/contributors.yml index 79a7047..92a0ee8 100644 --- a/.github/workflows/contributors.yml +++ b/.github/workflows/contributors.yml @@ -13,13 +13,15 @@ jobs: pull-requests: write contents: write runs-on: ubuntu-latest + outputs: + pull-request-url: ${{ steps.create-pull-request.outputs.pull-request-url }} steps: - name: Checkout repository - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0 - name: Identify all-time contributors to this repository - uses: github/contributors@8b7586939baa0af4e801dbd22c88adf6e0db8915 # v1.7.5 + uses: github/contributors@abf36819e840f6e8056dcd40d33003ce7c4bc8dd # v1.7.6 env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} REPOSITORY: ${{ github.repository }} @@ -29,17 +31,55 @@ jobs: run: | rm -rf contributors.json mv contributors.md CONTRIBUTORS.md + - + name: Switch to go-openapi bot user + uses: actions/create-github-app-token@7e473efe3cb98aa54f8d4bac15400b15fad77d94 # v2.2.0 + id: app-token + with: + app-id: ${{ secrets.CI_BOT_APP_ID }} + private-key: ${{ secrets.CI_BOT_APP_PRIVATE_KEY }} + - + name: Import GPG key + uses: crazy-max/ghaction-import-gpg@e89d40939c28e39f97cf32126055eeae86ba74ec # v6.3.0 + with: + gpg_private_key: ${{ secrets.CI_BOT_GPG_PRIVATE_KEY }} + passphrase: ${{ secrets.CI_BOT_GPG_PASSPHRASE }} + fingerprint: ${{ secrets.CI_BOT_SIGNING_KEY }} + git_user_signingkey: true + git_commit_gpgsign: true + git_tag_gpgsign: true - name: Create a PR id: create-pull-request - uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e # v7.0.8 + uses: peter-evans/create-pull-request@84ae59a2cdc2258d6fa0732dd66352dddae2a412 # v7.0.9 with: commit-message: "doc: updated contributors file" branch: doc/contributors-bot delete-branch: true title: "doc: updated contributors file" - token: ${{ secrets.GITHUB_TOKEN }} + token: ${{ steps.app-token.outputs.token }} labels: "bot" + draft: false assignees: fredbi reviewers: fredbi sign-commits: true + signoff: false + + auto-merge: + # description: | + # Validates and merge the pull request triggered above. + needs: [update-contributors] + permissions: + contents: write + pull-requests: write + runs-on: ubuntu-latest + env: + PR_URL: ${{needs.update-contributors.outputs.pull-request-url}} + GH_TOKEN: ${{secrets.GITHUB_TOKEN}} + steps: + - + name: Auto-approve PR + run: gh pr review --approve "$PR_URL" + - + name: Auto-merge PR + run: gh pr merge --auto --rebase "$PR_URL" diff --git a/.github/workflows/doc-update.yml b/.github/workflows/doc-update.yml deleted file mode 100644 index e343a4d..0000000 --- a/.github/workflows/doc-update.yml +++ /dev/null @@ -1,524 +0,0 @@ -name: doc update check -# description: | -# This workflow is designed to help improve documentation quality. -# -# It proceeds with markdown linting and checks spelling in markdown files every time a markdown file is changed -# in a pull request. -# -# > NOTE: this workflow is only concerned with markdown documentation, not documentation in code (e.g. godoc). -# -# ## Usage of github action features -# -# * shared workflow -# * temporary token exchange using github app to elevate privileges within a trusted workflow -# * job summary (on actions UI) -# -# ## Limitations of github action features -# -# * [ ] did not find a way yet to retrieve the repo repo specified by the caller of this workflow. -# Had to resort to `master` to retrieve extra config files. -# -# ## TODO -# -# * [ ] should make an adapted version that runs on schedule and analyzes all markdown. -# * [ ] in this case, instead of commenting pull requests, it should raise issues. -# * [ ] should be able to retrieve config files and dictionary from the called ref, not master. -# * [ ] should be able to merge config files and dictionary with local definitions on target repo. -# * [ ] should be able to work on diff -# * [ ] should format the output of spellcheck report - -on: - workflow_call: - -permissions: - pull-requests: write - contents: read - -env: - artifacts_dir: artifacts - - markdown_comment_title: Markdown linter - markdown_config: '.github/.markdownlint.yml' - markdown_artifact: markdown_comment.txt - - spellcheck_comment_title: Markdown spelling check - spellcheck_config: .github/.spellcheck.yml - spellcheck_dict: .github/.wordlist.txt - spellcheck_artifact: spellcheck_comment.txt - -jobs: - markdown-changed: - # description: | - # This triggers a markdown and spellcheck lint whenever documentation files change. - runs-on: ubuntu-latest - outputs: - proceed: ${{ steps.changed-markdown-files.outputs.any_changed }} - all_changed_files: ${{ steps.changed-markdown-files.outputs.all_changed_files }} - steps: - - - name: Originating repo checkout (e.g. public fork) - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 - with: - ref: ${{ github.event.pull_request.head.sha }} - - - name: Get changed markdown files - uses: tj-actions/changed-files@24d32ffd492484c1d75e0c0b894501ddb9d30d62 # v4.7.0 - id: changed-markdown-files - with: - files: '**/*.md' - - - name: Notify - run: | - echo "::notice::Detected some changed markdown files" - echo "${{ steps.changed-markdown-files.outputs.all_changed_files }}" - - markdown-lint: - needs: markdown-changed - if: ${{ needs.markdown-changed.outputs.proceed == 'true' }} - runs-on: ubuntu-latest - env: - lintreport: './markdownlint-report.txt' - outputs: - proceed: ${{ steps.report-exists.outputs.proceed }} - congrats: ${{ steps.congrats.outputs.proceed }} - report: ${{ steps.report-exists.outputs.report }} - steps: - - - name: Originating repo checkout (e.g. public fork) - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 - with: - ref: ${{ github.event.pull_request.head.sha }} - - - name: Checkout markdown config - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 - with: - repository: go-openapi/ci-workflows - ref: master # TODO: retrieve workflow ref - sparse-checkout: | - ${{ env.markdown_config }} - sparse-checkout-cone-mode: false - path: ci-tools - - - name: Copy markdown config - # TODO: merge with local if present - run: | - cp ci-tools/"${{ env.markdown_config}}" "${{ env.markdown_config }}" - - - name: Run markdown linter - continue-on-error: true - id: markdownlint - uses: docker://avtodev/markdown-lint:v1.5 - with: - config: ./${{ env.markdown_config }} - args: '${{ needs.markdown-changed.outputs.all_changed_files }}' - output: '${{ env.lintreport }}' - - - name: Comment on success - if: ${{ steps.markdownlint.outcome == 'success' }} - id: congrats - run: | - echo "::notice:: no linting issue with changed markdown" - echo "proceed=true" >> $GITHUB_OUTPUT - - - name: Comment on markdown lint complaining - if: ${{ steps.markdownlint.outcome != 'success' && hashFiles(env.lintreport) != '' }} - id: report-exists - run: | - # summarizes a bit the output from spellcheck - echo 'report<> $GITHUB_OUTPUT - cat ${{ env.lintreport }}|sed -e '$a\' >> $GITHUB_OUTPUT - echo 'EOF' >> $GITHUB_OUTPUT - - if [[ "$(cat ${{ env.lintreport }}|wc -l)" != "0" ]] ; then - echo "proceed=true" >> $GITHUB_OUTPUT - echo "::notice::Detected some linting issues with changed markdown" - cat ${{ env.lintreport }}|sed -e '$a\' - else - echo "proceed=false" >> $GITHUB_OUTPUT - echo "::notice::No linting issues with changed markdown" - fi - - - name: Other linter errors - if: ${{ steps.markdownlint.outcome != 'success' && hashFiles(env.lintreport) == '' }} - run: | - echo "::error::markdown linter encountered an error" - exit 1 - - markdown-spelling: - needs: markdown-changed - if: ${{ needs.markdown-changed.outputs.proceed == 'true' }} - runs-on: ubuntu-latest - env: - spellcheckreport: './spellcheck-report.txt' - outputs: - proceed: ${{ steps.report-exists.outputs.proceed }} - congrats: ${{ steps.congrats.outputs.proceed }} - report: ${{ steps.report-exists.outputs.report }} - steps: - - - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 - with: - ref: ${{ github.event.pull_request.head.sha }} - - - name: Checkout spellcheck config - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 - with: - repository: go-openapi/ci-workflows - ref: master # TODO: retrieve workflow ref - sparse-checkout: | - ${{ env.spellcheck_config }} - ${{ env.spellcheck_dict }} - sparse-checkout-cone-mode: false - path: ci-tools - - - name: Copy spellcheck config - # TODO: merge with local if present - run: | - cp ci-tools/${{ env.spellcheck_config }} ${{ env.spellcheck_config }} - cp ci-tools/${{ env.spellcheck_dict }} ${{ env.spellcheck_dict }} - - - name: Spellcheck - uses: rojopolis/spellcheck-github-actions@0.51.0 - continue-on-error: true - id: spellcheck - with: - config_path: ${{ env.spellcheck_config }} - source_files: '${{ needs.markdown-changed.outputs.all_changed_files }}' - task_name: markdown - output_file: ${{ env.spellcheckreport }} - - - name: Comment on success - if: ${{ steps.spellcheck.outcome == 'success' }} - id: congrats - run: | - echo "::notice:: no spelling issue with changed markdown" - echo "proceed=true" >> $GITHUB_OUTPUT - - echo "### Your changes to markdown docs show impeccable spelling. 👍" >> $GITHUB_STEP_SUMMARY - echo "" >> $GITHUB_STEP_SUMMARY - echo "> ℹī¸ INFO: we use [rojopolis/spellcheck-github-actions](https://github.com/rojopolis/spellcheck-github-actions)" >> $GITHUB_STEP_SUMMARY - - - name: Comment on spellcheck complaining - if: ${{ steps.spellcheck.outcome != 'success' && hashFiles(env.spellcheckreport) != '' }} - id: report-exists - run: | - echo 'report<> $GITHUB_OUTPUT - cat ${{ env.spellcheckreport }}|sed -e '$a\' >> $GITHUB_OUTPUT - echo 'EOF' >> $GITHUB_OUTPUT - - if [[ "$(cat ${{ env.spellcheckreport }}|wc -l)" != "0" ]] ; then - echo "proceed=true" >> $GITHUB_OUTPUT - echo "::notice::Detected some spelling issues with changed markdown" - cat ${{ env.lintreport }}|sed -e '$a\' - else - echo "proceed=false" >> $GITHUB_OUTPUT - echo "::notice::No spelling issues with changed markdown" - fi - - - name: Other linter errors - if: ${{ steps.spellcheck.outcome != 'success' && hashFiles(env.spellcheckreport) == '' }} - run: | - echo "::error::spellcheck encountered an error" - exit 1 - - pr-markdown-congrats: - needs: markdown-lint - if: ${{ needs.markdown-lint.outputs.congrats == 'true' }} - runs-on: ubuntu-latest - outputs: - run_id: ${{ steps.notify_markdown_congrats.outputs.run_id }} - target_repo: ${{ steps.notify_markdown_congrats.outputs.target_repo }} - pr_number: ${{ steps.notify_markdown_congrats.outputs.pr_number }} - pr_sha: ${{ steps.notify_markdown_congrats.outputs.pr_sha }} - artifact_name: ${{ steps.notify_markdown_congrats.outputs.artifact_name }} - comment_title: ${{ steps.notify_markdown_congrats.outputs.comment_title }} - reactions: ${{ steps.notify_markdown_congrats.outputs.reactions }} - steps: - - - name: Congrats - id: notify_markdown_congrats - run: | - mkdir -p "${{ env.artifacts_dir }}" - read -d '' MSG< "${{ env.artifacts_dir}}/${{ env.markdown_artifact }}" - - echo "### Your changes to markdown docs look good. 👍" >> $GITHUB_STEP_SUMMARY - echo "" >> $GITHUB_STEP_SUMMARY - echo "> ℹī¸ INFO: we use [avtodev/markdown-lint action](https://github.com/avto-dev/markdown-lint)" >> $GITHUB_STEP_SUMMARY - - echo "run_id=${{ github.run_id }}" >> "$GITHUB_OUTPUT" - echo "target_repo=${{ github.repository }}" >> "$GITHUB_OUTPUT" - echo "pr_number=${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT" - echo "pr_sha=${{ github.event.pull_request.head.sha }}" >> "$GITHUB_OUTPUT" - echo "artifact_name=${{ env.markdown_artifact }}" >> "$GITHUB_OUTPUT" - echo "comment_title=${{ env.markdown_comment_title }}" >> "$GITHUB_OUTPUT" - echo "reactions=hooray" >> "$GITHUB_OUTPUT" - - - name: Upload comment as artifact - uses: actions/upload-artifact@v4 - with: - path: ${{ env.artifacts_dir }}/${{ env.markdown_artifact }} - name: ${{ env.markdown_artifact }} - - pr-comment-markdown-congrats: - name: Create or update congrats comment - needs: pr-markdown-congrats - uses: go-openapi/ci-workflows/.github/workflows/pr-comment.yml@master # <- TODO: caller's ref - secrets: inherit - with: - run_id: ${{ needs.pr-markdown-congrats.outputs.run_id }} - target_repo: ${{ needs.pr-markdown-congrats.outputs.target_repo }} - pr_number: ${{ needs.pr-markdown-congrats.outputs.pr_number }} - pr_sha: ${{ needs.pr-markdown-congrats.outputs.pr_sha }} - artifact_name: ${{ needs.pr-markdown-congrats.outputs.artifact_name }} - comment_title: ${{ needs.pr-markdown-congrats.outputs.comment_title }} - reactions: ${{ needs.pr-markdown-congrats.outputs.reactions }} - - pr-markdown-report: - needs: markdown-lint - if: ${{ needs.markdown-lint.outputs.proceed == 'true' }} - outputs: - run_id: ${{ steps.notify_markdown_report.outputs.run_id }} - target_repo: ${{ steps.notify_markdown_report.outputs.target_repo }} - pr_number: ${{ steps.notify_markdown_report.outputs.pr_number }} - pr_sha: ${{ steps.notify_markdown_report.outputs.pr_sha }} - artifact_name: ${{ steps.notify_markdown_report.outputs.artifact_name }} - comment_title: ${{ steps.notify_markdown_report.outputs.comment_title }} - reactions: ${{ steps.notify_markdown_report.outputs.reactions }} - runs-on: ubuntu-latest - steps: - - - name: Format PR comment - id: comment_formatter - uses: skills/action-text-variables@v3 - with: - template-vars: > - { - "text": ${{ toJSON(needs.markdown-lint.outputs.report) }} - } - template-text: | - ### ${{ env.markdown_comment_title }} - - Some markdown linting issues were detected in the modified .md files. ⚠ī¸ - - Perhaps they were already there before your changes. - - This check is advisory only and not blocking. Please help us adopt a nice markdown style. - - Markdown formatting rules are documented [here](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md). -
- - ``` - {{ text }} - ``` - - - name: Slap on the wrist - env: - OUTPUT: "${{ steps.comment_formatter.outputs.updated-text }}" - run: | - mkdir -p "${{ env.artifacts_dir }}" - printenv OUTPUT > "${{ env.artifacts_dir}}/${{ env.markdown_artifact }}" - - echo "### Changed markdown docs need some formatting. ⚠ī¸" >> $GITHUB_STEP_SUMMARY - echo "" >> $GITHUB_STEP_SUMMARY - echo "> ℹī¸ INFO: we use [avtodev/markdown-lint action](https://github.com/avto-dev/markdown-lint)" >> $GITHUB_STEP_SUMMARY - - - name: Upload comment as artifact - uses: actions/upload-artifact@v4 - with: - path: ${{ env.artifacts_dir }}/${{ env.markdown_artifact }} - name: ${{ env.markdown_artifact }} - - - name: Notify - id: notify_markdown_report - run: | - echo "::notice::Commented pull request ${{ github.event.pull_request.number }}" - - echo "run_id=${{ github.run_id }}" >> "$GITHUB_OUTPUT" - echo "target_repo=${{ github.repository }}" >> "$GITHUB_OUTPUT" - echo "pr_number=${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT" - echo "pr_sha=${{ github.event.pull_request.head.sha }}" >> "$GITHUB_OUTPUT" - echo "artifact_name=${{ env.markdown_artifact }}" >> "$GITHUB_OUTPUT" - echo "comment_title=${{ env.markdown_comment_title }}" >> "$GITHUB_OUTPUT" - echo "reactions=confused" >> "$GITHUB_OUTPUT" - - pr-comment-markdown-report: - name: Create or update comment with report - needs: pr-markdown-report - uses: go-openapi/ci-workflows/.github/workflows/pr-comment.yml@master # <- TODO: caller's ref - secrets: inherit - with: - run_id: ${{ needs.pr-markdown-report.outputs.run_id }} - target_repo: ${{ needs.pr-markdown-report.outputs.target_repo }} - pr_number: ${{ needs.pr-markdown-report.outputs.pr_number }} - pr_sha: ${{ needs.pr-markdown-report.outputs.pr_sha }} - artifact_name: ${{ needs.pr-markdown-report.outputs.artifact_name }} - comment_title: ${{ needs.pr-markdown-report.outputs.comment_title }} - reactions: ${{ needs.pr-markdown-report.outputs.reactions }} - - pr-markdown-spelling-congrats: - needs: markdown-spelling - if: ${{ needs.markdown-spelling.outputs.congrats == 'true' }} - outputs: - run_id: ${{ steps.notify_spelling_congrats.outputs.run_id }} - target_repo: ${{ steps.notify_spelling_congrats.outputs.target_repo }} - pr_number: ${{ steps.notify_spelling_congrats.outputs.pr_number }} - pr_sha: ${{ steps.notify_spelling_congrats.outputs.pr_sha }} - artifact_name: ${{ steps.notify_spelling_congrats.outputs.artifact_name }} - comment_title: ${{ steps.notify_spelling_congrats.outputs.comment_title }} - reactions: ${{ steps.notify_spelling_congrats.outputs.reactions }} - runs-on: ubuntu-latest - steps: - - - name: Congrats - id: notify_spelling_congrats - run: | - mkdir -p artifacts - read -d '' MSG< "${{ env.artifacts_dir }}/${{ env.spellcheck_artifact }}" - - echo "run_id=${{ github.run_id }}" >> "$GITHUB_OUTPUT" - echo "target_repo=${{ github.repository }}" >> "$GITHUB_OUTPUT" - echo "pr_number=${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT" - echo "pr_sha=${{ github.event.pull_request.head.sha }}" >> "$GITHUB_OUTPUT" - echo "artifact_name=${{ env.spellcheck_artifact }}" >> "$GITHUB_OUTPUT" - echo "comment_title=${{ env.spellcheck_comment_title }}" >> "$GITHUB_OUTPUT" - echo "reactions=hooray" >> "$GITHUB_OUTPUT" - - - name: Upload comment as artifact - uses: actions/upload-artifact@v4 - with: - path: ${{ env.artifacts_dir }}/${{ env.spellcheck_artifact }} - name: ${{ env.spellcheck_artifact }} - - pr-comment-spelling-congrats: - name: Create or update comment - needs: pr-markdown-spelling-congrats - uses: go-openapi/ci-workflows/.github/workflows/pr-comment.yml@master # <- TODO: caller's ref - secrets: inherit - with: - run_id: ${{ needs.pr-markdown-spelling-congrats.outputs.run_id }} - target_repo: ${{ needs.pr-markdown-spelling-congrats.outputs.target_repo }} - pr_number: ${{ needs.pr-markdown-spelling-congrats.outputs.pr_number }} - pr_sha: ${{ needs.pr-markdown-spelling-congrats.outputs.pr_sha }} - artifact_name: ${{ needs.pr-markdown-spelling-congrats.outputs.artifact_name }} - comment_title: ${{ needs.pr-markdown-spelling-congrats.outputs.comment_title }} - reactions: ${{ needs.pr-markdown-spelling-congrats.outputs.reactions }} - - pr-markdown-spelling-report: - needs: markdown-spelling - if: ${{ needs.markdown-spelling.outputs.proceed == 'true' }} - outputs: - run_id: ${{ steps.notify_spelling_report.outputs.run_id }} - target_repo: ${{ steps.notify_spelling_report.outputs.target_repo }} - pr_number: ${{ steps.notify_spelling_report.outputs.pr_number }} - pr_sha: ${{ steps.notify_spelling_report.outputs.pr_sha }} - artifact_name: ${{ steps.notify_spelling_report.outputs.artifact_name }} - comment_title: ${{ steps.notify_spelling_report.outputs.comment_title }} - reactions: ${{ steps.notify_spelling_report.outputs.reactions }} - runs-on: ubuntu-latest - steps: - - - name: Pre-process spellcheck report - id: preprocess - env: - MSG: ${{ needs.markdown-spelling.outputs.report }} - SED_CMD: .github/workflows/scripts/filter.sed # a sed script to parse and reformat the spellcheck report - JQ_CMD: .github/workflows/scripts/merge.jq # a jq script to dedupe spellcheck reports by file - TMPFILE: /tmp/spellcheck-report.txt - run: | - export MSG - printenv MSG > "${TMPFILE}" - # produces a JSON object: - # { - # "file.md": [ mispelled word [, ...]] - # } - cat "${TMPFILE}" | sed -n -f "${SED_CMD}" | jq -s "${JQ_CMD}" > /tmp/preprocessed.txt - - echo 'report<> $GITHUB_OUTPUT - cat /tmp/preprocessed.txt|sed -e '$a\' >> $GITHUB_OUTPUT - echo 'EOF' >> $GITHUB_OUTPUT - - - name: Format PR comment - id: comment_formatter - uses: skills/action-text-variables@v3 - with: - template-vars: > - { - "text": ${{ steps.preprocess.outputs.report) }} - } - template-text: | - ### ${{ env.spellcheck_comment_title }} - - Some mispelled words were detected in the modified .md files. ⚠ī¸ - - Perhaps they were already there before your changes. - - This check is advisory only and not blocking. Please help us improve our documentation. -
- - ``` - ### TODO: range json - {{ text }} - ``` - - - name: Slap on the wrist - env: - OUTPUT: "${{ steps.comment_formatter.outputs.updated-text }}" - run: | - mkdir -p "${{ env.artifacts_dir }}" - printenv OUTPUT > "${{ env.artifacts_dir}}/${{ env.spellcheck_artifact }}" - - echo "### Changed markdown docs show some mispelled words. ⚠ī¸" >> $GITHUB_STEP_SUMMARY - echo "" >> $GITHUB_STEP_SUMMARY - echo "> ℹī¸ INFO: we use [rojopolis/spellcheck-github-actions](https://github.com/rojopolis/spellcheck-github-actions)." >> $GITHUB_STEP_SUMMARY - echo ">" >> $GITHUB_STEP_SUMMARY - echo "> As a general rule, technical terms or acronyms and references to code objects should be backquoted in markdown" >> $GITHUB_STEP_SUMMARY - - - name: Upload comment as artifact - # description: | - # Calls a trusted shared workflow that temporarily elevates the caller's privileges - # to write a comment in the PR. - uses: actions/upload-artifact@v4 - with: - path: ${{ env.artifacts_dir }}/${{ env.spellcheck_artifact }} - name: ${{ env.spellcheck_artifact }} - - - name: Notify - id: notify_spelling_report - run: | - echo "::notice::Commented pull request ${{ github.event.pull_request.number }}" - - echo "run_id=${{ github.run_id }}" >> "$GITHUB_OUTPUT" - echo "target_repo=${{ github.repository }}" >> "$GITHUB_OUTPUT" - echo "pr_number=${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT" - echo "pr_sha=${{ github.event.pull_request.head.sha }}" >> "$GITHUB_OUTPUT" - echo "artifact_name=${{ env.spellcheck_artifact }}" >> "$GITHUB_OUTPUT" - echo "comment_title=${{ env.spellcheck_comment_title }}" >> "$GITHUB_OUTPUT" - echo "reactions=confused" >> "$GITHUB_OUTPUT" - - pr-comment-spelling-report: - name: Create or update comment - needs: pr-markdown-spelling-report - secrets: inherit - uses: ./.github/workflows/pr-comment.yml - with: - run_id: ${{ needs.pr-markdown-spelling-report.outputs.run_id }} - target_repo: ${{ needs.pr-markdown-spelling-report.outputs.target_repo }} - pr_number: ${{ needs.pr-markdown-spelling-report.outputs.pr_number }} - pr_sha: ${{ needs.pr-markdown-spelling-report.outputs.pr_sha }} - artifact_name: ${{ needs.pr-markdown-spelling-report.outputs.artifact_name }} - comment_title: ${{ needs.pr-markdown-spelling-report.outputs.comment_title }} - reactions: ${{ needs.pr-markdown-spelling-report.outputs.reactions }} diff --git a/.github/workflows/fuzz-test.yml b/.github/workflows/fuzz-test.yml new file mode 100644 index 0000000..2d01b5b --- /dev/null +++ b/.github/workflows/fuzz-test.yml @@ -0,0 +1,123 @@ +name: fuzz test + +permissions: + pull-requests: read + contents: read + +on: + workflow_call: + +defaults: + run: + shell: bash + +# TODO: +# * support multiple fuzzed packages +# * support mono-repo setup + +jobs: + fuzz-test: + name: fuzz test + runs-on: ubuntu-latest + env: + CORPUS_MAX_SIZE_MB: 250 + FUZZ_TIME: 1m30s + FUZZ_MINIMIZE_TIME: 5m + steps: + - + uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0 + - + uses: actions/setup-go@4dc6199c7b1a012772edbd06daecab0f50c9053c # v6.1.0 + with: + go-version: stable + check-latest: true + cache: true + - + name: Locate go fuzz cache + run: | + GOCACHE=$(go env GOCACHE) + echo "CORPUS_DIR=${GOCACHE}/fuzz" >> "${GITHUB_ENV}" + - + name: Retrieve fuzz corpus from cache + uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0 + with: + key: ${{ runner.os }}-go-fuzz + path: + ${{ env.CORPUS_DIR }} + - + name: Manage fuzz corpus cache size + run: | + mkdir -p "${CORPUS_DIR}" + # This script checks that the size of the corpus cache doesn't exceed ${CORPUS_MAX_SIZE_MB}, + # and if it does, it removes all oldest files beyond that size. + + function size() { + local location=$1 + local unit=$2 + + du -s"${unit}" "${location}"|cut -f1 + } + + function purge() { + local location=$1 + local max_size_b=$2 + declare -i current_size_b=0 file_size_b=0 purged_files=0 + + while read -r filename ; do + file_size_b="$(size "${filename}" "b")" + ((current_size_b+=file_size_b)) + + if [[ ${current_size_b} -le ${max_size_b} ]] ; then + continue + fi + if [[ ${file_size_b} -eq 0 ]] ; then + continue + fi + + rm -f "${filename}" + ((purged_files+=1)) + done < <(find "${location}" -type f -print0 | xargs -0 ls -t) + + echo ${purged_files} + } + + CURRENT_SIZE_MB="$(size "${CORPUS_DIR}" "m")" + if [[ "${CURRENT_SIZE_MB}" -lt "${MAX_SIZE_MB}" ]] ; then + echo "::notice:cache size remains under the accepted size of ${MAX_SIZE_MB} MB: ${CURRENT_SIZE_MB} MB" + + exit 0 + fi + + declare -i max_size_b=$(("${CORPUS_MAX_SIZE_MB}" * 1024 * 1024)) + purged_files=$(purge "${purged_dir}" "${max_size_b}"); + echo "::notice:cache size is ${CURRENT_SIZE_MB} MB: purging oldest files to keep it under ${CORPUS_MAX_SIZE_MB} MB" + if [[ ${purged_files} -gt 0 ]] ; then + echo "::notice:removed ${purged_files} files to keep the cache size below ${CORPUS_MAX_SIZE_MB} MB" + fi + FINAL_SIZE_MB="$(size "${CORPUS_DIR}" "m")" + echo "::notice:purged cache size: ${FINAL_SIZE_MB} MB" + - + name: Run go fuzz tests + # TODO(fredbi): ./... is not supported: we should run as a matrix test multiple fuzz tests + run: > + go test + -fuzz=Fuzz + -run=Fuzz + -fuzztime='${{ env.FUZZ_TIME }}' + -fuzzminimizetime='${{ env.FUZZ_MINIMIZE_TIME }}' + ./... + - + name: Upload failed corpus + if: ${{ failure() }} + uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0 + # TODO(fredbi): ideally, after uploading, we should fire a pull request to add + # this corpus to testdata. + with: + path: ${{ env.CORPUS_DIR }} + name: '${{ runner.os }}-fuzz-corpus-failure' + retention-days: 60 + - + name: Report fuzz corpus cache size + run: | + FINAL_SIZE=$(du -m "${CORPUS_DIR}"|cut -f1) + echo "::notice title=fuzz corpus size:${FINAL_SIZE}MB" diff --git a/.github/workflows/gists.md b/.github/workflows/gists.md deleted file mode 100644 index 0af013d..0000000 --- a/.github/workflows/gists.md +++ /dev/null @@ -1,11 +0,0 @@ -# A few useful actions - - #- name: Acquire write access to PR - # if: ${{ steps.check_pr.outputs.proceed == 'true'}} - # id: acquire_write_token - # uses: actions/create-github-app-token@v2 - # with: - # app-id: ${{ secrets.CI_WORKFLOWS_PR_APP_ID }} - # private-key: ${{ secrets.CI_WORKFLOWS_PR_APP_PRIVATE_KEY }} - # owner: go-openapi - # repo: ${{ inputs.target_repo }} diff --git a/.github/workflows/go-test.yml b/.github/workflows/go-test.yml index 5dddca1..1827a83 100644 --- a/.github/workflows/go-test.yml +++ b/.github/workflows/go-test.yml @@ -1,32 +1,32 @@ name: go-test -on: - push: - branches: - - master - - pull_request: - permissions: pull-requests: read contents: read +on: + workflow_call: + +defaults: + run: + shell: bash + jobs: lint: name: Lint runs-on: ubuntu-latest steps: - - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0 - - uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00 # v6.0.0 + uses: actions/setup-go@4dc6199c7b1a012772edbd06daecab0f50c9053c # v6.1.0 with: go-version: stable check-latest: true cache: true - name: golangci-lint - uses: golangci/golangci-lint-action@0a35821d5c230e903fcfe077583637dea1b27b47 # v9.0.0 + uses: golangci/golangci-lint-action@e7fa5ac41e1cf5b7d48e45e42232ce7ada589601 # v9.1.0 with: version: latest only-new-issues: true @@ -44,21 +44,18 @@ jobs: steps: - - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0 - - uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00 # v6.0.0 + uses: actions/setup-go@4dc6199c7b1a012772edbd06daecab0f50c9053c # v6.1.0 with: go-version: '${{ matrix.go }}' check-latest: true cache: true - - name: Install Tools - # TODO: pin version -> fork + update dedicated github action - run: | - go install gotest.tools/gotestsum@latest + name: Install gotestsum + uses: go-openapi/gh-actions/install/gotestsum@2c8f8152814933c4cead92a51558699238ee9565 - name: Run unit tests - shell: bash run: > gotestsum --jsonfile 'unit.report.${{ matrix.os }}-${{ matrix.go }}.json' @@ -69,7 +66,7 @@ jobs: -timeout=20m -coverprofile='unit.coverage.${{ matrix.os }}-${{ matrix.go }}.out' -covermode=atomic - -coverpkg=$(go list)/... + -coverpkg="$(go list)"/... ./... - name: Upload coverage artifacts @@ -90,65 +87,7 @@ jobs: retention-days: 1 fuzz-test: - name: fuzz test - runs-on: ubuntu-latest - env: - CORPUS_MAX_SIZE_MB: 100 - steps: - - - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 - - - uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00 # v6.0.0 - with: - go-version: stable - check-latest: true - cache: true - - - name: Locate go fuzz cache - run: | - GOCACHE=$(go env GOCACHE) - echo "CORPUS_DIR=${GOCACHE}/fuzz" >> "${GITHUB_ENV}" - - - name: Retrieve fuzz corpus from cache - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0 - with: - key: ${{ runner.os }}-go-fuzz - path: - ${{ env.CORPUS_DIR }} - - - name: Manage fuzz corpus cache size - run: | - mkdir -p "${CORPUS_DIR}" - CURRENT_SIZE=$(du -sm "${CORPUS_DIR}"|cut -f1) - echo "corpus size: ${CURRENT_SIZE}MB" - if [[ "${CURRENT_SIZE}" -gt "${CORPUS_MAX_SIZE}" ]] ; then - # remove the 50 oldest corpus files - echo "::warning:Large fuzz corpus pruned" - find "${CORPUS_DIR}" -type f|ls -t|tail -n +50|xargs rm -f - fi - - - name: Run go fuzz tests - run: > - go test - -fuzz=Fuzz - -run=Fuzz - -fuzztime=1m30s - -fuzzminimizetime=5m - ./... - - - name: Upload failed corpus - if: ${{ failure() }} - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0 - with: - path: ${{ env.CORPUS_DIR }} - name: '${{ runner.os }}-fuzz-corpus-failure' - retention-days: 60 - - - name: Report fuzz corpus cache size - run: | - FINAL_SIZE=$(du -m "${CORPUS_DIR}"|cut -f1) - echo "::notice title=fuzz corpus size:${FINAL_SIZE}MB" - + uses: ./.github/workflows/fuzz-test.yml test-complete: # description: | @@ -163,146 +102,11 @@ jobs: echo "::notice title=Success:All tests passed" collect-coverage: - # description: | - # Gather, merge then uploads test coverage files from all test jobs (this includes integration tests, - # like codegen-test). This reduces the number of failures due to codecov hitting github API rate limit. - name: collect test coverage needs: [test-complete] if: ${{ !cancelled() && needs.test-complete.result == 'success' }} - runs-on: ubuntu-latest - steps: - - - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 - with: - ref: ${{ github.event.pull_request.head.ref }} - repository: ${{ github.event.pull_request.head.repo.full_name }} - - - name: Download coverage artifacts - uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0 - with: - run-id: "${{ github.run_id }}" - pattern: "*.coverage.*" - # artifacts resolve as folders - path: coverage/ - - - name: Upload coverage to codecov - uses: codecov/codecov-action@5a1091511ad55cbe89839c7260b706298ca349f7 # v5.5.1 - with: - name: Aggregated coverage - # All *.coverage.*.out files uploaded should be detected by the codecov action. - # NOTE: we lose the flags on individual test reports (e.g. by os, by go version, unit vs integration tests) - fail_ci_if_error: false - verbose: false + uses: ./.github/workflows/collect-coverage.yml collect-reports: - # description: | - # Gather, merge then uploads test report files from unit test jobs. - # - # At this moment test reports are published on both codecov - # (see ) and the github actions UI - # (see ). - name: collect test reports needs: [test] if: ${{ !cancelled() }} - runs-on: ubuntu-latest - steps: - - - uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00 # v6.0.0 - with: - go-version: stable - check-latest: true - cache: true - - - name: Download test report artifacts - uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0 - with: - run-id: "${{ github.run_id }}" - pattern: "*.report.*" - # artifacts resolve as folders - path: reports/ - - - name: Convert test reports to a merged JUnit XML - # NOTE: codecov test reports only support JUnit format at this moment. See https://docs.codecov.com/docs/test-analytics. - # Ideally, codecov improve a bit their platform, so we may only need a single pass to CTRF format. - # - # As a contemplated alternative, we could use gotestsum above to produce the JUnit XML directly. - # At this moment, we keep a json format to dispatch test reports to codecov as well as to CTRF reports. - # - # TODO(fredbi): sec compliance - pin go-junit-report - # TODO(fredbi): investigate - use mikepenz/action-junit-report@v5, that packages most of the following scripts - # in a single action. Alternative: for that action. - run: | - go install github.com/jstemmer/go-junit-report/v2@latest - go-junit-report -version - - find reports/ -name \*.json | xargs cat | go-junit-report -parser gojson -out=reports/junit_report.xml - - - name: Upload test results to Codecov - # This allows for using the test results UI on codecov - uses: codecov/codecov-action@5a1091511ad55cbe89839c7260b706298ca349f7 # v5.5.1 - with: - files: '**/junit_report.xml' - report_type: 'test_results' - fail_ci_if_error: false - handle_no_reports_found: true - verbose: true - - - name: Convert test reports to CTRF JSON - # description: | - # This step publishes CTRF test reports on github UI (actions) - # TODO: pin this dependency - run: | - go install github.com/ctrf-io/go-ctrf-json-reporter/cmd/go-ctrf-json-reporter@v0.0.10 - - appName="${{ github.repository }}" - buildNumber="${{ github.run_id }}" - appVersion="${{ github.event.pull_request.head.sha }}" - if [[ -z "${appVersion}" ]] ; then - # for push events - appVersion="${{ github.sha }}" - fi - - # reconstruct platform information from the file name - # set -x - while read report ; do - # 'unit.report.${{ matrix.os }}-${{ matrix.go }}.json' - reformated=$(echo "${report##*/}"|sed -E 's/(go)([[:digit:]]+)\.([[:digit:]]+)/\1\2\3/') # e.g. go1.24 becomes go124 - mapfile -d'.' -t -s 2 -n 2 split < <(echo $reformated) # skip the first 2 parts, stop on 2 more parts - envstring="${split[0]}" - osPlatform="${envstring%-*}" - osRelease="${envstring##*-}" - - # this is a best effort only: tests may be cancelled upstream and produce incorrect reports - go-ctrf-json-reporter \ - -quiet \ - -appName "${appName}" \ - -appVersion "${appVersion}" \ - -buildNumber "${buildNumber}" \ - -osPlatform "${osPlatform}" \ - -osRelease "${osRelease}" \ - -output "./reports/ctrf_report_${osPlatform}_${osRelease}.json" < "${report}" || true - done < <(find reports -name \*.json) - - # NOTE: at this moment, we don't upload CTRF reports as artifacts. - # Some of the CTRF reports are therefore not available (flaky tests, history, ...). - # - # See https://github.com/ctrf-io/github-test-reporter?tab=readme-ov-file#report-showcase - # for more reporting possibilities. At the moment, we keep it simple, as most advanced features - # require a github token (thus adding the complexity of a separate workflow starting on pull_request_target). - # - # For the moment, we are contented with these simple reports. This is an opportunity to compare the insight they - # provide as compared to what is uploaded to codecov. - # - # Codecov analytics are pretty poor at this moment. On the other hand, they manage the bot that pushes back - # PR comments. - # - # They also handle the storage of past test reports, so as to assess flaky tests. - - - name: Publish Test Summary Results - uses: ctrf-io/github-test-reporter@024bc4b64d997ca9da86833c6b9548c55c620e40 # v1.0.26 - with: - report-path: 'reports/ctrf_report_*.json' - use-suite-name: true - summary-report: true # post a report to the github actions summary - github-report: true - failed-folded-report: true + uses: ./.github/workflows/collect-reports.yml diff --git a/.github/workflows/local-auto-merge.yml b/.github/workflows/local-auto-merge.yml index 56a981c..e5db6ea 100644 --- a/.github/workflows/local-auto-merge.yml +++ b/.github/workflows/local-auto-merge.yml @@ -1,12 +1,14 @@ name: Dependabot auto-merge -# description: This workflow mimics how a go-openapi repo would typically invoke the common workflow. - -on: - pull_request: permissions: contents: read +# description: | +# This workflow mimics how a go-openapi repo would typically invoke the common workflow. + +on: + pull_request: + jobs: dependabot: permissions: diff --git a/.github/workflows/local-bump-release.yml b/.github/workflows/local-bump-release.yml new file mode 100644 index 0000000..d00136b --- /dev/null +++ b/.github/workflows/local-bump-release.yml @@ -0,0 +1,53 @@ +name: Bump Release + +permissions: + contents: read + +# description: | +# Manual action to bump the current version and cut a release. +# +# Determine which version to bump. +# Push corresponding tag, with comment. +# Build a github release on pushed tag. + +on: + workflow_dispatch: + inputs: + bump-patch: + description: Bump a patch version release + type: boolean + required: false + default: true + bump-minor: + description: Bump a minor version release + type: boolean + required: false + default: false + bump-major: + description: Bump a major version release + type: boolean + required: false + default: false + tag-message-title: + description: Tag message title to prepend to the release notes + required: false + type: string + tag-message-body: + description: | + Tag message body to prepend to the release notes. + (use "|" to replace end of line). + required: false + type: string + +jobs: + bump-release: + permissions: + contents: write + uses: ./.github/workflows/bump-release.yml + with: + bump-patch: ${{ inputs.bump-patch }} + bump-minor: ${{ inputs.bump-minor }} + bump-major: ${{ inputs.bump-major }} + tag-message-title: ${{ inputs.tag-message-title }} + tag-message-body: ${{ inputs.tag-message-body }} + secrets: inherit diff --git a/.github/workflows/local-codeql.yml b/.github/workflows/local-codeql.yml index 3b2728e..264b152 100644 --- a/.github/workflows/local-codeql.yml +++ b/.github/workflows/local-codeql.yml @@ -5,7 +5,7 @@ on: branches: [ "master" ] pull_request: branches: [ "master" ] - path-ignore: + paths-ignore: # remove this clause if CodeQL is a required check - '**/*.md' schedule: - cron: '39 19 * * 5' diff --git a/.github/workflows/local-go-test.yml b/.github/workflows/local-go-test.yml index 44ebd24..8972a7a 100644 --- a/.github/workflows/local-go-test.yml +++ b/.github/workflows/local-go-test.yml @@ -1,5 +1,11 @@ name: go test -# description: This workflow mimics how a go-openapi repo would typically invoke the common workflow. + +permissions: + pull-requests: read + contents: read + +# description: | +# This workflow mimics how a go-openapi repo would typically invoke the common workflow. on: push: @@ -8,10 +14,6 @@ on: pull_request: -permissions: - pull-requests: read - contents: read - jobs: test: uses: ./.github/workflows/go-test.yml diff --git a/.github/workflows/local-release.yml b/.github/workflows/local-release.yml index 45beed7..fbe6f16 100644 --- a/.github/workflows/local-release.yml +++ b/.github/workflows/local-release.yml @@ -13,4 +13,6 @@ jobs: permissions: contents: write uses: ./.github/workflows/release.yml + with: + tag: ${{ github.ref_name }} secrets: inherit diff --git a/.github/workflows/local-tag-release.yml b/.github/workflows/local-tag-release.yml new file mode 100644 index 0000000..e61b58a --- /dev/null +++ b/.github/workflows/local-tag-release.yml @@ -0,0 +1,24 @@ +name: Release on tag + +permissions: + contents: read + +# description: | +# Build a github release on pushed tag. +# +# The only available asset is a release note. + +on: + push: + tags: + - v[0-9]+* + +jobs: + gh-release: + name: Create release + permissions: + contents: write + uses: ./.github/workflows/release.yml + with: + tag: ${{ github.ref_name }} + secrets: inherit diff --git a/.github/workflows/markdown-changed.yml b/.github/workflows/markdown-changed.yml new file mode 100644 index 0000000..199ee61 --- /dev/null +++ b/.github/workflows/markdown-changed.yml @@ -0,0 +1,33 @@ +name: Markdown changed + +on: + workflow_call: + +permissions: + contents: read + +jobs: + markdown-changed: + # description: | + # This triggers a markdown and spellcheck lint whenever documentation files change. + runs-on: ubuntu-latest + outputs: + proceed: ${{ steps.changed-markdown-files.outputs.any_changed }} + all_changed_files: ${{ steps.changed-markdown-files.outputs.all_changed_files }} + steps: + - + name: Originating repo checkout (e.g. public fork) + uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + with: + ref: ${{ github.event.pull_request.head.sha }} + - + name: Get changed markdown files + uses: tj-actions/changed-files@24d32ffd492484c1d75e0c0b894501ddb9d30d62 # v4.7.0 + id: changed-markdown-files + with: + files: '**/*.md' + - + name: Notify + run: | + echo "::notice::Detected some changed markdown files" + echo "${{ steps.changed-markdown-files.outputs.all_changed_files }}" diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 1e79ad9..a41715d 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,15 +1,19 @@ name: Release -on: - workflow_call: - permissions: contents: read # description: | -# Build a github release on pushed tag. +# Build a github release on either pushed tag or a manual workflow call. # -# The only available asset is a release note. +# At this moment, the only available asset is a release note. + +on: + workflow_call: + inputs: + tag: + type: string + required: true jobs: gh-release: @@ -20,25 +24,33 @@ jobs: steps: - name: Checkout code - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0 with: fetch-depth: 0 - name: Extract tag message - id: get_message - # git-cliff may or may not pick the current tag message, difficult to tell when - # this works. We extract the tag message explicitly. + id: get-message + # tag message is not retrieved unless we fetch the ref explictly run: | - MESSAGE=$(git tag -l '${{ github.ref_name }}' --format='%(contents:subject) + set -x + + git fetch --depth=1 origin +refs/tags/*:refs/tags/* + MESSAGE=$(git tag -l '${{ inputs.tag }}' --format='%(contents:subject) %(contents:body) ') export MESSAGE - echo "message<> "${GITHUB_OUTPUT}" - printenv MESSAGE >> "${GITHUB_OUTPUT}" - echo 'EOF' >> "${GITHUB_OUTPUT}" + { + echo "message<> "${GITHUB_OUTPUT}" + + echo "Message in git tag ${{ inputs.tag }}" + echo "$MESSAGE" - name: Generate release notes + # this uses git-cliff to generate a release note from the commit history id: notes env: GITHUB_TOKEN: ${{ github.token }} @@ -48,9 +60,11 @@ jobs: config: '.cliff.toml' args: >- --current - --with-tag-message '${{ steps.get_message.outputs.message }}' + --with-tag-message '${{ steps.get-message.outputs.message }}' - name: Create github release uses: softprops/action-gh-release@5be0e66d93ac7ed76da52eca8bb058f665c3a5fe # v2.4.2 with: body: ${{ steps.notes.outputs.content }} + tag_name: ${{ inputs.tag }} + generate_release_notes: false # skip auto-generated release notes from github API diff --git a/.github/workflows/scanner.yml b/.github/workflows/scanner.yml index 2f34e48..d063e66 100644 --- a/.github/workflows/scanner.yml +++ b/.github/workflows/scanner.yml @@ -24,7 +24,7 @@ jobs: security-events: write steps: - - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0 with: persist-credentials: false - diff --git a/.github/workflows/tag-release.yml b/.github/workflows/tag-release.yml new file mode 100644 index 0000000..22fa5df --- /dev/null +++ b/.github/workflows/tag-release.yml @@ -0,0 +1,29 @@ +name: Release on tag + +permissions: + contents: read + +# description: | +# Build a github release on pushed tag. +# +# The only available asset is a release note. + +on: + workflow_call: + inputs: + tag: + type: string + required: true + +jobs: + gh-release: + # trigger release creation explictly. + # The previous tagging action does not trigger the normal release workflow + # (github prevents cascading triggers from happening). + name: Create release + permissions: + contents: write + uses: ./.github/workflows/release.yml + with: + tag: ${{ github.ref_name }} + secrets: inherit diff --git a/README.md b/README.md index 44e5be7..4e20b1b 100644 --- a/README.md +++ b/README.md @@ -98,8 +98,10 @@ This content ships under the [SPDX-License-Identifier: Apache-2.0](./LICENSE). [codeql-badge]: https://github.com/go-openapi/ci-workflows/actions/workflows/codeql.yml/badge.svg [codeql-url]: https://github.com/go-openapi/ci-workflows/actions/workflows/codeql.yml -[release-badge]: https://badge.fury.io/go/github.com%2Fgo-openapi%2Fci-workflows.svg -[release-url]: https://badge.fury.io/go/github.com%2Fgo-openapi%2Fci-workflows +[release-badge]: https://badge.fury.io/gh/go-openapi%2Fci-workflowser.svg +[release-url]: https://badge.fury.io/gh/go-openapi%2Fci-workflowser +[gomod-badge]: https://badge.fury.io/go/github.com%2Fgo-openapi%2Fci-workflowser.svg +[gomod-url]: https://badge.fury.io/go/github.com%2Fgo-openapi%2Fci-workflowser [gocard-badge]: https://goreportcard.com/badge/github.com/go-openapi/ci-workflows [gocard-url]: https://goreportcard.com/report/github.com/go-openapi/ci-workflows diff --git a/doc-templates/README.md b/doc-templates/README.md index 2cf2fb5..94d45e7 100644 --- a/doc-templates/README.md +++ b/doc-templates/README.md @@ -17,7 +17,7 @@ ## Status -{{ .Status }}. +API is stable. ## Import this library in your project @@ -65,8 +65,10 @@ on top of which it has been built. [codeql-badge]: https://github.com/{{ .Owner }}/{{ .Repo }}/actions/workflows/codeql.yml/badge.svg [codeql-url]: https://github.com/{{ .Owner }}/{{ .Repo }}/actions/workflows/codeql.yml -[release-badge]: https://badge.fury.io/go/github.com%2F{{ .Owner }}%2F{{ .Repo }}.svg -[release-url]: https://badge.fury.io/go/github.com%2F{{ .Owner }}%2F{{ .Repo }} +[release-badge]: https://badge.fury.io/gh/{{ .Owner }}%2F{{ .Repo }}.svg +[release-url]: https://badge.fury.io/gh/{{ .Owner }}%2F{{ .Repo }} +[gomod-badge]: https://badge.fury.io/go/github.com%2F{{ .Owner }}%2F{{ .Repo }}.svg +[gomod-url]: https://badge.fury.io/go/github.com%2F{{ .Owner }}%2F{{ .Repo }} [gocard-badge]: https://goreportcard.com/badge/github.com/{{ .Owner }}/{{ .Repo }} [gocard-url]: https://goreportcard.com/report/github.com/{{ .Owner }}/{{ .Repo }} diff --git a/experimental/go-test-monorepo.yml b/experimental/go-test-monorepo.yml new file mode 100644 index 0000000..324fc12 --- /dev/null +++ b/experimental/go-test-monorepo.yml @@ -0,0 +1,156 @@ +name: go test + +permissions: + contents: read + pull-requests: read + +on: + workflow_call: + +defaults: + run: + shell: bash + +jobs: + lint: + name: Go lint mono-repo + runs-on: ubuntu-latest + steps: + - + uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0 + with: + fetch-depth: 0 + - + uses: actions/setup-go@4dc6199c7b1a012772edbd06daecab0f50c9053c # v6.1.0 + with: + go-version: stable + check-latest: true + cache: true + cache-dependency-path: '**/go.sum' + - + name: Detect if mono-repo + id: detect-monorepo + run: | + count_modules=$(go list -m|wc -l) + if [[ "${count_module}" -gt 1 ]] ; then + echo "is_monorepo=true" >> "${GITHUB_OUTPUT}" + exit + fi + echo "is_monorepo=false" >> "${GITHUB_OUTPUT}" + - + name: Install golangci-lint + if: ${{ steps.detect-monorepo.outputs == 'true' }} + uses: golangci/golangci-lint-action@e7fa5ac41e1cf5b7d48e45e42232ce7ada589601 # v9.1.0 + with: + version: latest + skip-cache: true + install-only: true + - + name: Lint multiple modules + if: ${{ steps.detect-monorepo.outputs == 'true' }} + # golangci-lint doesn't support go.work to lint multiple modules in one single pass + # TODO: golangci-action v9.1+ has a built-in mono repo detection setup. + run: | + set -euxo pipefail + + git fetch origin master + git show --no-patch --oneline origin/master + + while read -r module_location ; do + pushd "${module_location}" + golangci-lint run --new-from-rev origin/master + popd + done < <(go list -f '{{.Dir}}' -m) + + test: + name: Unit tests mono-repo + needs: [ lint ] + runs-on: ${{ matrix.os }} + strategy: + matrix: + os: [ ubuntu-latest, macos-latest, windows-latest ] + go_version: ['oldstable', 'stable' ] + steps: + - + uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0 + - + uses: actions/setup-go@4dc6199c7b1a012772edbd06daecab0f50c9053c # v6.1.0 + with: + go-version: '${{ matrix.go_version }}' + check-latest: true + cache: true + cache-dependency-path: '**/go.sum' + - + name: Install gotestsum + uses: go-openapi/gh-actions/install/gotestsum@2c8f8152814933c4cead92a51558699238ee9565 + - + name: Run unit tests on all modules in this repo + run: | + # when go1.25 becomes the oldstable, we may replace this bash with "go test work" + declare -a ALL_MODULES + BASH_MAJOR=$(echo "${BASH_VERSION}"|cut -d'.' -f1) + if [[ "${BASH_MAJOR}" -ge 4 ]] ; then + mapfile ALL_MODULES < <(go list -f '{{.Dir}}/...' -m) + else + # for older bash versions, e.g. on macOS runner. This fallback will eventually disappear. + while read -r line ; do + ALL_MODULES+=("${line}") + done < <(go list -f '{{.Dir}}/...' -m) + fi + echo "::notice title=Modules found::${ALL_MODULES[@]}" + + # with go.work file enabled, go test recognizes sub-modules and collects all packages to be covered + # without specifying -coverpkg. + gotestsum \ + --jsonfile 'unit.report.${{ matrix.os }}-${{ matrix.go }}.json' \ + -- \ + -race \ + -p 2 \ + -count 1 \ + -timeout=20m \ + -coverprofile='unit.coverage.${{ matrix.os }}-${{ matrix.go }}.out' \ + -covermode=atomic \ + ${ALL_MODULES[@]} + - + name: Upload coverage artifacts + uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0 + with: + # *.coverage.* pattern is automatically detected by codecov + path: '**/*.coverage.*.out' + name: 'unit.coverage.${{ matrix.os }}-${{ matrix.go }}' + retention-days: 1 + - + name: Upload test report artifacts + # upload report even if test fail. BTW, this is when they are valuable. + if: ${{ !cancelled() }} + uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0 + with: + path: '**/unit.report.*.json' + name: 'unit.report.${{ matrix.os }}-${{ matrix.go }}' + retention-days: 1 + + fuzz-test: + uses: ./.github/workflows/fuzz-test.yml + + test-complete: + # description: | + # Be explicit about all tests being passed. This allows for setting up only a few status checks on PRs. + name: tests completed + needs: [test] + runs-on: ubuntu-latest + steps: + - + name: Tests completed + run: | + echo "::notice title=Success:All tests passed" + + collect-coverage: + needs: [test-complete] + if: ${{ !cancelled() && needs.test-complete.result == 'success' }} + uses: ./.github/workflows/collect-coverage.yml + + collect-reports: + name: collect test reports + needs: [test] + if: ${{ !cancelled() }} + uses: ./.github/workflows/collect-reports.yml diff --git a/.github/workflows/local-doc-update.yml b/experimental/local-doc-update.yml similarity index 100% rename from .github/workflows/local-doc-update.yml rename to experimental/local-doc-update.yml diff --git a/experimental/local-monorepo-go-test.yml b/experimental/local-monorepo-go-test.yml new file mode 100644 index 0000000..5cfdcd8 --- /dev/null +++ b/experimental/local-monorepo-go-test.yml @@ -0,0 +1,19 @@ +name: go test + +permissions: + contents: read + pull-requests: read + +on: + push: + tags: + - v* + branches: + - master + + pull_request: + +jobs: + go-monorepo-test: + uses: ./.github/workflows/monorepo-go-test.yml + secrets: inherit diff --git a/experimental/markdown-lint.yml b/experimental/markdown-lint.yml new file mode 100644 index 0000000..33fe637 --- /dev/null +++ b/experimental/markdown-lint.yml @@ -0,0 +1,272 @@ +name: doc update check +# description: | +# This workflow is designed to help improve documentation quality. +# +# It proceeds with markdown linting and checks spelling in markdown files every time a markdown file is changed +# in a pull request. +# +# > NOTE: this workflow is only concerned with markdown documentation, not documentation in code (e.g. godoc). +# +# ## Usage of github action features +# +# * shared workflow +# * temporary token exchange using github app to elevate privileges within a trusted workflow +# * job summary (on actions UI) +# +# ## Limitations of github action features +# +# * [ ] did not find a way yet to retrieve the repo repo specified by the caller of this workflow. +# Had to resort to `master` to retrieve extra config files. +# +# ## TODO +# +# * [ ] should make an adapted version that runs on schedule and analyzes all markdown. +# * [ ] in this case, instead of commenting pull requests, it should raise issues. +# * [ ] should be able to retrieve config files and dictionary from the called ref, not master. +# * [ ] should be able to merge config files and dictionary with local definitions on target repo. +# * [ ] should be able to work on diff +# * [ ] should format the output of spellcheck report + +on: + workflow_call: + +permissions: + contents: read + +env: + artifacts_dir: artifacts + + markdown_comment_title: Markdown linter + markdown_config: '.github/.markdownlint.yml' + markdown_artifact: markdown_comment.txt + +jobs: + markdown-changed: + uses: ./.github/workflows/markdown-changed.yml + + markdown-lint: + needs: markdown-changed + if: ${{ needs.markdown-changed.outputs.proceed == 'true' }} + runs-on: ubuntu-latest + env: + lintreport: './markdownlint-report.txt' + outputs: + proceed: ${{ steps.report-exists.outputs.proceed }} + congrats: ${{ steps.congrats.outputs.proceed }} + report: ${{ steps.report-exists.outputs.report }} + steps: + - + name: Originating repo checkout (e.g. public fork) + uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + with: + ref: ${{ github.event.pull_request.head.sha }} + - + name: Checkout markdown config + uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + with: + repository: go-openapi/ci-workflows + ref: master # TODO: retrieve workflow ref + sparse-checkout: | + ${{ env.markdown_config }} + sparse-checkout-cone-mode: false + path: ci-tools + - + name: Copy markdown config + # TODO: merge with local if present + run: | + cp ci-tools/"${{ env.markdown_config}}" "${{ env.markdown_config }}" + - + name: Run markdown linter + id: markdownlint + uses: DavidAnson/markdownlint-cli2-action@v21 + continue-on-error: true + with: + config: ./${{ env.markdown_config }} + globs: '${{ needs.markdown-changed.outputs.all_changed_files }}' + separator: ',' + output: '${{ env.lintreport }}' + # fix: true + - + name: Comment on success + if: ${{ steps.markdownlint.outcome == 'success' }} + id: congrats + run: | + echo "::notice:: no linting issue with changed markdown" + echo "proceed=true" >> $GITHUB_OUTPUT + - + name: Comment on markdown lint complaining + if: ${{ steps.markdownlint.outcome != 'success' && hashFiles(env.lintreport) != '' }} + id: report-exists + run: | + echo 'report<> $GITHUB_OUTPUT + cat ${{ env.lintreport }}|sed -e '$a\' >> $GITHUB_OUTPUT + echo 'EOF' >> $GITHUB_OUTPUT + + if [[ "$(cat ${{ env.lintreport }}|wc -l)" != "0" ]] ; then + echo "proceed=true" >> $GITHUB_OUTPUT + echo "::notice::Detected some linting issues with changed markdown" + cat ${{ env.lintreport }}|sed -e '$a\' + else + echo "proceed=false" >> $GITHUB_OUTPUT + echo "::notice::No linting issues with changed markdown" + fi + - + name: Other linter errors + if: ${{ steps.markdownlint.outcome != 'success' && hashFiles(env.lintreport) == '' }} + run: | + echo "::error::markdown linter encountered an error" + exit 1 + # TODO + - + name: Parse markdownlint JSON report + run: | + # TODO + - + name: Prepare PR comment + run: | + # TODO + - + name: Upload PR comment as artifact + run: | + # TODO + +# pr-markdown-congrats: +# needs: markdown-lint +# if: ${{ needs.markdown-lint.outputs.congrats == 'true' }} +# runs-on: ubuntu-latest +# outputs: +# run_id: ${{ steps.notify_markdown_congrats.outputs.run_id }} +# target_repo: ${{ steps.notify_markdown_congrats.outputs.target_repo }} +# pr_number: ${{ steps.notify_markdown_congrats.outputs.pr_number }} +# pr_sha: ${{ steps.notify_markdown_congrats.outputs.pr_sha }} +# artifact_name: ${{ steps.notify_markdown_congrats.outputs.artifact_name }} +# comment_title: ${{ steps.notify_markdown_congrats.outputs.comment_title }} +# reactions: ${{ steps.notify_markdown_congrats.outputs.reactions }} +# steps: +# - +# name: Congrats +# id: notify_markdown_congrats +# run: | +# mkdir -p "${{ env.artifacts_dir }}" +# read -d '' MSG< "${{ env.artifacts_dir}}/${{ env.markdown_artifact }}" +# +# echo "### Your changes to markdown docs look good. 👍" >> $GITHUB_STEP_SUMMARY +# echo "" >> $GITHUB_STEP_SUMMARY +# echo "> ℹī¸ INFO: we use [avtodev/markdown-lint action](https://github.com/avto-dev/markdown-lint)" >> $GITHUB_STEP_SUMMARY +# +# echo "run_id=${{ github.run_id }}" >> "$GITHUB_OUTPUT" +# echo "target_repo=${{ github.repository }}" >> "$GITHUB_OUTPUT" +# echo "pr_number=${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT" +# echo "pr_sha=${{ github.event.pull_request.head.sha }}" >> "$GITHUB_OUTPUT" +# echo "artifact_name=${{ env.markdown_artifact }}" >> "$GITHUB_OUTPUT" +# echo "comment_title=${{ env.markdown_comment_title }}" >> "$GITHUB_OUTPUT" +# echo "reactions=hooray" >> "$GITHUB_OUTPUT" +# - +# name: Upload comment as artifact +# uses: actions/upload-artifact@v4 +# with: +# path: ${{ env.artifacts_dir }}/${{ env.markdown_artifact }} +# name: ${{ env.markdown_artifact }} +# +# pr-comment-markdown-congrats: +# name: Create or update congrats comment +# needs: pr-markdown-congrats +# uses: go-openapi/ci-workflows/.github/workflows/pr-comment.yml@master # <- TODO: caller's ref +# secrets: inherit +# with: +# run_id: ${{ needs.pr-markdown-congrats.outputs.run_id }} +# target_repo: ${{ needs.pr-markdown-congrats.outputs.target_repo }} +# pr_number: ${{ needs.pr-markdown-congrats.outputs.pr_number }} +# pr_sha: ${{ needs.pr-markdown-congrats.outputs.pr_sha }} +# artifact_name: ${{ needs.pr-markdown-congrats.outputs.artifact_name }} +# comment_title: ${{ needs.pr-markdown-congrats.outputs.comment_title }} +# reactions: ${{ needs.pr-markdown-congrats.outputs.reactions }} +# +# pr-markdown-report: +# needs: markdown-lint +# if: ${{ needs.markdown-lint.outputs.proceed == 'true' }} +# outputs: +# run_id: ${{ steps.notify_markdown_report.outputs.run_id }} +# target_repo: ${{ steps.notify_markdown_report.outputs.target_repo }} +# pr_number: ${{ steps.notify_markdown_report.outputs.pr_number }} +# pr_sha: ${{ steps.notify_markdown_report.outputs.pr_sha }} +# artifact_name: ${{ steps.notify_markdown_report.outputs.artifact_name }} +# comment_title: ${{ steps.notify_markdown_report.outputs.comment_title }} +# reactions: ${{ steps.notify_markdown_report.outputs.reactions }} +# runs-on: ubuntu-latest +# steps: +# - +# name: Format PR comment +# id: comment_formatter +# uses: skills/action-text-variables@v3 +# with: +# template-vars: > +# { +# "text": ${{ toJSON(needs.markdown-lint.outputs.report) }} +# } +# template-text: | +# ### ${{ env.markdown_comment_title }} +# +# Some markdown linting issues were detected in the modified .md files. ⚠ī¸ +# +# Perhaps they were already there before your changes. +# +# This check is advisory only and not blocking. Please help us adopt a nice markdown style. +# +# Markdown formatting rules are documented [here](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md). +#
+# +# ``` +# {{ text }} +# ``` +# - +# name: Slap on the wrist +# env: +# OUTPUT: "${{ steps.comment_formatter.outputs.updated-text }}" +# run: | +# mkdir -p "${{ env.artifacts_dir }}" +# printenv OUTPUT > "${{ env.artifacts_dir}}/${{ env.markdown_artifact }}" +# +# echo "### Changed markdown docs need some formatting. ⚠ī¸" >> $GITHUB_STEP_SUMMARY +# echo "" >> $GITHUB_STEP_SUMMARY +# echo "> ℹī¸ INFO: we use [avtodev/markdown-lint action](https://github.com/avto-dev/markdown-lint)" >> $GITHUB_STEP_SUMMARY +# - +# name: Upload comment as artifact +# uses: actions/upload-artifact@v4 +# with: +# path: ${{ env.artifacts_dir }}/${{ env.markdown_artifact }} +# name: ${{ env.markdown_artifact }} +# - +# name: Notify +# id: notify_markdown_report +# run: | +# echo "::notice::Commented pull request ${{ github.event.pull_request.number }}" +# +# echo "run_id=${{ github.run_id }}" >> "$GITHUB_OUTPUT" +# echo "target_repo=${{ github.repository }}" >> "$GITHUB_OUTPUT" +# echo "pr_number=${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT" +# echo "pr_sha=${{ github.event.pull_request.head.sha }}" >> "$GITHUB_OUTPUT" +# echo "artifact_name=${{ env.markdown_artifact }}" >> "$GITHUB_OUTPUT" +# echo "comment_title=${{ env.markdown_comment_title }}" >> "$GITHUB_OUTPUT" +# echo "reactions=confused" >> "$GITHUB_OUTPUT" +# +# pr-comment-markdown-report: +# name: Create or update comment with report +# needs: pr-markdown-report +# uses: go-openapi/ci-workflows/.github/workflows/pr-comment.yml@master # <- TODO: caller's ref +# secrets: inherit +# with: +# run_id: ${{ needs.pr-markdown-report.outputs.run_id }} +# target_repo: ${{ needs.pr-markdown-report.outputs.target_repo }} +# pr_number: ${{ needs.pr-markdown-report.outputs.pr_number }} +# pr_sha: ${{ needs.pr-markdown-report.outputs.pr_sha }} +# artifact_name: ${{ needs.pr-markdown-report.outputs.artifact_name }} +# comment_title: ${{ needs.pr-markdown-report.outputs.comment_title }} +# reactions: ${{ needs.pr-markdown-report.outputs.reactions }} diff --git a/experimental/markdown-spellcheck.yml b/experimental/markdown-spellcheck.yml new file mode 100644 index 0000000..c26f375 --- /dev/null +++ b/experimental/markdown-spellcheck.yml @@ -0,0 +1,270 @@ +name: Markdown spellcheck + +on: + workflow_call: + +permissions: + contents: read + +env: + artifacts_dir: artifacts + + spellcheck_comment_title: Markdown spelling check + spellcheck_config: .github/.spellcheck.yml + spellcheck_dict: .github/.wordlist.txt + spellcheck_artifact: spellcheck_comment.txt + +jobs: + markdown-changed: + uses: ./.github/workflows/markdown-changed.yml + + markdown-spellcheck: + needs: markdown-changed + if: ${{ needs.markdown-changed.outputs.proceed == 'true' }} + runs-on: ubuntu-latest + env: + spellcheckreport: './spellcheck-report.txt' + outputs: + proceed: ${{ steps.report-exists.outputs.proceed }} + congrats: ${{ steps.congrats.outputs.proceed }} + report: ${{ steps.report-exists.outputs.report }} + steps: + - + uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + with: + ref: ${{ github.event.pull_request.head.sha }} + - + name: Checkout spellcheck config + uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + with: + repository: go-openapi/ci-workflows + ref: master # TODO: retrieve workflow ref + sparse-checkout: | + ${{ env.spellcheck_config }} + ${{ env.spellcheck_dict }} + sparse-checkout-cone-mode: false + path: ci-tools + - + name: Copy spellcheck config + # TODO: merge with local if present + run: | + cp ci-tools/${{ env.spellcheck_config }} ${{ env.spellcheck_config }} + cp ci-tools/${{ env.spellcheck_dict }} ${{ env.spellcheck_dict }} + - + name: Spellcheck + id: spellcheck + uses: crate-ci/typos@master + continue-on-error: true + with: + config_path: ${{ env.spellcheck_config }} + source_files: '${{ needs.markdown-changed.outputs.all_changed_files }}' + task_name: markdown + output_file: ${{ env.spellcheckreport }} + # TODO + - + name: Parse markdownlint JSON report + run: | + # TODO + - + name: Prepare PR comment + run: | + # TODO + - + name: Upload PR comment as artifact + run: | + # TODO +# - +# name: Comment on success +# if: ${{ steps.spellcheck.outcome == 'success' }} +# id: congrats +# run: | +# echo "::notice:: no spelling issue with changed markdown" +# echo "proceed=true" >> $GITHUB_OUTPUT +# +# echo "### Your changes to markdown docs show impeccable spelling. 👍" >> $GITHUB_STEP_SUMMARY +# echo "" >> $GITHUB_STEP_SUMMARY +# echo "> ℹī¸ INFO: we use [rojopolis/spellcheck-github-actions](https://github.com/rojopolis/spellcheck-github-actions)" >> $GITHUB_STEP_SUMMARY +# - +# name: Comment on spellcheck complaining +# if: ${{ steps.spellcheck.outcome != 'success' && hashFiles(env.spellcheckreport) != '' }} +# id: report-exists +# run: | +# echo 'report<> $GITHUB_OUTPUT +# cat ${{ env.spellcheckreport }}|sed -e '$a\' >> $GITHUB_OUTPUT +# echo 'EOF' >> $GITHUB_OUTPUT +# +# if [[ "$(cat ${{ env.spellcheckreport }}|wc -l)" != "0" ]] ; then +# echo "proceed=true" >> $GITHUB_OUTPUT +# echo "::notice::Detected some spelling issues with changed markdown" +# cat ${{ env.lintreport }}|sed -e '$a\' +# else +# echo "proceed=false" >> $GITHUB_OUTPUT +# echo "::notice::No spelling issues with changed markdown" +# fi +# - +# name: Other linter errors +# if: ${{ steps.spellcheck.outcome != 'success' && hashFiles(env.spellcheckreport) == '' }} +# run: | +# echo "::error::spellcheck encountered an error" +# exit 1 +# +# pr-markdown-spelling-congrats: +# needs: markdown-spelling +# if: ${{ needs.markdown-spelling.outputs.congrats == 'true' }} +# outputs: +# run_id: ${{ steps.notify_spelling_congrats.outputs.run_id }} +# target_repo: ${{ steps.notify_spelling_congrats.outputs.target_repo }} +# pr_number: ${{ steps.notify_spelling_congrats.outputs.pr_number }} +# pr_sha: ${{ steps.notify_spelling_congrats.outputs.pr_sha }} +# artifact_name: ${{ steps.notify_spelling_congrats.outputs.artifact_name }} +# comment_title: ${{ steps.notify_spelling_congrats.outputs.comment_title }} +# reactions: ${{ steps.notify_spelling_congrats.outputs.reactions }} +# runs-on: ubuntu-latest +# steps: +# - +# name: Congrats +# id: notify_spelling_congrats +# run: | +# mkdir -p artifacts +# read -d '' MSG< "${{ env.artifacts_dir }}/${{ env.spellcheck_artifact }}" +# +# echo "run_id=${{ github.run_id }}" >> "$GITHUB_OUTPUT" +# echo "target_repo=${{ github.repository }}" >> "$GITHUB_OUTPUT" +# echo "pr_number=${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT" +# echo "pr_sha=${{ github.event.pull_request.head.sha }}" >> "$GITHUB_OUTPUT" +# echo "artifact_name=${{ env.spellcheck_artifact }}" >> "$GITHUB_OUTPUT" +# echo "comment_title=${{ env.spellcheck_comment_title }}" >> "$GITHUB_OUTPUT" +# echo "reactions=hooray" >> "$GITHUB_OUTPUT" +# - +# name: Upload comment as artifact +# uses: actions/upload-artifact@v4 +# with: +# path: ${{ env.artifacts_dir }}/${{ env.spellcheck_artifact }} +# name: ${{ env.spellcheck_artifact }} +# +# pr-comment-spelling-congrats: +# name: Create or update comment +# needs: pr-markdown-spelling-congrats +# uses: go-openapi/ci-workflows/.github/workflows/pr-comment.yml@master # <- TODO: caller's ref +# secrets: inherit +# with: +# run_id: ${{ needs.pr-markdown-spelling-congrats.outputs.run_id }} +# target_repo: ${{ needs.pr-markdown-spelling-congrats.outputs.target_repo }} +# pr_number: ${{ needs.pr-markdown-spelling-congrats.outputs.pr_number }} +# pr_sha: ${{ needs.pr-markdown-spelling-congrats.outputs.pr_sha }} +# artifact_name: ${{ needs.pr-markdown-spelling-congrats.outputs.artifact_name }} +# comment_title: ${{ needs.pr-markdown-spelling-congrats.outputs.comment_title }} +# reactions: ${{ needs.pr-markdown-spelling-congrats.outputs.reactions }} +# +# pr-markdown-spelling-report: +# needs: markdown-spelling +# if: ${{ needs.markdown-spelling.outputs.proceed == 'true' }} +# outputs: +# run_id: ${{ steps.notify_spelling_report.outputs.run_id }} +# target_repo: ${{ steps.notify_spelling_report.outputs.target_repo }} +# pr_number: ${{ steps.notify_spelling_report.outputs.pr_number }} +# pr_sha: ${{ steps.notify_spelling_report.outputs.pr_sha }} +# artifact_name: ${{ steps.notify_spelling_report.outputs.artifact_name }} +# comment_title: ${{ steps.notify_spelling_report.outputs.comment_title }} +# reactions: ${{ steps.notify_spelling_report.outputs.reactions }} +# runs-on: ubuntu-latest +# steps: +# - +# name: Pre-process spellcheck report +# id: preprocess +# env: +# MSG: ${{ needs.markdown-spelling.outputs.report }} +# SED_CMD: .github/workflows/scripts/filter.sed # a sed script to parse and reformat the spellcheck report +# JQ_CMD: .github/workflows/scripts/merge.jq # a jq script to dedupe spellcheck reports by file +# TMPFILE: /tmp/spellcheck-report.txt +# run: | +# export MSG +# printenv MSG > "${TMPFILE}" +# # produces a JSON object: +# # { +# # "file.md": [ mispelled word [, ...]] +# # } +# cat "${TMPFILE}" | sed -n -f "${SED_CMD}" | jq -s "${JQ_CMD}" > /tmp/preprocessed.txt +# +# echo 'report<> $GITHUB_OUTPUT +# cat /tmp/preprocessed.txt|sed -e '$a\' >> $GITHUB_OUTPUT +# echo 'EOF' >> $GITHUB_OUTPUT +# - +# name: Format PR comment +# id: comment_formatter +# uses: skills/action-text-variables@v3 +# with: +# template-vars: > +# { +# "text": ${{ steps.preprocess.outputs.report) }} +# } +# template-text: | +# ### ${{ env.spellcheck_comment_title }} +# +# Some mispelled words were detected in the modified .md files. ⚠ī¸ +# +# Perhaps they were already there before your changes. +# +# This check is advisory only and not blocking. Please help us improve our documentation. +#
+# +# ``` +# ### TODO: range json +# {{ text }} +# ``` +# - +# name: Slap on the wrist +# env: +# OUTPUT: "${{ steps.comment_formatter.outputs.updated-text }}" +# run: | +# mkdir -p "${{ env.artifacts_dir }}" +# printenv OUTPUT > "${{ env.artifacts_dir}}/${{ env.spellcheck_artifact }}" +# +# echo "### Changed markdown docs show some mispelled words. ⚠ī¸" >> $GITHUB_STEP_SUMMARY +# echo "" >> $GITHUB_STEP_SUMMARY +# echo "> ℹī¸ INFO: we use [rojopolis/spellcheck-github-actions](https://github.com/rojopolis/spellcheck-github-actions)." >> $GITHUB_STEP_SUMMARY +# echo ">" >> $GITHUB_STEP_SUMMARY +# echo "> As a general rule, technical terms or acronyms and references to code objects should be backquoted in markdown" >> $GITHUB_STEP_SUMMARY +# - +# name: Upload comment as artifact +# # description: | +# # Calls a trusted shared workflow that temporarily elevates the caller's privileges +# # to write a comment in the PR. +# uses: actions/upload-artifact@v4 +# with: +# path: ${{ env.artifacts_dir }}/${{ env.spellcheck_artifact }} +# name: ${{ env.spellcheck_artifact }} +# - +# name: Notify +# id: notify_spelling_report +# run: | +# echo "::notice::Commented pull request ${{ github.event.pull_request.number }}" +# +# echo "run_id=${{ github.run_id }}" >> "$GITHUB_OUTPUT" +# echo "target_repo=${{ github.repository }}" >> "$GITHUB_OUTPUT" +# echo "pr_number=${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT" +# echo "pr_sha=${{ github.event.pull_request.head.sha }}" >> "$GITHUB_OUTPUT" +# echo "artifact_name=${{ env.spellcheck_artifact }}" >> "$GITHUB_OUTPUT" +# echo "comment_title=${{ env.spellcheck_comment_title }}" >> "$GITHUB_OUTPUT" +# echo "reactions=confused" >> "$GITHUB_OUTPUT" +# +# pr-comment-spelling-report: +# name: Create or update comment +# needs: pr-markdown-spelling-report +# secrets: inherit +# uses: ./.github/workflows/pr-comment.yml +# with: +# run_id: ${{ needs.pr-markdown-spelling-report.outputs.run_id }} +# target_repo: ${{ needs.pr-markdown-spelling-report.outputs.target_repo }} +# pr_number: ${{ needs.pr-markdown-spelling-report.outputs.pr_number }} +# pr_sha: ${{ needs.pr-markdown-spelling-report.outputs.pr_sha }} +# artifact_name: ${{ needs.pr-markdown-spelling-report.outputs.artifact_name }} +# comment_title: ${{ needs.pr-markdown-spelling-report.outputs.comment_title }} +# reactions: ${{ needs.pr-markdown-spelling-report.outputs.reactions }} diff --git a/.github/workflows/pr-comment.yml b/experimental/pr-comment.yml similarity index 100% rename from .github/workflows/pr-comment.yml rename to experimental/pr-comment.yml From 2541f50dbc01a0cf1862456d16895b364d304995 Mon Sep 17 00:00:00 2001 From: "bot-go-openapi[bot]" <246880138+bot-go-openapi[bot]@users.noreply.github.com> Date: Tue, 2 Dec 2025 21:51:27 +0000 Subject: [PATCH 28/28] doc: updated contributors file --- CONTRIBUTORS.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 CONTRIBUTORS.md diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md new file mode 100644 index 0000000..5fe9362 --- /dev/null +++ b/CONTRIBUTORS.md @@ -0,0 +1,13 @@ +# Contributors + +- Repository: ['go-openapi/ci-workflows'] + +| Total Contributors | Total Contributions | +| --- | --- | +| 1 | 27 | + +| Username | All Time Contribution Count | All Commits | +| --- | --- | --- | +| @fredbi | 27 | https://github.com/go-openapi/ci-workflows/commits?author=fredbi | + + _this file was generated by the [Contributors GitHub Action](https://github.com/github/contributors)_