diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md deleted file mode 100644 index c951263..0000000 --- a/.github/CONTRIBUTING.md +++ /dev/null @@ -1,251 +0,0 @@ -You'll find here general guidelines to contribute to this project. -They mostly correspond to standard practices for open source repositories. - -We have tried to keep things as simple as possible. - -> [!NOTE] -> If you're an experienced 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 apply the usual guidelines for a go library project on github. - -These guidelines are common to all libraries published on github by the `go-openapi` organization, -so you'll feel at home with any of our projects. - -You'll find more detailed (or repo-specific) instructions in the [maintainer's docs][maintainers-doc]. - -[maintainers-doc]: ../docs/MAINTAINERS.md - -## How can I contribute - -There are many ways in which you can contribute, not just code. Here are a few ideas: - -- Reporting issues or bugs -- Suggesting improvements -- Documentation -- Art work that makes the project look great -- Code - - proposing bug fixes and new features that are within the main project scope - - improving test coverage - - addressing code quality issues - -## Questions & issues - -### Asking a question - -You may inquire anything about this library by reporting a "Question" issue on github. - -You may also join our discord server where you may discuss issues or requests. - -[![Discord Server][discord-badge]][discord-url] - -[discord-badge]: https://img.shields.io/discord/1446918742398341256?logo=discord&label=discord&color=blue -[discord-url]: https://discord.gg/FfnFYaC3k5 - -### 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 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've 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 lose track of things on big PRs. - -We're trying very hard to keep the go-openapi packages lean and focused. - -Together, these packages constitute a toolkit for go developers: -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 minimal go compiler version required is always the old stable (latest minor go version - 1). - -Our libraries are designed and tested to work on `Linux`, `MacOS` and `Windows`. - -If you're 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 bug fixing 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 at least 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 a feature. - -Most documentation for this library is directly found in code as comments for godoc. - -The documentation for this go-openapi package is published on [the public go docs site][go-doc]. - ---- - -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 will run a godoc server locally where you may see the documentation generated from your local repository. - -[go-doc]: https://pkg.go.dev/github.com/go-openapi/jsonreference - -#### 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 that convention (e.g. "fix: fixed panic in XYZ", "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've squashed 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 - -Software is developed by real people. - -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-doc] (from [developercertificate.org][dco-source]) -- 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`. - -[dco-doc]: ./DCO.md -[dco-source]: https://developercertificate.org - -## Code contributions by AI agents - -Our agentic friends are welcome to contribute! - -We only have a few demands to keep-up with human maintainers. - -1. Issues and PRs written or posted by agents should always mention the original (human) poster for reference -2. We don't accept PRs attributed to agents. We don't want commits signed like "author: @claude.code". - Agents or bots may coauthor commits, though. -3. Security vulnerability reports by agents should always be reported privately and mention the original (human) poster - (see also [Security Policy][security-doc]). - -[security-doc]: ../SECURITY.md diff --git a/.github/DCO.md b/.github/DCO.md deleted file mode 100644 index e168dc4..0000000 --- a/.github/DCO.md +++ /dev/null @@ -1,40 +0,0 @@ - # 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/README.md b/README.md index d84b9bd..43d05b0 100644 --- a/README.md +++ b/README.md @@ -14,15 +14,9 @@ An implementation of JSON Reference for golang. + ## Status @@ -74,9 +68,9 @@ on top of which it has been built. ## Other documentation * [All-time contributors](./CONTRIBUTORS.md) -* [Contributing guidelines](.github/CONTRIBUTING.md) -* [Maintainers documentation](docs/MAINTAINERS.md) -* [Code style](docs/STYLE.md) +* [Contributing guidelines][contributing-doc-site] +* [Maintainers documentation][maintainers-doc-site] +* [Code style][style-doc-site] ## Cutting a new release @@ -125,3 +119,7 @@ Maintainers can cut a new release by either: [goversion-url]: https://github.com/go-openapi/jsonreference/blob/master/go.mod [top-badge]: https://img.shields.io/github/languages/top/go-openapi/jsonreference [commits-badge]: https://img.shields.io/github/commits-since/go-openapi/jsonreference/latest + +[contributing-doc-site]: https://go-openapi.github.io/doc-site/contributing/contributing/index.html +[maintainers-doc-site]: https://go-openapi.github.io/doc-site/maintainers/index.html +[style-doc-site]: https://go-openapi.github.io/doc-site/contributing/style/index.html diff --git a/docs/.gitkeep b/docs/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/MAINTAINERS.md b/docs/MAINTAINERS.md deleted file mode 100644 index 019c5ce..0000000 --- a/docs/MAINTAINERS.md +++ /dev/null @@ -1,186 +0,0 @@ -> [!NOTE] -> Comprehensive guide for maintainers covering repository structure, CI/CD workflows, release procedures, and development practices. -> Essential reading for anyone contributing to or maintaining this project. - -## Repo structure - -This project is organized as a repo with a single go module. - -## 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 - * All tests completed -* Auto-merge enabled (used for dependabot updates and other auto-merged PR's, e.g. contributors update) - -## Continuous Integration - -### Code Quality checks - -* meta-linter: [golangci-lint][golangci-url] -* linter config: [`.golangci.yml`][linter-config] (see our [posture][style-doc] on linters) -* Code quality assessment: [CodeFactor][codefactor-url] -* Code quality badges - * [go report card][gocard-url] - * [CodeFactor][codefactor-url] - -> **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/go-openapi`). -> -> 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 across `go-openapi` use our fork of `stretchr/jsonreference` (this repo): `github.com/go-openapi/jsonreference`. -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/go-openapi`). -> -> 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`][dependabot-config] - - Principle: - - * codecov applies updates and security patches to the github-actions and golang ecosystems. - * all updates from "trusted" dependencies (github actions, golang.org packages, go-openapi packages - are auto-merged if they successfully pass CI. - -* go version updates - - 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). - - > This means that our projects always have a 6 months lag to enforce new features from the go compiler. - > - > However, new features of go may be used with a "go:build" tag: this allows users of the newer - > version to benefit the new feature while users still running with `oldstable` use another version - > that still builds. - -* contributors - * a [`CONTRIBUTORS.md`][contributors-doc] 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 - -**For single module repos:** - -A bump release workflow can be triggered from the github actions UI to cut a release with a few clicks. - -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: the `.cliff.toml` is defined as a share configuration on - remote repo [`ci-workflows/.cliff.toml`][remote-cliff-config] - -Commits from maintainers are preferably PGP-signed. - -Tags are preferably PGP-signed. - -We want our releases to show as "verified" on github. - -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". - -**For mono-repos with multiple modules:** - -The release process is slightly different because we need to update cross-module dependencies -before pushing a tag. - -A bump release workflow (mono-repo) can be triggered from the github actions UI to cut a release with a few clicks. - -It works with the same input as the one for single module repos, and first creates a PR (auto-merged) -that updates the different go.mod files _before_ pushing the desired git tag. - -Commits and tags pushed by the workflow bot are PGP-signed ("go-openapi[bot]"). - -## Other files - -Standard documentation: - -* [CONTRIBUTING.md][contributing-doc] guidelines -* [DCO.md][dco-doc] terms for first-time contributors to read -* [CODE_OF_CONDUCT.md][coc-doc] -* [SECURITY.md][security-doc] policy: how to report vulnerabilities privately -* [LICENSE][license-doc] terms -* [NOTICE][notice-doc] on supplementary license terms (original authors, copied code etc) - -Reference documentation (released): - -* [pkg.go.dev (fka godoc)][godoc-url] - - -[linter-config]: https://github.com/go-openapi/jsonreference/blob/master/.golangci.yml -[local-cliff-config]: https://github.com/go-openapi/jsonreference/blob/master/.cliff.toml -[remote-cliff-config]: https://github.com/go-openapi/ci-workflows/blob/master/.cliff.toml -[dependabot-config]: https://github.com/go-openapi/jsonreference/blob/master/.github/dependabot.yaml -[gocard-url]: https://goreportcard.com/report/github.com/go-openapi/jsonreference -[codefactor-url]: https://www.codefactor.io/repository/github/go-openapi/jsonreference -[golangci-url]: https://golangci-lint.run/ -[godoc-url]: https://pkg.go.dev/github.com/go-openapi/jsonreference -[contributors-doc]: ../CONTRIBUTORS.md -[contributing-doc]: ../.github/CONTRIBUTING.md -[dco-doc]: ../.github/DCO.md -[style-doc]: STYLE.md -[coc-doc]: ../CODE_OF_CONDUCT.md -[security-doc]: ../SECURITY.md -[license-doc]: ../LICENSE -[notice-doc]: ../NOTICE diff --git a/docs/STYLE.md b/docs/STYLE.md deleted file mode 100644 index e6e1859..0000000 --- a/docs/STYLE.md +++ /dev/null @@ -1,117 +0,0 @@ -# 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 and linting. -> -> 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 together 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 [the linter's configuration reference][golangci-doc] for additional reference. - -This configuration is essentially the same across all `go-openapi` projects. - -Some projects may require slightly different settings. - -## 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. - -### Our approach: evaluate, don't consume blindly - -As early adopters of `golangci-lint` (and its predecessors), we've watched linting orthodoxy -shift back and forth over the years. Patterns that were idiomatic one year get flagged the next; -rules that seemed reasonable in isolation produce noise at scale. Conversations with maintainers -of other large Go projects confirmed what our own experience taught us: -**the default linter set is a starting point, not a prescription**. - -Our stance is deliberate: - -- **Start from `default: all`**, then consciously disable what doesn't earn its keep. - This forces us to evaluate every linter and articulate why we reject it — the disabled list - is a design rationale, not technical debt. -- **Tune thresholds rather than disable** when a linter's principle is sound but its defaults - are too aggressive for a mature codebase. -- **Require justification for every `//nolint`** directive. Each one must carry an inline comment - explaining why it's there. -- **Prefer disabling a linter over scattering `//nolint`** across the codebase. If a linter - produces systematic false positives on patterns we use intentionally, the linter goes — - not our code. -- **Keep the configuration consistent** across all `go-openapi` repositories. Per-repo - divergence is a maintenance tax we don't want to pay. - -We enable all linters published by `golangci-lint` by default, then disable a few ones. - -Here are the reasons why they are disabled (update: Feb. 2026, `golangci-lint v2.8.0`). - -```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 - - thelper # too many false positives on test case factories returning func(*testing.T). See note below - - 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 objective 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. - -**Relaxed linter settings** - -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. - -[golangci-yml]: https://github.com/go-openapi/jsonreference/blob/master/.golangci.yml -[golangci-doc]: https://golangci-lint.run/docs/linters/configuration/