From f8bb2cd1fedfb8d8083220b7bf3c59e1fff56ad9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Flendrich?= Date: Fri, 10 Jan 2025 18:44:40 +0100 Subject: [PATCH 1/2] Re-add contributing.md deleted in 1fbdf0339dbe0ad842d1840f528fb55357484277 Update contribution guide Our contribution guide is very outdated and recommends style we don't use anymore. Content was updated to follow our existing style and lays out a coding convention and code review standard. Apply suggestions from code review Co-authored-by: Kacper Rzetelski <32443348+rzetelskik@users.noreply.github.com> --- docs/source/contributing.md | 87 +++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 docs/source/contributing.md diff --git a/docs/source/contributing.md b/docs/source/contributing.md new file mode 100644 index 00000000000..936e297813b --- /dev/null +++ b/docs/source/contributing.md @@ -0,0 +1,87 @@ +# Contributing to Scylla Operator + +## Prerequisites + +To develop Scylla Operator, ensure your environment has the following items configured: + +1. [Go](https://golang.org/dl) + * Check `go.mod` for minimal version requirement. +2. Git client +3. GitHub account + +## Initial Setup + +### Fork the repository + +Follow GitHub's official documentation on [forking a repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo). + +## Development + +To add a feature or to make a bug fix, you will need to create a branch in your fork and then submit a pull request (PR) from the branch. +A subset of useful commands: +* `make build` - build project binaries +* `make test-unit` - run unit tests +* `make update` - run all code generators +* `make verify` - verify if all autogenerated changes are generated. + +Check `make help` for more. + +## Coding convention + +Follow these guidelines for writing and structuring your code: +* [Effective Go](https://go.dev/doc/effective_go) +* [Go Code Review Comments](https://go.dev/wiki/CodeReviewComments) +* [API changes](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md) +* [API conventions](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md) + + +In cases where the existing code doesn't fully follow these conventions, try to be consistent with what's already there. Make sure to familiarize yourself with these resources before making changes. + +## Enhancement proposals + +For significant features or API changes, you might be required to prepare an enhancement proposal beforehand, as these usually involve broader discussions. If unsure, please consult the [maintainers of the project](https://github.com/scylladb/scylla-operator/blob/master/OWNERS) to learn if your contribution falls into these categories before you start working on the implementation. +For further details, see [Enhancement Proposals directory](https://github.com/scylladb/scylla-operator/tree/master/enhancements). + +## Submitting a Pull Request + +Once you have implemented the feature or bug fix in your branch, open a PR to the upstream repository. Before doing so, ensure the following: +- Unit tests are included. +- End-to-end tests are passing. +- Your commit history is clean. + +### Commit History + +To maintain a clean commit history, aim for a minimal number of logical commits. Typically, this means a single commit that contains all the changes, with a separate commit for autogenerated parts. + +### Commits and PRs + +The first line of your commit message and PR title should summarize the change in one clear sentence that would be meaningful to a user of the Operator. The sentence should use a verb in its base form to describe the change, e.g. "Add support for XYZ." . +Every release note is based on these first lines, so make them concise yet informative. + +If you have more to say about the change, then enter a blank line and carry on the description. +Remember to say why the change was needed - the commit itself shows what was changed. + +Writing more is better than less. Comparing the behavior before the change to that after the change is beneficial. +Imagine writing to yourself in 12 months when you've forgotten everything about what you just did, and you need to get up to speed quickly. + +If the change fixes an issue, then write Fixes #1234 in the PR description. + +Here is an example of a good commit message and PR title/description: +``` + +Add new XYZ field to ScyllaCluster CRD. + +The new field allows for configuration of ZYX feature of ScyllaDB. + +API change was discussed in the following enhancement: . + +Fixes #1234 +``` + +### Code review + +Refer to [The Standard of Code Review](https://github.com/golang/go/wiki/CodeReviewComments) for best practices when conducting peer reviews or responding to feedback. + +### Submitting + +After addressing the review feedback, squash your changes into the original commits. Avoid adding new commits. Your PR should always be in a mergeable state. From 05b34c796800894bb432548607268e33cc8cc839 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Flendrich?= Date: Mon, 13 Jan 2025 08:40:29 +0100 Subject: [PATCH 2/2] Move the contributing guide to the repo root Update CONTRIBUTING.md Co-authored-by: Kacper Rzetelski <32443348+rzetelskik@users.noreply.github.com> --- .../source/contributing.md => CONTRIBUTING.md | 29 +++++-------------- 1 file changed, 7 insertions(+), 22 deletions(-) rename docs/source/contributing.md => CONTRIBUTING.md (71%) diff --git a/docs/source/contributing.md b/CONTRIBUTING.md similarity index 71% rename from docs/source/contributing.md rename to CONTRIBUTING.md index 936e297813b..1df188cc8a5 100644 --- a/docs/source/contributing.md +++ b/CONTRIBUTING.md @@ -1,14 +1,5 @@ # Contributing to Scylla Operator -## Prerequisites - -To develop Scylla Operator, ensure your environment has the following items configured: - -1. [Go](https://golang.org/dl) - * Check `go.mod` for minimal version requirement. -2. Git client -3. GitHub account - ## Initial Setup ### Fork the repository @@ -55,27 +46,21 @@ To maintain a clean commit history, aim for a minimal number of logical commits. ### Commits and PRs -The first line of your commit message and PR title should summarize the change in one clear sentence that would be meaningful to a user of the Operator. The sentence should use a verb in its base form to describe the change, e.g. "Add support for XYZ." . -Every release note is based on these first lines, so make them concise yet informative. - -If you have more to say about the change, then enter a blank line and carry on the description. -Remember to say why the change was needed - the commit itself shows what was changed. +The **subject line** of your commit message **and the PR title** should summarize the change in one clear sentence that would be meaningful to a user of the Operator. The sentence should be **written in the imperative**, i.e. written as if giving a command or instruction, e.g. "Add support for XYZ". A properly formed Git commit subject line should always be able to complete the sentence "If applied, this commit will...", e.g. "If applied, this commit will **Add support for XYZ**". +Changelog entries are verbatim PR titles, so make them concise yet informative. -Writing more is better than less. Comparing the behavior before the change to that after the change is beneficial. -Imagine writing to yourself in 12 months when you've forgotten everything about what you just did, and you need to get up to speed quickly. +Further details should be added after a blank line. Explain why the change was necessary, not just what was changed. In the general case, extensive descriptions are well-received. Comparing the behavior before and after the change is especially helpful. Write the message with the mindset that you’ll need to revisit the code in the future. +If your PR fixes an issue, include "Resolves #1234" in the description, replacing "1234" with the issue number. -If the change fixes an issue, then write Fixes #1234 in the PR description. - -Here is an example of a good commit message and PR title/description: ``` - +**Description of your changes:** Add new XYZ field to ScyllaCluster CRD. - The new field allows for configuration of ZYX feature of ScyllaDB. API change was discussed in the following enhancement: . -Fixes #1234 +**Which issue is resolved by this Pull Request:** +Resolves #1234 ``` ### Code review