From 085910d3b9cfb28f13b8c8e2d5bec7f08d17292d Mon Sep 17 00:00:00 2001 From: Amar Tumballi Date: Wed, 12 Aug 2020 18:47:56 +0530 Subject: Migration: update the docs * Make CONTRIBUTING.md have complete workflow documented. * Change './rfc.sh' to reflect the new workflow Updates: #1000 Also Updates: gluster/project-infrastructure#62 Change-Id: I31becd7cdb35cb68048b662786c31694791d50fe Signed-off-by: Amar Tumballi --- .testignore | 2 +- CONTRIBUTING | 30 --------------- CONTRIBUTING.md | 113 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 3 +- rfc.sh | 68 ++++++++++++++++++++++------------ 5 files changed, 160 insertions(+), 56 deletions(-) delete mode 100644 CONTRIBUTING create mode 100644 CONTRIBUTING.md diff --git a/.testignore b/.testignore index 1784aff629a..fe8f838bf2b 100644 --- a/.testignore +++ b/.testignore @@ -8,7 +8,7 @@ rfc.sh submit-for-review.sh AUTHORS -CONTRIBUTING +CONTRIBUTING.md COPYING-GPLV2 COPYING-LGPLV3 ChangeLog diff --git a/CONTRIBUTING b/CONTRIBUTING deleted file mode 100644 index eb30d76d1b4..00000000000 --- a/CONTRIBUTING +++ /dev/null @@ -1,30 +0,0 @@ -# GlusterFS project Contribution guidelines - - -## By contributing to this project, the contributor would need to agree to below. - -### 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/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000000..4798f38ce6c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,113 @@ +# GlusterFS project Contribution guidelines + +## Development Workflow + +We follow most of the details as per the [document here](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests). If you are not aware of the github workflow, it is recommended to go through them before continuing here. + + +#### Get the Repository setup + +0. Fork Repository + - Fork [GlusterFS repository](https://github.com/gluster/glusterfs/fork). + +1. Clone Repository + - Clone the glusterfs repo freshly from github using below steps. + +``` + git clone git@github.com:${username}/glusterfs.git + cd glusterfs/ + git remote add upstream git@github.com:gluster/glusterfs.git +``` + +About two tasks are one time for the life time. You can continue to use the same repository for all the work in future. + +#### Development & Other flows + +0. Issue: + - Make sure there is an issue filed for the task you are working on. + - If it is not filed, open the issue with all the description. + - If it is a bug fix, add label "Type:Bug". + - If it is an RFC, provide all the documentation, and request for "DocApproved", and "SpecApproved" label. + +1. Code: + - Start coding + - Build and test locally + - Make sure clang-format is installed and is run on the patch. + +2. Keep up-to-date + - GlusterFS is a large project with many developers, so there would be one or the other patch everyday. + - It is critical for developer to be up-to-date with master repo to be Conflict-Free when PR is opened. + - Git provides many options to keep up-to-date, below is one of them +``` + git fetch upstream + git rebase upstream/master +``` + - It is recommended you keep pushing to your repo every day, so you don't loose any work. + - It can be done by `./rfc.sh` (or `git push origin HEAD:issueNNN`) + +2. Commit Message / PR description: + - The name of the branch on your personal fork can start with issueNNNN, followed by anything of your choice. + - PRs continue to have the title of format "component: \", like it is practiced now. + - When you open a PR, having a reference Issue for the commit is mandatory in GlusterFS. + - Commit message can have, either `Fixes: #NNNN` or `Updates: #NNNN` in a separate line in the commit message. + - Here, NNNN is the Issue ID in glusterfs repository. + - Each commit needs the author to have the "Signed-off-by: Name \" line. + - Can do this by `-s` option for `git commit`. + - If the PR is not ready for review, apply the label `work-in-progress`. + - Check the availability of "Draft PR" is present for you, if yes, use that instead. + +3. Tests: + - All the required smoke tests would be auto-triggered. + - Developers get a chance to retrigger the smoke tests using **"/recheck smoke"** as comment. + - The "regression" tests would be triggered by a comment **"/run regression"** from anyone in the [@gluster-all](https://github.com/orgs/gluster/teams/gluster-all) group. + +4. Review Process: + - `+2` : is equivalent to "Approve" from the people in the maintainer's group. + - `+1` : can be given by a maintainer/reviewer by explicitly stating that in the comment. + - `-1` : provide details on required changes and pick "Request Changes" while submitting your review. + - `-2` : done by adding the `DO-NOT-MERGE` label. + + - Any further discussions can happen as comments in the PR. + +5. Making changes: + - There are 2 approaches to submit changes done after addressing review comments. + - Commit changes as a new commit on top of the original commits in the branch, and push the changes to same branch (issueNNNN) + - Commit changes into the same commit with `--amend` option, and do a push to the same branch with `--force` option. + +6. Merging: + - GlusterFS project follows 'Squash and Merge' method + - This is mainly to preserve the historic Gerrit method of one patch in `git log` for one URL link. + - This also makes every merge a complete patch, which has passed all tests. + - The merging of the patch is expected to be done by the maintainers. + - It can be done when all the tests (smoke and regression) pass. + - When the PR has 'Approved' flag from corresponding maintainer. + - If you feel there is delay, feel free to add a comment, discuss the same in Slack channel, or send email. + +## By contributing to this project, the contributor would need to agree to below. + +### 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/README.md b/README.md index 92f829e431e..9d68e033782 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,7 @@ petabytes. It provides interfaces for object, block and file storage. ## Development - Contributions to gluster in the form of patches and new feature additions can - be made by following steps outlined at [Developers Guide](http://docs.gluster.org/en/latest/Developer-guide/Developers-Index/#contributing-to-the-gluster-community). + The development workflow is documented in [Contributors guide](CONTRIBUTING.md) ## Documentation The Gluster documentation can be found at [Gluster Docs](http://docs.gluster.org). diff --git a/rfc.sh b/rfc.sh index 8ab2f41b570..e7faec9ea0f 100755 --- a/rfc.sh +++ b/rfc.sh @@ -4,7 +4,29 @@ # i.e. where we are interested in the result of a command, # we have to run the command in an if-statement. -ORIGIN=${GLUSTER_ORIGIN:-origin} +UPSTREAM=${GLUSTER_UPSTREAM} +if [ "x$UPSTREAM" -eq "x" ]; then + for rmt in $(git remote); do + rmt_repo=$(git remote show $rmt -n | grep Fetch | awk '{ print $3 }'); + if [ $rmt_repo -eq "git@github:gluster/glusterfs" ]; then + UPSTREAM=$rmt + echo "Picked $rmt as upstream remote" + break + fi + done +fi + +USER_REPO=${GLUSTER_USER_REPO:-origin} +if [ "x${USER_REPO}" -eq "x${UPSTREAM}" ] ; then + echo "When you submit patches, it should get submitted to your fork, not to upstream directly" + echo "If you are not sure, check `for rmt in $(git remote); do git remote show $rmt -n; done`" + echo "And pick the correct remote you would like to push to and do `export GLUSTER_USER_REPO=$rmt`" + echo "" + echo "Exiting..." + exit 1 +fi + + while getopts "v" opt; do case $opt in @@ -18,7 +40,7 @@ done shift $((OPTIND-1)) -branch="master"; +branch="devel"; set_hooks_commit_msg() { @@ -50,21 +72,21 @@ is_num() backport_id_message() { echo "" - echo "This commit is to a non-master branch, and hence is treated as a backport." + echo "This commit is to a non-devel branch, and hence is treated as a backport." echo "" echo "For backports we would like to retain the same gerrit Change-Id across" echo "branches. On auto inspection it is found that a gerrit Change-Id is" - echo "missing, or the Change-Id is not found on your local master" + echo "missing, or the Change-Id is not found on your local devel branch" echo "" echo "This could mean a few things:" echo " 1. This is not a backport, hence choose Y on the prompt to proceed" - echo " 2. Your $ORIGIN master is not up to date, hence the script is unable" - echo " to find the corresponding Change-Id on master. Either choose N," + echo " 2. Your $USER_REPO/devel is not up to date, hence the script is unable" + echo " to find the corresponding Change-Id on devel. Either choose N," echo " 'git fetch', and try again, OR if you are sure you used the" echo " same Change-Id, choose Y at the prompt to proceed" echo " 3. You commented or removed the Change-Id in your commit message after" echo " cherry picking the commit. Choose N, fix the commit message to" - echo " use the same Change-Id as master (git commit --amend), resubmit" + echo " use the same Change-Id as 'devel' (git commit --amend), resubmit" echo "" } @@ -72,8 +94,8 @@ check_backport() { moveon='N' - # Backports are never made to master - if [ $branch = "master" ]; then + # Backports are never made to 'devel' + if [ $branch = "devel" ]; then return; fi @@ -86,22 +108,22 @@ check_backport() echo -n "Did not find a Change-Id for a possible backport. Continue (y/N): " read moveon else - # Search master for the same change ID (rebase_changes has run, so we + # Search 'devel' for the same change ID (rebase_changes has run, so we # should never not find a Change-Id) - mchangeid=$(git log $ORIGIN/master --format='%b' --grep="^Change-Id: ${changeid}" | grep ${changeid} | awk '{print $2}') + mchangeid=$(git log $UPSTREAM/devel --format='%b' --grep="^Change-Id: ${changeid}" | grep ${changeid} | awk '{print $2}') - # Check if we found the change ID on master, else throw a message to + # Check if we found the change ID on 'devel', else throw a message to # decide if we should continue. - # NOTE: If master was not rebased, we will not find the Change-ID and + # NOTE: If 'devel' was not rebased, we will not find the Change-ID and # could hit a false positive case here (or if someone checks out some - # other branch as master). + # other branch as 'devel'). if [ "${mchangeid}" = "${changeid}" ]; then moveon="Y" else backport_id_message; echo "Change-Id of commit: $changeid" - echo "Change-Id on master: $mchangeid" - echo -n "Did not find mentioned Change-Id on master for a possible backport. Continue (y/N): " + echo "Change-Id on devel: $mchangeid" + echo -n "Did not find mentioned Change-Id on 'devel' for a possible backport. Continue (y/N): " read moveon fi fi @@ -116,7 +138,7 @@ check_backport() rebase_changes() { - GIT_EDITOR=$0 git rebase -i $ORIGIN/$branch; + GIT_EDITOR=$0 git rebase -i $UPSTREAM/$branch; } @@ -212,7 +234,7 @@ EOF assert_diverge() { - git diff $ORIGIN/$branch..HEAD | grep -q .; + git diff $UPSTREAM/$branch..HEAD | grep -q .; } @@ -258,7 +280,7 @@ main() return; fi - git fetch $ORIGIN; + git fetch $UPSTREAM; rebase_changes; @@ -269,9 +291,9 @@ main() # see note above variable REFRE for regex elaboration reference=$(git log -n1 --format='%b' | grep -iow -E "${REFRE}" | awk -F '#' '{print $2}'); - # If this is a commit against master and does not have a github + # If this is a commit against 'devel' and does not have a github # issue reference. Warn the contributor that one of the 2 is required - if [ -z "${reference}" ] && [ $branch = "master" ]; then + if [ -z "${reference}" ] && [ $branch = "devel" ]; then warn_reference_missing; fi @@ -299,9 +321,9 @@ main() fi if [ -z "${reference}" ]; then - $drier git push $ORIGIN HEAD:refs/for/$branch/rfc; + $drier git push $USER_REPO HEAD:temp_${branch}/$(date +%Y-%m-%d_%s); else - $drier git push $ORIGIN HEAD:refs/for/$branch/ref-${reference}; + $drier git push $USER_REPO HEAD:issue${reference}_${branch}; fi } -- cgit