From e4cefac22357797364100be258951f4de0fa3279 Mon Sep 17 00:00:00 2001 From: Evan Baker Date: Tue, 26 Sep 2023 16:53:18 -0500 Subject: [PATCH] Create initial contrbuting guides (#2244) * start creating contrbuting guides Signed-off-by: Evan Baker * add CLA instructions Signed-off-by: Evan Baker --------- Signed-off-by: Evan Baker --- CONTRIBUTING.md | 14 ++++++++++++++ docs/contributing/git.md | 13 +++++++++++++ docs/contributing/github.md | 21 +++++++++++++++++++++ docs/contributing/go.md | 5 +++++ 4 files changed, 53 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 docs/contributing/git.md create mode 100644 docs/contributing/github.md create mode 100644 docs/contributing/go.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..ed0745d01 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,14 @@ +## Contributing guidelines +Contributers must sign the CLA. The CLA bot will post instructions to new contributors when their first PR is opened as a comment. To agree to the CLA, respond: + +> [@microsoft-github-policy-service agree](https://github.com/microsoft/contributorlicenseagreement#accepting) + +If you have previously agreed to the CLA but the check is failing/not running, try rerunning with: + +> @microsoft-github-policy-service rerun + + +### Specific guide docs +- [GitHub contributing guidelines](docs/contributing/github.md) +- [Git best-practices guide](docs/contributing/git.md) +- [Go style guidelines](docs/contributing/go.md) diff --git a/docs/contributing/git.md b/docs/contributing/git.md new file mode 100644 index 000000000..3c3dd9799 --- /dev/null +++ b/docs/contributing/git.md @@ -0,0 +1,13 @@ +## Git best-practices guide + +Write good commit messages. +- https://chris.beams.io/posts/git-commit/ +- https://www.gitkraken.com/learn/git/best-practices/git-commit-message + +[Rebase, don't merge](https://www.atlassian.com/git/tutorials/rewriting-history/git-rebase). + + +Configure your fork to rebase from the upstream master branch by default: +```bash +git config branch.master.remote upstream && git config branch.autoSetupRebase always +``` diff --git a/docs/contributing/github.md b/docs/contributing/github.md new file mode 100644 index 000000000..b1d210eb0 --- /dev/null +++ b/docs/contributing/github.md @@ -0,0 +1,21 @@ +## GitHub contributing guidelines +### General +- Use a [forking workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow). [(How to fork)](https://help.github.com/articles/fork-a-repo/). + +### Pull Requests +Do: +- Scope PRs to the smallest self-contained change possible. +- Open one PR per change (for example: a feature addition and a refactor of related code are separate changes warranting separate PRs). +- Use a descriptive title and description. Provide enough context that anyone familiar with the codebase can understand the purpose of the change and review it. +- Include a link to a related issue if applicable. +- Attach labels. +- Assign reviewers if the automated reviewer assignment is insufficient. +- Open PRs early as a draft and add the `WIP` label to get early feedback. +- Rebase from master when your branch/PR is out of date. +- Fix review feedback in individual commits with descriptive commit messages (and link these commits in the comments). + +Do not: +- Link to private issue trackers or internal documents. +- Ask for final reviews unless CI is passing. +- Resolve reviewer comments yourself (allow the reviewer to do so once they are satisfied that their feedback is addressed). +- Close and open a new PR to address git conflicts or feedback (PRs are documentation. One PR per change). diff --git a/docs/contributing/go.md b/docs/contributing/go.md new file mode 100644 index 000000000..572cbd384 --- /dev/null +++ b/docs/contributing/go.md @@ -0,0 +1,5 @@ +### Go style guidelines +Do: +- By default follow the [Uber Go style guide](https://github.com/uber-go/). +- Prefer `zap` for structured logging. +- Prefer `pkg/errors` for error handling.