From 5ff050e6658fec798d040cb3cbbb39503e4f1d09 Mon Sep 17 00:00:00 2001 From: Jakob Borg Date: Tue, 2 Sep 2025 00:16:36 -0700 Subject: [PATCH] docs: update contribution guidelines from the docs site (#10336) This copies the relevant parts of the contribution guidelines in the docs, for the purpose of keeping them in a single place. The in-docs contribution guidelines can become a link to this document. Signed-off-by: Jakob Borg --- CONTRIBUTING.md | 119 ++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 106 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b15d98480..9f1752dda 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,20 +34,45 @@ Note that the previously used service at retired and we kindly ask you to sign up on Weblate for continued involvement. -## Contributing Code - -Every contribution is welcome. If you want to contribute but are unsure -where to start, any open issues are fair game! See the [Contribution -Guidelines](https://docs.syncthing.net/dev/contributing.html) for the full -story on committing code. - ## Contributing Documentation Updates to the [documentation site](https://docs.syncthing.net/) can be made as pull requests on the [documentation repository](https://github.com/syncthing/docs). -## The Developer Certificate of Origin (DCO) +## Contributing Code + +Every contribution is welcome. If you want to contribute but are unsure +where to start, any open issues are fair game! Here's a short rundown of +what you need to keep in mind: + +- Don't worry. You are not expected to get everything right on the first + attempt, we'll guide you through it. + +- Make sure there is an + [issue](https://github.com/syncthing/syncthing/issues) that describes the + change you want to do. If the thing you want to do does not have an issue + yet, please file one before starting work on it. + +- Fork the repository and make your changes in a new branch. Once it's ready + for review, create a pull request. + +### Authorship + +All code authors are listed in the AUTHORS file. When your first pull +request is accepted your details are added to the AUTHORS file and the list +of authors in the GUI. Commits must be made with the same name and email as +listed in the AUTHORS file. To accomplish this, ensure that your git +configuration is set correctly prior to making your first commit: + + $ git config --global user.name "Jane Doe" + $ git config --global user.email janedoe@example.com + +You must be reachable on the given email address. If you do not wish to use +your real name for whatever reason, using a nickname or pseudonym is +perfectly acceptable. + +### The Developer Certificate of Origin (DCO) The Syncthing project requires the Developer Certificate of Origin (DCO) sign-off on pull requests (PRs). This means that all commit messages must @@ -92,7 +117,79 @@ a `Signed-off-by` line to their commit messages. For example: Signed-off-by: Random J Developer The name and email address in this line must match those of the committing -author. +author, and be the same as what you want in the AUTHORS file as per above. + +### Coding Style + +#### General + +- All text files use Unix line endings. The git settings already present in + the repository attempt to enforce this. + +- When making changes, follow the brace and parenthesis style of the + surrounding code. + +#### Go Specific + +- Follow the conventions laid out in [Effective + Go](https://go.dev/doc/effective_go) as much as makes sense. The review + guidelines in [Go Code Review + Comments](https://github.com/golang/go/wiki/CodeReviewComments) should + generally be followed. + +- Each commit should be `go fmt` clean. + +- Imports are grouped per `goimports` standard; that is, standard + library first, then third party libraries after a blank line. + +### Commits + +- Commit messages (and pull request titles) should follow the [conventional + commits](https://www.conventionalcommits.org/en/v1.0.0/) specification and + be in lower case. + +- We use a scope description in the commit message subject. This is the + component of Syncthing that the commit affects. For example, `gui`, + `protocol`, `scanner`, `upnp`, etc -- typically, the part after + `internal/`, `lib/` or `cmd/` in the package path. If the commit doesn't + affect a specific component, such as for changes to the build system or + documentation, the scope should be omitted. The same goes for changes that + affect many components which would be cumbersome to list. + +- Commits that resolve an existing issue must include the issue number + as `(fixes #123)` at the end of the commit message subject. A correctly + formatted commit message looks like this: + + feat(dialer): add env var to disable proxy fallback (fixes #3006) + +- If the commit message subject doesn't say it all, one or more paragraphs of + describing text should be added to the commit message. This should explain + why the change is made and what it accomplishes. + +- When drafting a pull request, please feel free to add commits with + corrections and merge from `main` when necessary. This provides a clear time + line with changes and simplifies review. Do not, in general, rebase your + commits, as this makes review harder. + +- Pull requests are merged to `main` using squash merge. The "stream of + consciousness" set of commits described in the previous point will be reduced + to a single commit at merge time. The pull request title and description will + be used as the commit message. + +### Tests + +Yes please, do add tests when adding features or fixing bugs. Also, when a +pull request is filed a number of automatic tests are run on the code. This +includes: + +- That the code actually builds and the test suite passes. + +- That the code is correctly formatted (`go fmt`). + +- That the commits are based on a reasonably recent `main`. + +- That the output from `go lint` and `go vet` is clean. (This checks for a + number of potential problems the compiler doesn't catch.) ## Licensing @@ -106,10 +203,6 @@ otherwise stated this means MPLv2, but there are exceptions: - The documentation (man/...) is licensed under the Creative Commons Attribution 4.0 International License. -- Projects under vendor/... are copyright by and licensed from their - respective original authors. Contributions should be made to the original - project, not here. - Regardless of the license in effect, you retain the copyright to your contribution.