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.
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
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.
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.
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
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.
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:
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latestFork 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-somethingwhere 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-somethingwhere XXX is the number of the issue.
NOTE: we don't enforce naming conventions on branches: it's your fork after all.
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.
You may read our stance on code style there.
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.
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.
go install golang.org/x/pkgsite/cmd/pkgsite@latestThen run on the repository folder:
pkgsite .This will run a godoc server locally where you may see the documentation generated from your local repository.
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 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.
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 (from developercertificate.org)
- if you agree with these terms, then you just add a line to every git commit message
Signed-off-by: Joe Smith <joe@gmail.com>
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.
Our agentic friends are welcome to contribute!
We only have a few demands to keep-up with human maintainers.
- Issues and PRs written or posted by agents should always mention the original (human) poster for reference
- 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.
- Security vulnerability reports by agents should always be reported privately and mention the original (human) poster (see also Security Policy).