- Types of Contributions
- Fix Bugs
- Development
- Changelog Entries
- Contributor License Agreement
- Code reviews
Contributions are welcome, and they are greatly appreciated! There's no such thing as a contribution that is "too small". Grammar and spelling corrections are just as important as fixing bugs or adding features. Every little bit helps, and credit will always be given.
You can contribute in many ways:
Report bugs in the GitHub Issues tracker.
If you are reporting a bug, please include:
- Your operating system name and version.
- Any details about your local setup that might be helpful in troubleshooting.
- Detailed steps to reproduce the bug.
Look through the issues for bugs. Anything in that list is open to whoever wants to fix it.
Look through the issues for features. Anything in that list is open to whoever wants to implement it.
gotagger
can always use more documentation,
whether as part of the official docs or in godocs.
gotagger
uses semantic newlines in all documentation files and comments:
This is a sentence.
This is another sentance,
with a clause.
The best way to send feedback is to file an issue.
If you are proposing a feature:
- Explain in detail how it would work.
- Keep the scope as narrow as possible, to make it easier to implement.
Ready to contribute? Here's how to set up gotagger
for local development.
The gotagger
project provides a devcontainer setup for VS Code,
and a set of recommended extensions.
To use the devcontainer with VS Code, first install the Remote - Container extension.
You can either follow the Local Development instructions and mount your local clone into the devcontainer, or clone the repository into a docker volume.
Read the official documentation for details.
First,
make sure you have a supported version of go installed.
While gotagger
supports the two most recent releases,
development should be done with the lowest supported version.
You will also want GNU make >= 3.81 and pre-commit to ensure that your changes will pass our CI checks.
pre-commit install -t commit-msg -t pre-commit
-
Make a fork of the
gotagger
repository by going to https://github.com/sassoftware/gotagger and clicking on the Fork button near the top of the page. -
Clone your fork of the
gotagger
repository:git clone [email protected]:<username>/gotagger.git
-
Create a branch to track your changes.
git checkout -b my-branch-name
-
Write your changes, making sure to run the tests and linters as you work.
-
When your changes are ready, commit them to your branch.
git add . git commit
-
Push your changes to GitHub.
git push -u origin my-branch-name
Before you submit a pull request, first open an issue. All pull requests must reference an issue before they will be accepted. Additionally, check that it meets these guidelines:
- Pull requests that do not pass our CI checks will not receive feedback.
If you need help passing the CI checks,
add the
CI Triage
label to your pull request. - Tests are required for all changes. If you fix a bug, add a test to ensure that bug stays fixed. If you add a feature, add a test to show how that feature works.
- New features require new documentation.
gotagger
's API is still considered in flux, but API breaking changes need to clear a higher bar than new features.- Commits must use the [conventional commits] standard. You also may want to read How to Write a Git Commit Message. The conventional commit standard takes precedence when it and How to Write a Git Commit Message disagree.
- All changes should include a changelog entry.
Add a single file to the
.stentor.d
directory as part of your pull request named<pull request #>.(security|deprecate|remove|change|feature|fix).<short-description>.md
. See below for details.
gotagger
uses a news file management tool called stentor
to update the CHANGELOG.md file.
Changelog entries should follow these rules:
-
Use semantic newlines, just like other documentation.
-
Wrap the names of things in backticks:
like this
. -
Wrap arguments with asterisks: these or attributes.
-
Names of functions or other callables should be followed by parentheses:
my_cool_function()
. -
Use the active voice and either present tense or simple past tense.
- Added `my_cool_function()` to do cool things. - Creating `Foo` objects with the _many_ argument no longer raises a `RuntimeError`.
-
For changes that address multiple pull requests, create one fragment for the primary pull request and reference the others in the body.
Contributions to this project must be accompanied by a signed Contributor Agreement. You (or your employer) retain the copyright to your contribution, this simply gives us permission to use and redistribute your contributions as part of the project.
All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult [GitHub Help] for more information on using pull requests.