docs(contributing): add commit, branch, and PR name conventions (#78)

deckhouse · May 3, 2024 · 7cfe20b · 7cfe20b
2 parents 1375792 + 900b01e
commit 7cfe20b
Showing 1 changed file with 166 additions and 0 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,166 @@
+# Contributing
+
+## Feedback
+
+The first thing we recommend is to check the existing [issues](https://github.com/deckhouse/virtualization/issues) — there may already be a discussion or solution on your topic. If not, choose the appropriate way to address the issue on [the new issue form](https://github.com/deckhouse/virtualization/issues/new/choose).
+
+## Code contributions
+
+1. Prepare an environment. To build and run common workflows locally, you'll need to _at least_ have the following installed:
+
+   - [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+   - [Go](https://golang.org/doc/install)
+   - [Docker](https://docs.docker.com/get-docker/)
+   - [go-task](https://taskfile.dev/installation/) (task runner)
+   - [ginkgo](https://onsi.github.io/ginkgo/#installing-ginkgo) (testing framework required to run tests)
+
+2. [Fork the project](https://github.com/deckhouse/virtualization/fork).
+
+3. Clone the project:
+
+    ```shell
+    git clone https://github.com/[GITHUB_USERNAME]/virtualization
+    ```
+
+4. Create branch following the [branch name convention](#branch-name):
+
+    ```shell
+    git branch -b feat/core/add-new-feature
+    ```
+
+5. Make changes.
+
+6. Commit changes:
+
+   - Follow [the commit message convention](#commit-message).
+   - Sign off every commit you contributed as an acknowledgment of the [DCO](https://developercertificate.org/).
+
+7. Push commits. 
+
+8. Create a pull request following the [pull request name convention](#pull-request-name).
+
+## Conventions
+
+### Commit message
+
+Each commit message consists of a **header** and a [**body**](#body). The header has a special format that includes a [**type**](#type), a [**scope**](#scope) and a [**subject**](#subject):
+
+```
+<type>(<scope>): <subject>
+<BLANK LINE>
+<body>
+```
+
+**Examples:**
+
+  - _feat(api): bump resource version to v1beta1_
+  - _feat(images): implement ImageLost phase_
+  - _feat(images, vi): add PVC as a storage_
+  - _fix(vm, vmmodel): fix unsupported type of model_
+  - _refactor(core): rename 3rd party resources_
+  - _docs(module): describe how to install module_
+  - _chore(core): use alt linux as base image_
+  - _chore: update go dependencies_
+
+#### Type
+
+Must be one of the following:
+
+* **feat**: new features or capabilities that enhance the user's experience.
+* **fix**: bug fixes that enhance the user's experience.
+* **refactor**: a code changes that neither fixes a bug nor adds a feature.
+* **docs**: updates or improvements to documentation.
+* **test**: additions or corrections to tests.
+* **chore**: updates that don't fit into other types.
+
+#### Scope
+
+Scope indicates the area of the project affected by the changes. The scope can consist of a top-level scope, which broadly categorizes the changes, and can optionally include nested scopes that provide further detail.
+
+Supported scopes are the following:
+
+  ```
+  # The end-user functionalities, aiming to streamline and optimize user experiences.
+  # NOTE! The api scope should be omitted if a more specific sub-scope is used.
+  - api
+    - vm
+      - vmop
+      - vmbda
+      - vmcpu
+      - vmcpureq
+      - vmmodel
+      - vmip
+      - vmipl
+    - disks
+      - vd
+    - images
+      - vi
+      - cvi
+
+  # Core mechanisms and low-level system functionalities.
+  - core
+    - api-service
+    - vmi-router
+    - kubevirt
+    - cdi
+    - dvcr
+
+  # Integration with the Deckhouse.
+  - module
+
+  # User metrics, alerts, dashboards, and logs that provide insights into system performance and health.
+  - observability
+
+  # Maintaining, improving code quality and development workflow. 
+  - ci
+  - lint
+  - format
+  - gen
+  - dev
+  ```
+
+#### Subject
+
+The subject contains a succinct description of the change:
+
+  - use the imperative, present tense: "change" not "changed" nor "changes"
+  - don't capitalize the first letter
+  - no dot (.) at the end
+
+#### Body
+
+Just as in the **subject**, use the imperative, present tense: "change" not "changed" nor "changes".
+The body should include the motivation for the change and contrast this with previous behavior.
+
+### Branch name
+
+Each branch name consists of a [**type**](#type), [**scope**](#scope), and a [**short-description**](#short-description):
+
+```
+<type>/<scope>/<short-description>
+```
+
+When naming branches, only the top-level scope should be used. Multiple or nested scopes are not allowed in branch names, ensuring that each branch is clearly associated with a broad area of the project.
+
+**Examples:**
+
+  - _feat/disks/support-new-image-source_
+  - _chore/ci/speed-up-builds_
+
+#### Short description
+
+A concise, hyphen-separated phrase in kebab-case that clearly describes the main focus of the branch.
+
+### Pull request name
+
+Each pull request title should clearly reflect the changes introduced, adhering to [**the header format** of a commit message](#commit-message), typically mirroring the main commit's text in the PR.
+
+**Examples**
+
+  - _feat(vm): add live migration capability_
+  - _docs(api): update REST API documentation for clarity_
+
+## Coding
+
+  - [Effective Go](https://golang.org/doc/effective_go.html).
+  - [Go's commenting conventions](http://blog.golang.org/godoc-documenting-go-code).