From 99c5c282c567ff0079171444b34f31c52a4ab3fb Mon Sep 17 00:00:00 2001 From: Madhu Rajanna Date: Tue, 4 Jun 2024 10:25:57 +0200 Subject: [PATCH] doc: adding more documentation for process Adding more documentations for the process to follow. Signed-off-by: Madhu Rajanna --- LICENSE | 177 ++++++++++++++++++++++++++++++++++++++ PendingReleaseNotes.md | 7 ++ docs/DCO | 36 ++++++++ docs/coding.md | 84 ++++++++++++++++++ docs/development-guide.md | 166 +++++++++++++++++++++++++++++++++++ docs/releases.md | 47 ++++++++++ 6 files changed, 517 insertions(+) create mode 100644 LICENSE create mode 100644 PendingReleaseNotes.md create mode 100644 docs/DCO create mode 100644 docs/coding.md create mode 100644 docs/development-guide.md create mode 100644 docs/releases.md diff --git a/LICENSE b/LICENSE new file mode 100644 index 00000000..f433b1a5 --- /dev/null +++ b/LICENSE @@ -0,0 +1,177 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS diff --git a/PendingReleaseNotes.md b/PendingReleaseNotes.md new file mode 100644 index 00000000..6c4a233e --- /dev/null +++ b/PendingReleaseNotes.md @@ -0,0 +1,7 @@ +# v0.0.1 Pending Release Notes + +## Breaking Changes + +## Features + +## NOTE diff --git a/docs/DCO b/docs/DCO new file mode 100644 index 00000000..716561d5 --- /dev/null +++ b/docs/DCO @@ -0,0 +1,36 @@ +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. diff --git a/docs/coding.md b/docs/coding.md new file mode 100644 index 00000000..d3560b99 --- /dev/null +++ b/docs/coding.md @@ -0,0 +1,84 @@ +# Coding Conventions + +Please follow coding conventions and guidelines described in the following documents: + +* [Go proverbs](https://go-proverbs.github.io/) - highly recommended read +* [CodeReviewComments](https://github.com/golang/go/wiki/CodeReviewComments) +* [Effective Go](https://golang.org/doc/effective_go.html) +* [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) + +Here's a list of some more specific conventions that are often followed in the code and will be pointed out in the review process: + +## General + +* Keep variable names short for variables that are local to the function. +* Do not export a function or variable name outside the package until you have an external consumer for it. + +### Imports + +We use the following convention for specifying imports: + +``` + + + + + +``` + +Example: + +```go +import ( + "os" + "path" + "strings" + "time" + + "github.com/ceph/ceph-csi-operator/util" + + "github.com/pborman/uuid" +) +``` + +### Error Handling + +* Use variable name `err` to denote error variable during a function call. +* Localize error vars to the deepest scope possible, this allows to reuse the err var name and have a different memory location for each. For example, do not use `errWrite` or `errRead`. +* Do not panic() for errors that can be bubbled up back to user. Use panic() in higher function only for fatal errors which shouldn't occur. +* Do not ignore errors using `_` variable unless you know what you're doing. +* Error strings should not start with a capital letter. +* If error requires passing of extra information, you can define a new type. +* Error types should end with `Error`. +* Reuse existing error types as much as possible. + +### Logging + +* Utility functions should never log. Logging must almost always be done by the caller on receiving an `error`. +* Always use log level `DEBUG` to provide useful **diagnostic information** to developers or sysadmins. +* Use log level `INFO` to provide information to users or sysadmins. This is the kind of information you'd like to log in an out-of-the-box configuration in happy scenario. +* Use log level `WARN` when something fails but there's a workaround or fallback or retry for it and/or is fully recoverable. +* Use log level `ERROR` when something occurs which is fatal to the operation, but not to the service or application. + +### Wrap long lines + +At present, we restrict the number of chars in a line to `120` which is the default value for the `lll` linter check we have in CI. If your source code line or comment goes beyond this limit please try to organize it in such a way it is within the line length limit and help on code reading. + +### Mark Down Rules + +* MD014 - Dollar signs used before commands without showing output + +The dollar signs are unnecessary, it is easier to copy and paste and less noisy if the dollar signs are omitted. Especially when the command doesn't list the output, but if the command follows output we can use '$' (dollar+space) mainly to differentiate between command and its output. + + scenario 1: when command doesn't follow output + + ```console + cd ~/work + ``` + + scenario 2: when command follow output (use dollar+space) + + ```console + $ ls ~/work + file1 file2 dir1 dir2 ... + ``` diff --git a/docs/development-guide.md b/docs/development-guide.md new file mode 100644 index 00000000..acb59ab8 --- /dev/null +++ b/docs/development-guide.md @@ -0,0 +1,166 @@ +# Development Guide + +## New to Go + +Ceph-csi-operator is written in Go and if you are new to the language, +it is **highly** encouraged to: + +* Take the [A Tour of Go](http://tour.golang.org/welcome/1) course. +* [Set up](https://golang.org/doc/code.html) Go development environment on your machine. +* Read [Effective Go](https://golang.org/doc/effective_go.html) for best practices. + +## Development Workflow + +### Workspace and repository setup + +* [Download](https://golang.org/dl/) Go and + [install](https://golang.org/doc/install) it on your system. +* Clone the ceph-csi-operator + repo]() +* Fork the [ceph-csi-operator repo](https://github.com/ceph/ceph-csi-operator) on Github. +* Add your fork as a git remote: + + ```console + git remote add fork https://github.com//ceph-csi-operator + ``` + +> Editors: Our favorite editor is vim with the [vim-go](https://github.com/fatih/vim-go) +> plugin, but there are many others like [vscode](https://github.com/Microsoft/vscode-go) + +### Building ceph-csi-operator + +To build ceph-csi-operator locally run: + +```console +make +``` + +To build ceph-csi-operator in a container: + +```console +make docker-build +``` + +The built binary will be present under `bin/` directory. + +### Running ceph-csi-operator tests + +Once the changes to the sources compile, it is good practice to run the tests that validate the style and other basics of the source code. Execute the unit tests (in the `*_test.go` files) and check the formatting of YAML files, MarkDown documents and shell scripts: + +```console +make test +``` + +In addition to running tests locally, each Pull Request that is created will +trigger Continuous Integration tests. + +### Code contribution workflow + +ceph-csi-operator repository currently follows GitHub's +[Fork & Pull] () workflow +for code contributions. + +Please read the [coding guidelines](coding.md) document before submitting a PR. + +#### Certificate of Origin + +By contributing to this project you agree to the Developer Certificate of Origin (DCO). This document was created by the Linux Kernel community and is a simple statement that you, as a contributor, have the legal right to make the contribution. See the [DCO](DCO) file for details. + +Contributors sign-off that they adhere to these requirements by adding a Signed-off-by line to commit messages. For example: + +``` +This is my commit message + +More details on what this commit does + +Signed-off-by: Random J Developer +``` + +If you have already made a commit and forgot to include the sign-off, you can amend your last commit to add the sign-off with the following command, which can then be force pushed. + +```console +git commit --amend -s +``` + +We use a [DCO bot](https://github.com/apps/dco) to enforce the DCO on each pull request and branch commits. + +#### Commit Messages + +We follow a rough convention for commit messages that is designed to answer two questions: what changed and why? The subject line should feature the what and the body of the commit should describe the why. + +``` +fix bug in configmap + +fix clusterID bug in the configmap where the clusterID is +not set to the expected value. + +Signed-off-by: Random J Developer +``` + +The format can be described more formally as follows: + +``` + + + + + +``` + +The first line is the subject and should be no longer than 70 characters, the second line is always blank, and other lines should be wrapped at 80 characters. This allows the message to be easier to read on GitHub as well as in various git tools. + +Here is a short guide on how to work on a new patch. In this example, we will work on a patch called *hellopatch*: + +1. Make sure you Frok's main branch is up to date + +```console +git fetch upstream main:main +git checkout main +git push +``` + +2. Create a new branch for your patch: + +```console +git checkout -b hellopatch +``` + +Do your work here and commit. + +Run the test suite, which includes linting checks, static code check, and unit tests: + +```console +make test +``` + +Once you are ready to push, you will type the following: + +```console +git push hellopatch +``` + +**Creating A Pull Request:** +When you are satisfied with your changes, you will then need to go to your repo in GitHub.com and create a pull request for your branch. Automated tests will be run against the pull request. Your pull request will be reviewed and merged. + +If you are planning on making a large set of changes or a major architectural change it is often desirable to first build a consensus in an issue discussion and/or create an initial design doc PR. Once the design has been agreed upon one or more PRs implementing the plan can be made. + +A few labels interact with automation around the pull requests: + +* ready-to-merge: This PR is ready to be merged and it doesn't need second review +* do-not-merge: DO NOT MERGE (Mergify will not merge this PR) +* ok-to-test: PR is ready for e2e testing. + +**Review Process:** +Once your PR has been submitted for review the following criteria will need to be met before it will be merged: + +When the criteria are met, a project maintainer can merge your changes into the project's main branch. + +### Backport a Fix to a Release Branch + +The flow for getting a fix into a release branch is: + +1. Open a PR to merge the changes to main following the process outlined above. +2. Add the backport label to that PR such as `backport-to-release-vX.Y.Z` +3. After your PR is merged to main, the mergify bot will automatically open a PR with your commits backported to the release branch +4. If there are any conflicts you will need to resolve them by pulling the branch, resolving the conflicts and force push back the branch +5. After the CI is green, the bot will automatically merge the backport PR. diff --git a/docs/releases.md b/docs/releases.md new file mode 100644 index 00000000..eb06271a --- /dev/null +++ b/docs/releases.md @@ -0,0 +1,47 @@ +# Ceph CSI Operator Release Process + +- [Ceph CSI Operator Release Process](#ceph-csi-operator-release-process) + - [Introduction](#introduction) + - [Versioning](#versioning) + - [Tagging repositories](#tagging-repositories) + - [Release process \[TBD\]](#release-process-tbd) + +## Introduction + +This document provides details about Ceph CSI operator release process. + +## Versioning + +The ceph-csi-operator project uses [semantic versioning](http://semver.org/) for all releases. Semantic versions are comprised of three fields in the form: + +```MAJOR.MINOR.PATCH``` + +For examples: `1.0.0`, `1.0.0-rc.2`. + +Semantic versioning is used since the version number is able to convey clear information about how a new version relates to the previous version. For example, semantic versioning can also provide assurances to allow users to know when they must upgrade compared with when they might want to upgrade: + +- When `PATCH` increases, the new release contains important **security fixes**, general bug fixes and an upgrade is recommended. + +The patch field can contain extra details after the number. Dashes denote pre-release versions.`1.0.0-rc.2` in the example denotes the second release candidate for release `1.0.0`. + +- When `MINOR` increases, the new release adds **new features** and it must be backward compatible. + +- When `MAJOR` increases, the new release adds **new features, bug fixes, or both** and which *changes the behavior from the previous release* (maybe backward incompatible). + +## Tagging repositories + +The tag name must begin with "v" followed by the version number, conforming to the [versioning](#versioning) requirements (e.g. a tag of `v1.0.0-rc2` for version `1.0.0-rc2`). This tag format is used by the GitHub action infrastructure to properly upload and tag releases to Quay. + +## Release process [TBD] + +The Release Owner must follow the following process, which is designed to ensure clarity, quality, stability, and auditability of each release: + +- [Create a new milestone](https://github.com/ceph/ceph-csi-operator/milestones/new) to track the progress of the release. Set the scheduled date for the release, or update it later when a date is selected. + +- [Raise new issue in this repository](https://github.com/ceph/ceph-csi-operator/issues/new) to track the progress of the release with maximum visibility. Link the issue with the milestone for the release. + +- Paste the release checklist into the issue. + + This is useful for tracking so that the stage of the release is visible to all interested parties. This checklist could be a list of issues/PRs tracked for a release. The issues/PRs will be marked with the milestone for the release. For example, a milestone called `release-2.1.0` (for release version 2.1.0) can be linked to issues and PRs for better tracking release items. + +- Once all steps are complete, close the issue and the milestone.