From c7a537ba3a806b9ae65e67e4a0345be6d34992dc 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 | 102 +++++++++++++++++++++ docs/development-guide.md | 185 ++++++++++++++++++++++++++++++++++++++ docs/releases.md | 74 +++++++++++++++ 6 files changed, 581 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..ac4047bf --- /dev/null +++ b/docs/coding.md @@ -0,0 +1,102 @@ +# 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..e658b329 --- /dev/null +++ b/docs/development-guide.md @@ -0,0 +1,185 @@ +# 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: + +``` +subsystem: 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. + +``` +controller: 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*: + +```console +git fetch upstream main:main +git checkout main +git push +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 +* DNM: 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..0c4e643e --- /dev/null +++ b/docs/releases.md @@ -0,0 +1,74 @@ +# 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.