You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+16-1
Original file line number
Diff line number
Diff line change
@@ -32,13 +32,18 @@ Your assistance in improving documentation is highly valued, regardless of your
32
32
To claim an issue that you are interested in, kindly leave a comment on the issue and request the maintainers to assign it to you.
33
33
34
34
### Committing
35
-
We encourage all contributors to adopt [best practices in git commit management](https://hackmd.io/q22nrXjERBeIGb-fqwrUSg) to facilitate efficient reviews and retrospective analysis. Your git commits should provide ample context for reviewers and future codebase readers.
35
+
We encourage all contributors to adopt [best practices in git commit management](https://hackmd.io/q22nrXjERBeIGb-fqwrUSg) to facilitate efficient reviews and retrospective analysis. Note: that document was written for projects where some of the contributors are doing merges into the main branch, but in KubeStellar we have GitHub doing that for us. For the kubestellar repository, this is controlled by [Prow](https://docs.prow.k8s.io/); for the other repositories in the kubestellar organization we use the GitHub mechanisms directly.
36
+
37
+
Your git commits should provide ample context for reviewers and future codebase readers.
36
38
37
39
A recommended format for final commit messages is as follows:
38
40
39
41
```
40
42
{Short Title}: {Problem this commit is solving and any important contextual information} {issue number if applicable}
41
43
```
44
+
45
+
In conformance with CNCF expectations, we will only merge commits that indicate your agreement with the [Developer Certificate of Origin](#certificate-of-origin). The CNCF defines how to do this, and there are two cases: one for developers working for an organization that is a CNCF member, and one for contributors acting as individuals. For the latter, assent is indicated by doing a Git "sign-off" on the commit. See [Git Commit Signoff and Signing](docs/content/direct/pr-signoff.md) for more information on how to do that.
46
+
42
47
### Pull Requests
43
48
When submitting a pull request, clear communication is appreciated. This can be achieved by providing the following information:
44
49
@@ -49,6 +54,16 @@ When submitting a pull request, clear communication is appreciated. This can be
49
54
50
55
The pull request template has been designed to assist you in communicating this information effectively.
51
56
57
+
We require that the title of each pull request start with a special character that classifies the request into one of the following categories.
Smaller pull requests are typically easier to review and merge than larger ones. If your pull request is big, it is always recommended to collaborate with the maintainers to find the best way to divide it.
53
68
54
69
Approvers will review your PR within a business day. A PR requires both an /lgtm and then an /approve in order to get merged. You may /approve your own PR but you may not /lgtm it. Automation will add the PR it to the OpenShift PR merge queue. The OpenShift Tide bot will automatically merge your work when it is available.
In order to get your pull requests approved, you must first complete a
14
-
DCO sign-off. This process is defined by the CNCF, and there are two
13
+
In order to get a pull request approved, you must first complete a DCO
14
+
sign-off for each commit that the request is asking to add to the
15
+
repository. This process is defined by the CNCF, and there are two
15
16
cases: individual contributors and contributors that work for a
16
-
corporate CNCF member. Both mean consent with the terms stated in the
17
-
`DCO` file at the root of this Git repository.
18
-
19
-
In the case of an individual, DCO sign-off is done with a Git "signoff".
17
+
corporate CNCF member. Both mean consent with the terms stated in [the
18
+
`DCO` file at the root of this Git
19
+
repository](https://github.com/kubestellar/kubestellar/blob/main/DCO). In
20
+
the case of an individual, DCO sign-off is accomplished by doing a Git
21
+
"sign-off" on the commit.
20
22
21
23
We prefer that commits contributed to this repository be signed and
22
24
GitHub verified, but this is not strictly necessary or enforced.
23
25
24
26
## Commit Sign-off
25
27
26
-
Your submitted PR must pass the automated checks in order to be reviewed. One of these checks that each commit that you propose to contribute is signed-off. If you use the `git` shell command, this involves passing the `-s` flag on the command line. For other tools, consult their documentation.
28
+
Your submitted PR must pass the automated checks in order to be merged. One of these checks that each commit that you propose to contribute is signed-off. If you use the `git` shell command, this involves passing the `-s` flag on the command line. For example, the following command will create a signed-off commit but _not_ sign it.
27
29
28
-
### Repairing non-signed-off commits
30
+
```shell
31
+
git commit -s
32
+
```
29
33
30
-
If you have already created a PR that proposes to merge a branch that
31
-
adds commits that are not signed-off then you can repair this by
32
-
adding the signoff to each using `git commit -s --amend` on each of
33
-
them. Following is an outline of how to do it for a branch that adds
34
-
**exactly one** commit. If your branch adds more than one commit then
35
-
you can extrapolate using `git cherry-pick -s -S` to build up a
36
-
revised series of commits one-by-one.
34
+
Alternatively, the following command will create a commit that is both signed-off and signed.
37
35
38
-
The following instructions provide a basic walk-through if you have already created your own fork of the repository but yet not made a clone on your workstation. If you have set up your SSH and GPG keys and include `-S` on the `git commit` command line or have configured automatic signing then this will also get the commits signed.
36
+
```shell
37
+
git commit -s -S
38
+
```
39
39
40
-
1. Navigate to the **Code** page of the Kubestellar github.
41
-
42
-
2. Click the **Fork** dropdown in the top right corner of the page.
43
-
- Under "Existing Forks" click your fork (should look something like "your_username/kubestellar")
44
-
3. Once in your fork, click the **Code** dropdown.
45
-
- Under the "Local" tab at the top of the dropdown, select the SSH tab
46
-
- Copy the SSH repo URL to your clipboard
47
-
4. Open Git Bash (or your CLI of choice), create or change to a different directory if desired.
48
-
5. Clone the repository using `git clone` followed by pasting the URL you just copied.
49
-
6. Change your directory to the Kubestellar repo using `cd kubestellar`.
50
-
7.`git checkout` to the branch in your fork where the changes were committed.
51
-
- The branch name should be written at the top of your submitted PR page and looks something like "patch-*X*" (where "X" should be the number of PRs made on your fork to date)
52
-
8. Once in your branch, type `git commit -s --amend` to sign off your PR.
53
-
- You may replace `--amend` with a `-m` followed by a commit message if you desire; the `--amend` simply uses the same commit message as the one you wrote when initially submitting the PR
54
-
- If prompted with a sign-off page in your Git Bash (or alternative CLI), type `:wq!` to exit the prompt
55
-
9. Type `git push -f origin [branch_name]`, replacing `[branch_name]` with the actual name of your branch.
56
-
10. Navigate back to your PR github page.
57
-
- A green `dco-signoff: yes` label indicates that your PR is successfully signed
40
+
For other tools, consult their documentation.
58
41
59
42
## Signing Commits
60
43
61
-
To sign a commit, you must have a GPG and SSH key. Basic setup instructions can be found below (For more detailed instructions, refer to the Github [GPG](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key) and [SSH](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key) setup pages.)
44
+
Before signing any commits, you must have a GPG and SSH key. Basic setup instructions can be found below (For more detailed instructions, refer to the Github [GPG](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key) and [SSH](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key) setup pages.)
45
+
46
+
To sign a particular commit, you must either include `-S` on the `git commit` command line (see the command exhibited above for an example) or have configured automatic signing (see ["Everyone Must Sign" in the Git Book for a hint about that](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work#_everyone_must_sign)).
62
47
63
48
Before starting, make sure that your user email is verified on Github. To check for this:
64
49
@@ -71,7 +56,7 @@ Before starting, make sure that your user email is verified on Github. To check
71
56
72
57
<br />
73
58
74
-
**Git Bash** is also highly recommended.
59
+
For Windows users, **Git Bash** is also highly recommended.
75
60
76
61
<br />
77
62
@@ -161,11 +146,45 @@ Before starting, make sure that your user email is verified on Github. To check
161
146
162
147
## Creating Pull Requests Using the GitHub Website
163
148
149
+
This is not recommended for individual contributors, because the commits that it produces are not "signed-off" (as defined by Git) and thus do not carry assent to the DCO; for corporate contributors that is not an issue because that assent is indicated differently.
150
+
164
151
Whether it's editing files from Kubestellar.io or directly from the Kubestellar Github, there are a couple steps to follow that streamlines the workflow of your PR:
165
152
166
153
1. Changes made to any file are automatically committed to a new branch in your fork.
167
-
- When committing, make sure to specify the type of PR at the beginning of your commit message (i.e. :bug: if it addresses a bug-type issue)
168
-
- If the PR addresses a specific issue that has already been opened in the github, make sure to include the opened issue in**additional comments** (i.e. `fixes Issue #XXXX`)
169
-
170
-
2. Click **Propose Changes** after writing the commit message, review your changes, and then create the PR.
171
-
3. If your PR addresses an already opened issue on the github, make sure to close the issue once your PR is approved and closed.
154
+
- After clicking **Commit changes...**, write your commit message summary line and any extended desription that you want. Then click **Propose changes**, review your changes, and then create the PR.
155
+
- When making the PR, make sure to specify the type of PR at the beginning of the PR's title (i.e. :bug: if it addresses a bug-type issue)
156
+
157
+
1. If the PR addresses a specific issue that has already been opened in GitHub, make sure to include the open issue number in **Related Issue(s)** (i.e. `Fixes #NNNN`); this will cause GitHub to automatically close the Issue once the PR is merged. If you have finished addressing an open issue without getting it automatically closed then explicitly close the issue.
158
+
159
+
## Repairing commits
160
+
161
+
If you have already created a PR that proposes to merge a branch that
162
+
adds commits that are not signed-off then you can repair this (and
163
+
lack of signing, if you choose) by adding the signoff to each using
164
+
`git commit -s --amend` on each of them. If you also want those
165
+
commits signed then you would use `git commit -s -S --amend` or
166
+
configure automatic signing. Following is an outline of how to do it
167
+
for a branch that adds **exactly one** commit. If your branch adds
168
+
more than one commit then you can extrapolate using `git cherry-pick
169
+
-s -S` to build up a revised series of commits one-by-one.
170
+
171
+
The following instructions provide a basic walk-through if you have already created your own fork of the repository but yet not made a clone on your workstation.
172
+
173
+
1. Navigate to the **Code** page of the Kubestellar github.
174
+
175
+
2. Click the **Fork** dropdown in the top right corner of the page.
176
+
- Under "Existing Forks" click your fork (should look something like "your_username/kubestellar")
177
+
3. Once in your fork, click the **Code** dropdown.
178
+
- Under the "Local" tab at the top of the dropdown, select the SSH tab
179
+
- Copy the SSH repo URL to your clipboard
180
+
4. Open Git Bash (or your CLI of choice), create or change to a different directory if desired.
181
+
5. Clone the repository using `git clone` followed by pasting the URL you just copied.
182
+
6. Change your directory to the Kubestellar repo using `cd kubestellar`.
183
+
7. `git checkout` to the branch in your fork where the changes were committed.
184
+
- The branch name should be written at the top of your submitted PR page and looks something like "patch-*X*" (where "X" should be the number of PRs made on your fork to date)
185
+
8. Once in your branch, type `git commit -s --amend` to sign off your PR.
186
+
- The commit will also be signed if either you have set up automatic signing or both include the `-S` flag on that command and have set up your GPG key.
187
+
- You may extend that command with `-m` followed by a quoted commit message if you desire. Otherwise `git` will pop up an editor for you to use in making any desired adjustment to the commit message. After making any desired changes, save and exit the editor. FYI: in `vi` (which GitBash uses), when it is in Command mode (which is the normal mode, and contrasts with Insert mode) the keystrokes `:wq!` will attempt to save and then will exit no matter what.
188
+
9. Type `git push -f origin [branch_name]`, replacing `[branch_name]` with the actual name of your branch.
189
+
10. Navigate back to your PR github page.
190
+
- A green `dco-signoff: yes` label indicates that your PR is successfully signed
0 commit comments