From ef1664148ce77e8634cab6d9121ce5c108840799 Mon Sep 17 00:00:00 2001 From: John MacGregor Date: Mon, 27 Sep 2021 22:35:26 +0200 Subject: [PATCH 1/7] First draft of GitHub Contribution Workflow This addresses Issue #2 - Updated the nav bar structure - Added a link to the GitHub contribution document in the nav bar - Wrote an initial version of the contribution document Signed-off-by: John MacGregor --- docs/GitHubContributionWorkflow.md | 431 +++++++++++++++ docs/_includes/siteNav.html | 14 +- docs/assets/css/style.css | 4 +- .../graphics/GitHubContributionRepos.svg | 492 ++++++++++++++++++ 4 files changed, 937 insertions(+), 4 deletions(-) create mode 100644 docs/GitHubContributionWorkflow.md create mode 100644 docs/assets/graphics/GitHubContributionRepos.svg diff --git a/docs/GitHubContributionWorkflow.md b/docs/GitHubContributionWorkflow.md new file mode 100644 index 0000000..7472f48 --- /dev/null +++ b/docs/GitHubContributionWorkflow.md @@ -0,0 +1,431 @@ +--- +layout: default +title: GitHub Contribution Workflow +description: Workflow to create and modify content in an ELISA GitHub repo +--- +> This document defines the steps necessary to create new content +> and modify existing content in an ELISA GitHub repository, validate it, +> submit it for review and accompany it through the review process. + +> People working in ELISA may come from safety certification, RTOS-based embedded product development, +> open-source software development, Linux kernel development backgrounds or combinations thereof. +> Some have extensive experience developing with git, and specifically with GitHub, +> as well as collaborating with others in such a context (black belts). +> Others, on the other hand, having only passing or no experience (white belts). + +> This document aims to define the necessary steps for the black belts while giving additional information +> to aid understanding those steps for the white belts. + +# Preamble + +Contribution is possible from Linux-, Mac OS- and Windows-based computers +sometimes using the command line (CLI), custom tools, +integrated development environments (IDE)s +and partially with GitHub's web-based user interface (UI). +GitHub's documentation often focuses on that web-based UI. + +This document focuses on using the CLI, +as it is usually the most precise and least ambiguous way to describe an action. +Note, however, that tool-supported actions can be less complicated and therefore less error-prone. + +For the time being at least, identifying appropriate tools and IDE's for their platform +and mapping their operations to the git actions +is left as an exercise for the readers. + +**NOTE 1:** +You cannot contribute anonymously to ELISA project repositories. +All developers must therefore have a GitHub account before starting. + +**NOTE 2:** +You must sign the work that you commit. +By signing your work, you document that you are author of the work +and have accepted the license conditions documented in the root directory of **projectRepo**. + +**NOTE 3:** +You will be expected to keep your contribution in sync with the project repository until it has been accepted. + +# Terminology + +The diagramme below illustrates the repository topology underlying the terminology. + +![Contribution Repositories](assets/graphics/GitHubContributionRepos.svg){: .svgImg} + +## Roles + +Developer +: you + +Maintainer +: People with the right to accept new contributions in the form of pull requests (PR)s + +Reviewer +: Someone who either was appointed by the maintainer or has volunteered to review a PR + +## Repositories + +projectRepo +: the elisa-tech repository for the current activity, sometimes known as the "upstream repo" + +userRepo +: the developer's repository on GitHub, in this case a fork of projectRepo + +localRepo +: a clone of userRepo on the developer's computer. +This is where the development work occurs + +## Branches + +newFeature +: the branch on which developers work on the task at hand + +master +: the branch to containing the final versions of all contributions. +On old repositories, this branch is named "master". +On newer repositories, there is a tendency to name it "main". + +# Set up the development environment + +You would need write permission to push changes from your **localRepo** directly to the **projectRepo**, which is neither advisable not generally permitted. +Instead you should use the following procedure: + +## Create userRepo + +Create **userRepo** by **fork**ing the **projectRepo** to your GitHub site. +Refer to [About Forks - GitHub Docs](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-forks?algolia-query=fork). + +Note: If you activate the issue tracker in the options of **userRepo**, +developers who fork your fork (i.e. to collaborate on intermediate versions before submitting a (final) PR to the project) +will be able to create issues in **userRepo**. +Otherwise all issues created on your will be forwarded to the **projectRepo** repository instead. + +## Create and set up localRepo +If you haven't already done so, install git on your machine. +In corporate environments, the central IT department may have to install it for you. +Git is a standard package in many Linux distributions. Otherwise you can install git with the package manager. +Windows users can install [Git for Windows](https://gitforwindows.org/). + +Create a new directory for your development environment and **clone** **userRepo** to your machine, thus creating the **localRepo**. +Refer to the "GitHub.com" tab in +[Cloning a repository - GitHub Docs](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) +for a more detailed explanation. +As well as merely copying the code from **userRepo**, the clone operation also +effectively performs a `git init`{: language-shell .highlight} +([docu](https://git-scm.com/docs/git-init)): +* Creates .git directory in the root directory of **localRepo**: **localRepo/.git** +* Which contains, among other things a config file: **localRepo/.git/config** +* And sets a pointer to **userRepo** as the repository's remote origin repository. + Refer to + [About remote repositories - GitHub Docs](https://docs.github.com/en/get-started/getting-started-with-git/about-remote-repositories) + and + [Managing remote repositories - GitHub Docs](https://docs.github.com/en/get-started/getting-started-with-git/managing-remote-repositories) + for a more detailed explanation. + +Set your user name and e-mail in your cloned repository. +Refer to [Set up Git - GitHub Docs](https://help.github.com/en/github/getting-started-with-github/set-up-git) for directions. + +Optionally, set up a procedure to automatically sign commits. +The currently recommended way is to use a GPG key. +Refer to [Signing commits - GitHub Docs](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits?query=feature+branch). +The traditional method, which is also acceptable, is to sign with your name and e-mail, as set in the git configuration. +This means, however, that each commit must be called with the --signoff (or -s) argument. +git has no configuration parameter for automatic sign-off, but you can set an alias for your commit command. +Using your favourite text editor, you can add the following entry either in the .git/config in your home directory or at the root of **localRepo** +~~~~ conf + +[alias] + cs = commit --signoff + +~~~~ +and then substitute cs for the commit command, as in +~~~ bash + +$ git cs -a -m "commit message" + +~~~ + +Assuming you have used **localRepo/.git/config** for all your configuration, it should contain something like this: +~~~ + +[user] + name = Your Name + email = yourEmail@yourProvider.com +[alias] + cs = commit --signoff + +... + +[remote "origin"] + url = https://github.com/yourGitHubId/projectRepo.git + fetch = +refs/heads/*:refs/remotes/origin/* +[branch "main"] + remote = origin + merge = refs/heads/main + +~~~ + +# Workflow + +This section details the actions needed to create content and submit it to the project, +which may involve basic git operations. +For a summary of the necessary git commands, refer to +[Using git - GitHub Docs](https://docs.github.com/en/get-started/using-git). + +For another explanation of what is basically being said here, refer to +[GitHub flow - GitHub Docs](https://docs.github.com/en/get-started/quickstart/github-flow). + +## Create an issue + +You should indicate your intention to work on **projectRepo** to the project in **projectRepo**'s issue tracker. +This serves two purposes: +1. It notifies the project that work is being done on a particular topic area. + It therefore notifies others of potential conflicts with their work and allows + coordinated work in areas which may conflict. +2. It gives other participants an opportunity to comment on your work before it starts. + The issue tracker offers a forum to discuss potential problems or alternative solutions + before work has been invested. + +Either create an issue for new work or add an entry to an existing issue. + +The notification should contain: +* a description of the problem (maybe just the title) +* a description of the work +* your name and email +* your GitHub id, which, naturally, should be there already + +## Sync with projectRepo + +Should the local development environment already exist, +**userRepo** and **localRepo** should contain the latest changes from **projectRepo**. +Perform Steps 1 and 2 described in the +[Periodically sync with projectRepo](#periodically-sync-with-projectrepo){: target="_self"} section below. + +## Create a newFeature branch + +The **master** branches of **userRepo** and **localRepo** should not contain +changes from the current work. +Instead they should mirror **projectRepo** in order to update your repositories with the changes that +have occurred due to accepted pull requests since you originally created the **newFeature** branch.. +Refer to the next section for instructions on merging those changes +into **newFeature**. + +Creating a **newFeature** branch insulates your work from the rest of the project work. +Refer to +[About branches - GitHub](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches) +for a more detailed explanation. + +Although you can create a branch with the `git branch` command +([docu](https://git-scm.com/docs/git-branch)), +the `git checkout` command +([docu](https://git-scm.com/docs/git-checkout)) +can be used to switch to the new branch as well. +~~~ shell + +$ git checkout -b newFeature + +~~~ +The new branch should be placed on **userRepo** and the **localRepo** branch should track it. +~~~ shell + +$ git push -u origin newFeature + +~~~ + +## Create content + +There are any number of git operations that may be necessary during a normal write/test development cycle. +This section documents only those operations necessary to prepare the developed content for submission. +Refer to [Everyday git](https://git-scm.com/docs/giteveryday) for a short tutorial of useful commands. + +### Periodically commit + +Use `git status`{:.language-shell .highlight} ([docu](https://git-scm.com/docs/git-status)) to obtain lists of: +* files have changed, been marked to be committed and not been changed since (**staged**), +* files that have been marked to be committed (and are thus **tracked**) but have un-staged changes +* files in the repository that have not been marked to be committed (**untracked**) + +Use `git add `{:.language-shell .highlight} ([docu](https://git-scm.com/docs/git-add)) to track and stage files + +Use `git commit`{:.language-shell .highlight} ([docu](https://git-scm.com/docs/git-commit)) to bundle a set of changed files into an atomic change. +* The -a switch automatically "adds" all changed **tracked** files, otherwise only the changes that have already been "added" are committed. +* The -s (or --signoff) switch includes your identity information (minimally you name and email from the config file) in the commit message +* The -m (--message) switch allows a commit message to be supplied as a string. + Using this switch is not recommended as a generated commit includes the requisite information automatically. + When the switch is not supplied, a commit message is generated and placed in a text editor for modification. + Close the editor to finalise the message. + Generally, vim is used as the editor, which can be a problem for the uninitiated. + +Sign the commit ([docu](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work)). +Refer to the [Create and set up localRepo section](#create-and-set-up-localrepo){: target="_self"} for information +about how to automate signing off commit. + +Include a reference the relevant issue in the commit message. +Use the hashtag syntax +`#<<"issue number">>`{:.language-conf .highlight} +([docu](https://docs.github.com/en/github/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls#issues-and-pull-requests)) +This will link the commit to the issue and make it visible in the GitHub interface. + +Refer to [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) for good set of tips +for writing the commit message. + +### Back up your work on userRepo + +Use the `git push`{:.language-shell .highlight} command ([docu](https://git-scm.com/docs/git-push)) +to update your remote repository. + +John: Should this be git push origin newFeature +{: .comment} +~~~ shell + +$ git push origin + +~~~ + +### Periodically sync with projectRepo + +As necessary, import the changes from **projectRepo** that have been merged since the last fork. +These changes are located on the **master** branch. +This is a three step process as follows. + +#### 1) Update userRepo from projectRepo + +Your fork of **projectRepo** can be synchronised in the GitHub browser interface with just one click, +provided, of course, that **localRepo**'s **master** branch has no conflicts with **projectRepo**'s **master** branch. +Refer to +[Syncing a fork from the web UI - GitHub Docs](https://docs.github.com/en/github/collaborating-with-pull-requests/working-with-forks/syncing-a-fork#syncing-a-fork-from-the-web-ui). + +#### 2) Update localRepo from userRepo + +To bring the **master** branch updates into your local development environment, +you must first switch to the **master** branch and then bring in the changes from **userRepo**. +Use the `git checkout`[:.language-shell .highlight} ([docu](https://git-scm.com/docs/git-checkout)) +and `git pull` ([docu](https://git-scm.com/docs/git-pull)) +commands: +~~~ shell + +$ git checkout master +$ git pull origin + +~~~ + +The **master** branch in **localRepo** is now synchronised with the **master** branch in **projectRepo**, +but the changes must now be merged into the **newFeature** branch in **localRepo**. + +#### 3) Merge the changes in projectRepo into your local work + +Other than the content that you have changed, the content **newFeature** branch +is at the base state. +That is, the state it was in as the branch was created +or in the state from the last merge. +This merge updates the base state to the current state of **master** +(which would then be synchronised with **projectRepo**). + +Switch back to the **newFeature** branch and pull the changes over from +the **master** branch using the +`git rebase`{:.language-shell .highlight} command +([docu](https://git-scm.com/docs/git-rebase)) +~~~ shell + +$ git checkout newFeature +$ git rebase master + +~~~ + +In case of conflicts, rebase will interrupt the process and give you a chance to resolve the conflict. +After the conflict has been resolved, the merge process can resume. +Refer to the [rebase documentation](https://git-scm.com/docs/git-rebase) +for a detailed description of the process and necessary commands. + +Now the **newFeature** branch is based on the most recent **master** branch and +can be merged without back into the **master** branch without conflicts. +Note that pushing the **newFeature** branch to **userRepo** will now require +the -force switch since rebasing will change the commit history in **localRepo**. +Use +~~~ shell + +$ git push origin -force + +~~~ + + + +## Prepare for submission + +### Validate your work + +Initially, the validation procedure depends on the type of content being submitted. +Code must compile cleanly, pass unit tests and static analyses. +Textual submissions should be spell-checked. +The validation procedures should be specified by the ELISA working group responsible +for **projectRepo**. + +Check that your commits have all been signed off. +Use the `git log`{:.language-shell .highlight} +([docu](https://git-scm.com/docs/git-log)) +as follows: +~~~ shell + +$ git log --show-signature + +~~~ + +In any case, the DCO checking configured in GitHub will detect unsigned commits +when you create the PR. +Should it come that far, or if you find unsigned commits with +`git log`{:.language-shell .highlight}, +you must rebase back from the first missing commit. +If, for example, there are 10 commits between the unsigned commit +and the last commit (which is at the HEAD), +use the following command: +~~~ shell + +$ git rebase HEAD-10 --signoff + +~~~ + +Note that since this changes the history of **localRepo**, +pushing it to **userRepo** will overwrite the changelog and +thus require using the --force flag! + +### Sync with projectRepo + +The rest of the content of **newFeature** should be at the same state as the current version on **projectRepo**. + +This is explained in the [Periodically sync with projectRepo](#periodically-sync-with-projectrepo){: target="_self"} section above. + +### Push your work to userRepo + +This is explained in the [Back up your work on userRepo](#back-up-your-work-on-userrepo){: target="_self"} section above. + +## Submit a PR from userRepo + +Create a cross-fork PR from the **newFeature** branch on **userRepo** to the **master** branch on **projectRepo**. +* Sign the pull request. +* Include a link to (the) affected issue(s). + +This can be done from the GitHub web UI. +Refer to +[Creating a pull request from a fork - GitHub Docs](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork). + +GitHub will perform a DCO check and provide instructions about how to remedy failed checks. +It provides instructions about how to sign off afterwards. +It does not always get it right, though. + +**Important:** Do not continue to push revisions to **newFeature** on **localRepo** unless you want the changes +included in the PR. +The moment you push revisions to **localRepo**, the PR will be amended automatically. + +The maintainer will merge **newFeature** into **master** in **projectRepo** (and delete **newFeature** from **projectRepo**?). + +## Rebase userRepo, as necessary + +Should the maintainer accept other pull requests before yours is accepted, +your fork may need to be rebased in order to ensure +that it can be merged without conflicts. + +This is explained in the [Periodically sync with projectRepo](#periodically-sync-with-projectrepo){: target="_self"} section above. + +*[CLI]: Command Line Interface +*[DCO]: Developer Certification of Origin +*[IDE]: Integrated Development Environment +*[PR]: Pull Request +*[UI]: User Interface diff --git a/docs/_includes/siteNav.html b/docs/_includes/siteNav.html index 0c6fbd3..b6075e5 100644 --- a/docs/_includes/siteNav.html +++ b/docs/_includes/siteNav.html @@ -1,4 +1,14 @@
- > Home
- > Onboarding
+ > Home
+
+ Organisation:
+ > Onboarding
+
+ Strategy:
+ > TBD
+
+ Good Practices:
+ > GitHub Contribution Workflow
+ > GitHub Review Workflow
+
diff --git a/docs/assets/css/style.css b/docs/assets/css/style.css index 0b3e5f1..7046168 100644 --- a/docs/assets/css/style.css +++ b/docs/assets/css/style.css @@ -62,10 +62,10 @@ footer { margin-right: auto; width: 90%; } -.hrefLevel1 { +.navLevel1 { margin top: 10px; } -.hrefLevel2 { +.navLevel2 { margin top: 5px; margin-left: 10px; } diff --git a/docs/assets/graphics/GitHubContributionRepos.svg b/docs/assets/graphics/GitHubContributionRepos.svg new file mode 100644 index 0000000..53ee8cd --- /dev/null +++ b/docs/assets/graphics/GitHubContributionRepos.svg @@ -0,0 +1,492 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + Magnetic Disk (Database) + A magnetic disk. (ISO) + + + + + + + Magnetic Drum (Direct Access) + Magnetic drum. (ISO) + + + + + + + + + + + GitHub + Dev. Computer + Project + Developer + + + + + + + + + Project + + + + Master + + + + + + + + + + User + + + + Master + + + + + + + + + + Local + + + + Master + + + + + From 194c2b95e2700321ce4647d7fad175f67c778c94 Mon Sep 17 00:00:00 2001 From: John MacGregor Date: Wed, 29 Sep 2021 16:56:44 +0200 Subject: [PATCH 2/7] Small cleanup This work contributes to Issue #2 - After trying it in GitHub found out that the hashtag syntax works in GitHub, but the syntax used in the document was misleading - changed, hopefully improved - In the Update localRepo section, two code snippets weren't displayed properly Signed-off-by: John MacGregor --- docs/GitHubContributionWorkflow.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/GitHubContributionWorkflow.md b/docs/GitHubContributionWorkflow.md index 7472f48..8b44091 100644 --- a/docs/GitHubContributionWorkflow.md +++ b/docs/GitHubContributionWorkflow.md @@ -260,7 +260,7 @@ about how to automate signing off commit. Include a reference the relevant issue in the commit message. Use the hashtag syntax -`#<<"issue number">>`{:.language-conf .highlight} +`#`{:.language-conf .highlight} ([docu](https://docs.github.com/en/github/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls#issues-and-pull-requests)) This will link the commit to the issue and make it visible in the GitHub interface. @@ -297,8 +297,8 @@ Refer to To bring the **master** branch updates into your local development environment, you must first switch to the **master** branch and then bring in the changes from **userRepo**. -Use the `git checkout`[:.language-shell .highlight} ([docu](https://git-scm.com/docs/git-checkout)) -and `git pull` ([docu](https://git-scm.com/docs/git-pull)) +Use the `git checkout`{:.language-shell .highlight} ([docu](https://git-scm.com/docs/git-checkout)) and +`git pull`{:.language-shell .highlight} ([docu](https://git-scm.com/docs/git-pull)) commands: ~~~ shell From bd03dc491b88c89fae1ac4c16612bdbaa0be2c93 Mon Sep 17 00:00:00 2001 From: John MacGregor Date: Wed, 29 Sep 2021 17:22:08 +0200 Subject: [PATCH 3/7] Aded section for existing newFeature branch This work contributes to Issue #2 - above - also fixed missing code snippet highlighting in the Create a newFeature branch section Signed-off-by: John MacGregor --- docs/GitHubContributionWorkflow.md | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/docs/GitHubContributionWorkflow.md b/docs/GitHubContributionWorkflow.md index 8b44091..41297a7 100644 --- a/docs/GitHubContributionWorkflow.md +++ b/docs/GitHubContributionWorkflow.md @@ -189,6 +189,7 @@ Either create an issue for new work or add an entry to an existing issue. The notification should contain: * a description of the problem (maybe just the title) * a description of the work +* the name of the branch on which you will be working * your name and email * your GitHub id, which, naturally, should be there already @@ -199,7 +200,7 @@ Should the local development environment already exist, Perform Steps 1 and 2 described in the [Periodically sync with projectRepo](#periodically-sync-with-projectrepo){: target="_self"} section below. -## Create a newFeature branch +## Create a newFeature branch... The **master** branches of **userRepo** and **localRepo** should not contain changes from the current work. @@ -213,10 +214,11 @@ Refer to [About branches - GitHub](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches) for a more detailed explanation. -Although you can create a branch with the `git branch` command +Although you can create a branch with the +`git branch`{:.language-shell .highlight} command, ([docu](https://git-scm.com/docs/git-branch)), -the `git checkout` command -([docu](https://git-scm.com/docs/git-checkout)) +the `git checkout`{:.language-shell .highlight} +([docu](https://git-scm.com/docs/git-checkout)) command can be used to switch to the new branch as well. ~~~ shell @@ -230,6 +232,18 @@ $ git push -u origin newFeature ~~~ +## or switch to the newFeature branch + +Should the **newFeature** branch already exist, you need only switch to it using the +`git checkout`{:.language-shell .highlight} +([docu](https://git-scm.com/docs/git-checkout)) +command. +~~~ shell + +$ git checkout newFeature + +~~~ + ## Create content There are any number of git operations that may be necessary during a normal write/test development cycle. From 2a8b144edc05dfb1b2aea4575eb506ed33ef881c Mon Sep 17 00:00:00 2001 From: John MacGregor Date: Wed, 29 Sep 2021 19:55:57 +0200 Subject: [PATCH 4/7] Changed sync from pull/merge to fetch/rebase This work contributes to Issue #2 Simplified the workflow to sync the newFeature branch with the projectRepo/master from pulling to newFeature/master and then merging newFeature/master into newFeature to fetching userRepo and rebasing newFeature. Signed-off-by: John MacGregor --- docs/GitHubContributionWorkflow.md | 66 ++++++++++++++---------------- 1 file changed, 31 insertions(+), 35 deletions(-) diff --git a/docs/GitHubContributionWorkflow.md b/docs/GitHubContributionWorkflow.md index 41297a7..a173cd8 100644 --- a/docs/GitHubContributionWorkflow.md +++ b/docs/GitHubContributionWorkflow.md @@ -296,9 +296,9 @@ $ git push origin ### Periodically sync with projectRepo -As necessary, import the changes from **projectRepo** that have been merged since the last fork. +As necessary, import the changes from **projectRepo** that have been merged since the last fork sync. These changes are located on the **master** branch. -This is a three step process as follows. +This is a two step process as follows. #### 1) Update userRepo from projectRepo @@ -309,49 +309,45 @@ Refer to #### 2) Update localRepo from userRepo -To bring the **master** branch updates into your local development environment, -you must first switch to the **master** branch and then bring in the changes from **userRepo**. -Use the `git checkout`{:.language-shell .highlight} ([docu](https://git-scm.com/docs/git-checkout)) and -`git pull`{:.language-shell .highlight} ([docu](https://git-scm.com/docs/git-pull)) -commands: -~~~ shell - -$ git checkout master -$ git pull origin - -~~~ - -The **master** branch in **localRepo** is now synchronised with the **master** branch in **projectRepo**, -but the changes must now be merged into the **newFeature** branch in **localRepo**. - -#### 3) Merge the changes in projectRepo into your local work - -Other than the content that you have changed, the content **newFeature** branch -is at the base state. +Other than the content that you have changed, the content ot the **newFeature** branch +is at the **base** state. That is, the state it was in as the branch was created -or in the state from the last merge. -This merge updates the base state to the current state of **master** -(which would then be synchronised with **projectRepo**). +or in the state from the last merge from **userRepo/master**. -Switch back to the **newFeature** branch and pull the changes over from -the **master** branch using the -`git rebase`{:.language-shell .highlight} command +To bring updates of all branches in **userRepo** into your local development environment, +use the +`git fetch`{:.language-shell .highlight} +([docu](https://git-scm.com/docs/git-fetch)) +command. + +The fetched changes must still be explicitly merged into the **newFeature** branch, however. +Since **projectMaster** contains changes that are not contained in **newFeature**, +the merge will update the base state of the branch. +Use the +`git rebase`{:.language-shell .highlight} ([docu](https://git-scm.com/docs/git-rebase)) +command to merge. ~~~ shell -$ git checkout newFeature -$ git rebase master +git rebase origin/master ~~~ -In case of conflicts, rebase will interrupt the process and give you a chance to resolve the conflict. +Should conflicts occur, rebase will interrupt the process and give you a chance to resolve the conflict. After the conflict has been resolved, the merge process can resume. Refer to the [rebase documentation](https://git-scm.com/docs/git-rebase) for a detailed description of the process and necessary commands. Now the **newFeature** branch is based on the most recent **master** branch and -can be merged without back into the **master** branch without conflicts. -Note that pushing the **newFeature** branch to **userRepo** will now require +can be merged without back into the **master** branch (of **userRepo** and **projectRepo**) without conflicts. + +**Note 1** This workflow means that the local version of **master** in **localRepo** +is **not** updated, but it does have the benefit that the merge operation +does not involve checking out **master** to update it and then merging +**master** into to **newFeature**. +This lessens the danger of commiting **it** instead of **newFeature**. + +**Note 2** Pushing the **newFeature** branch to **userRepo** will now require the -force switch since rebasing will change the commit history in **localRepo**. Use ~~~ shell @@ -361,7 +357,6 @@ $ git push origin -force ~~~ - ## Prepare for submission ### Validate your work @@ -402,9 +397,10 @@ thus require using the --force flag! ### Sync with projectRepo -The rest of the content of **newFeature** should be at the same state as the current version on **projectRepo**. +The rest of the content of **newFeature** should brought up to the same state as the current version on **projectRepo**, +if it isn't already. -This is explained in the [Periodically sync with projectRepo](#periodically-sync-with-projectrepo){: target="_self"} section above. +How to do this is explained in the [Periodically sync with projectRepo](#periodically-sync-with-projectrepo){: target="_self"} section above. ### Push your work to userRepo From 5e2ce76ded8d683e36f5f4b9e4c08a4504e3eb4a Mon Sep 17 00:00:00 2001 From: John MacGregor Date: Wed, 29 Sep 2021 22:46:35 +0200 Subject: [PATCH 5/7] Added advice to use pull with the -ff-only option This work contributes to Issue #2 - to call it before creating a new branch - to make it a default switch in the git pull command Signed-off-by: John MacGregor --- docs/GitHubContributionWorkflow.md | 44 ++++++++++++++++++++++++++---- 1 file changed, 39 insertions(+), 5 deletions(-) diff --git a/docs/GitHubContributionWorkflow.md b/docs/GitHubContributionWorkflow.md index a173cd8..7442de1 100644 --- a/docs/GitHubContributionWorkflow.md +++ b/docs/GitHubContributionWorkflow.md @@ -123,17 +123,40 @@ effectively performs a `git init`{: language-shell .highlight} Set your user name and e-mail in your cloned repository. Refer to [Set up Git - GitHub Docs](https://help.github.com/en/github/getting-started-with-github/set-up-git) for directions. +We recommend that you set the `git pull`{:.language-shell .highlight} command to default to `--ff-only`{:.language-shell .highlight} +as pull's default behoviour is to merge from the remote repository's master branch into the current branch. +Refer to [Why you should use git pull -ff-only](https://blog.sffc.xyz/post/185195398930/why-you-should-use-git-pull-ff-only-git-is-a) +for a detailed explanation of why this behaviour is not desirable. +Use the `git config`{:.language-shell .highlight} +([docu](https://git-scm.com/docs/git-config)) +command to set the default. +As described in +[Set up Git - GitHub Docs](https://help.github.com/en/github/getting-started-with-github/set-up-git), +this command can set values either for the current repository (default, or with the `--local`{:.language-shell .highlight} option) +or for all repositories (with the `--global`{:.language-shell .highlight} option. +The values are stored in a **.git/config** file either at the root of **localRepo**, as mentioned above, +or in your home directory, respectively. +The appropriate command to set the default for all repositories would therefore be: +~~~ shell + +$ git config --global pull.ff only + +~~~ + +Instead of using the `git config`{:.language-shell .highlight} command, you can use your favourite text editor +to enter the corresponding entries directly. +Refer to the example conf file contents below for all recommended configuration values. + Optionally, set up a procedure to automatically sign commits. The currently recommended way is to use a GPG key. Refer to [Signing commits - GitHub Docs](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits?query=feature+branch). The traditional method, which is also acceptable, is to sign with your name and e-mail, as set in the git configuration. This means, however, that each commit must be called with the --signoff (or -s) argument. git has no configuration parameter for automatic sign-off, but you can set an alias for your commit command. -Using your favourite text editor, you can add the following entry either in the .git/config in your home directory or at the root of **localRepo** +Again, use the `git config`{:.language-shell .highlight}: ~~~~ conf -[alias] - cs = commit --signoff +$ git config --global alias.cs commit --signoff ~~~~ and then substitute cs for the commit command, as in @@ -160,6 +183,8 @@ Assuming you have used **localRepo/.git/config** for all your configuration, it [branch "main"] remote = origin merge = refs/heads/main +[pull] + ff = only ~~~ @@ -200,7 +225,7 @@ Should the local development environment already exist, Perform Steps 1 and 2 described in the [Periodically sync with projectRepo](#periodically-sync-with-projectrepo){: target="_self"} section below. -## Create a newFeature branch... +## Either create a newFeature branch... The **master** branches of **userRepo** and **localRepo** should not contain changes from the current work. @@ -209,6 +234,15 @@ have occurred due to accepted pull requests since you originally created the **n Refer to the next section for instructions on merging those changes into **newFeature**. +First, ensure that the **master** branch is kept up to date. +You should pull it from **userRepo** using the --ff-only option ([docu](https://git-scm.com/docs/git-pull)). +~~~ shell + +$ git checkout mastter +$ git pull origin master --ff-only + +~~~ + Creating a **newFeature** branch insulates your work from the rest of the project work. Refer to [About branches - GitHub](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches) @@ -232,7 +266,7 @@ $ git push -u origin newFeature ~~~ -## or switch to the newFeature branch +## ...or switch to the newFeature branch Should the **newFeature** branch already exist, you need only switch to it using the `git checkout`{:.language-shell .highlight} From 0c19a56088c5729e245d30eaacc2a10faaca7111 Mon Sep 17 00:00:00 2001 From: John MacGregor Date: Tue, 19 Oct 2021 20:19:42 +0200 Subject: [PATCH 6/7] Incorporated Review Comments This work contributes to Issue #2 Fixed various issues identfied by - Paul Albertella on the 30th of September 2021 - Jochen Kall on the 30th of September 2021 Signed-off-by: John MacGregor --- docs/GitHubContributionWorkflow.md | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/docs/GitHubContributionWorkflow.md b/docs/GitHubContributionWorkflow.md index 7442de1..418177d 100644 --- a/docs/GitHubContributionWorkflow.md +++ b/docs/GitHubContributionWorkflow.md @@ -46,7 +46,7 @@ You will be expected to keep your contribution in sync with the project reposito # Terminology -The diagramme below illustrates the repository topology underlying the terminology. +The diagram below illustrates the repository topology underlying the terminology. ![Contribution Repositories](assets/graphics/GitHubContributionRepos.svg){: .svgImg} @@ -96,7 +96,7 @@ Refer to [About Forks - GitHub Docs](https://help.github.com/en/github/collabora Note: If you activate the issue tracker in the options of **userRepo**, developers who fork your fork (i.e. to collaborate on intermediate versions before submitting a (final) PR to the project) will be able to create issues in **userRepo**. -Otherwise all issues created on your will be forwarded to the **projectRepo** repository instead. +Otherwise all issues created on **userRepo** will be forwarded to the **projectRepo** repository instead. ## Create and set up localRepo If you haven't already done so, install git on your machine. @@ -149,7 +149,7 @@ Refer to the example conf file contents below for all recommended configuration Optionally, set up a procedure to automatically sign commits. The currently recommended way is to use a GPG key. -Refer to [Signing commits - GitHub Docs](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits?query=feature+branch). +Refer to [Signing commits - GitHub Docs](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits). The traditional method, which is also acceptable, is to sign with your name and e-mail, as set in the git configuration. This means, however, that each commit must be called with the --signoff (or -s) argument. git has no configuration parameter for automatic sign-off, but you can set an alias for your commit command. @@ -320,14 +320,16 @@ for writing the commit message. Use the `git push`{:.language-shell .highlight} command ([docu](https://git-scm.com/docs/git-push)) to update your remote repository. -John: Should this be git push origin newFeature -{: .comment} ~~~ shell $ git push origin ~~~ +You can also configure **newFeature** to be the default to be pushed to by using: +* `git push -u origin newFeature`{:.language-shell .highlight} when you first push it, or +* `git branch --set-upstream newFeature origin/newFeature`{:.language-shell .highlight} if you forget + ### Periodically sync with projectRepo As necessary, import the changes from **projectRepo** that have been merged since the last fork sync. @@ -353,6 +355,11 @@ use the `git fetch`{:.language-shell .highlight} ([docu](https://git-scm.com/docs/git-fetch)) command. +~~~ shell + +$ git fetch origin + +~~~ The fetched changes must still be explicitly merged into the **newFeature** branch, however. Since **projectMaster** contains changes that are not contained in **newFeature**, @@ -373,12 +380,12 @@ Refer to the [rebase documentation](https://git-scm.com/docs/git-rebase) for a detailed description of the process and necessary commands. Now the **newFeature** branch is based on the most recent **master** branch and -can be merged without back into the **master** branch (of **userRepo** and **projectRepo**) without conflicts. +can be merged back into the **master** branch (of **userRepo** and **projectRepo**) without conflicts. **Note 1** This workflow means that the local version of **master** in **localRepo** is **not** updated, but it does have the benefit that the merge operation does not involve checking out **master** to update it and then merging -**master** into to **newFeature**. +**master** into **newFeature**. This lessens the danger of commiting **it** instead of **newFeature**. **Note 2** Pushing the **newFeature** branch to **userRepo** will now require @@ -421,13 +428,13 @@ and the last commit (which is at the HEAD), use the following command: ~~~ shell -$ git rebase HEAD-10 --signoff +$ git rebase HEAD~10 --signoff ~~~ Note that since this changes the history of **localRepo**, pushing it to **userRepo** will overwrite the changelog and -thus require using the --force flag! +thus requires using the --force flag! ### Sync with projectRepo From a78eca1d4f07ff9e665da035b405a000a4350aa3 Mon Sep 17 00:00:00 2001 From: John MacGregor Date: Tue, 19 Oct 2021 20:56:02 +0200 Subject: [PATCH 7/7] Cosmetic impprovements, additional links This work contributes to Issue #2 - typo mastter - Added a link to a general explanation of the fork/clone/pull request model in GitHub docs. - Consistently put the link to the documentation directly behind a command reference - Added a link to an explanation of the DCO Signed-off-by: John MacGregor --- docs/GitHubContributionWorkflow.md | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/docs/GitHubContributionWorkflow.md b/docs/GitHubContributionWorkflow.md index 418177d..45467d2 100644 --- a/docs/GitHubContributionWorkflow.md +++ b/docs/GitHubContributionWorkflow.md @@ -40,6 +40,8 @@ All developers must therefore have a GitHub account before starting. You must sign the work that you commit. By signing your work, you document that you are author of the work and have accepted the license conditions documented in the root directory of **projectRepo**. +[ Developer Certficate of Origin - elinux.org](https://elinux.org/Developer_Certificate_Of_Origin) +provides a more detailed explanation. **NOTE 3:** You will be expected to keep your contribution in sync with the project repository until it has been accepted. @@ -86,7 +88,9 @@ On newer repositories, there is a tendency to name it "main". # Set up the development environment You would need write permission to push changes from your **localRepo** directly to the **projectRepo**, which is neither advisable not generally permitted. -Instead you should use the following procedure: +GitHub has devised another approach (refer to +[About collaborative development models - GitHub Docs](https://docs.github.com/en/github/collaborating-with-pull-requests/getting-started/about-collaborative-development-models). +You should therefore use the following procedure: ## Create userRepo @@ -123,7 +127,10 @@ effectively performs a `git init`{: language-shell .highlight} Set your user name and e-mail in your cloned repository. Refer to [Set up Git - GitHub Docs](https://help.github.com/en/github/getting-started-with-github/set-up-git) for directions. -We recommend that you set the `git pull`{:.language-shell .highlight} command to default to `--ff-only`{:.language-shell .highlight} +We recommend that you set the +`git pull`{:.language-shell .highlight} +[docu](https://git-scm.com/docs/git-pull) +command to default to `--ff-only`{:.language-shell .highlight} as pull's default behoviour is to merge from the remote repository's master branch into the current branch. Refer to [Why you should use git pull -ff-only](https://blog.sffc.xyz/post/185195398930/why-you-should-use-git-pull-ff-only-git-is-a) for a detailed explanation of why this behaviour is not desirable. @@ -153,7 +160,7 @@ Refer to [Signing commits - GitHub Docs](https://docs.github.com/en/authenticati The traditional method, which is also acceptable, is to sign with your name and e-mail, as set in the git configuration. This means, however, that each commit must be called with the --signoff (or -s) argument. git has no configuration parameter for automatic sign-off, but you can set an alias for your commit command. -Again, use the `git config`{:.language-shell .highlight}: +Again, use the `git config`{:.language-shell .highlight} command: ~~~~ conf $ git config --global alias.cs commit --signoff @@ -238,7 +245,7 @@ First, ensure that the **master** branch is kept up to date. You should pull it from **userRepo** using the --ff-only option ([docu](https://git-scm.com/docs/git-pull)). ~~~ shell -$ git checkout mastter +$ git checkout master $ git pull origin master --ff-only ~~~ @@ -249,8 +256,8 @@ Refer to for a more detailed explanation. Although you can create a branch with the -`git branch`{:.language-shell .highlight} command, -([docu](https://git-scm.com/docs/git-branch)), +`git branch`{:.language-shell .highlight} +([docu](https://git-scm.com/docs/git-branch)) command, the `git checkout`{:.language-shell .highlight} ([docu](https://git-scm.com/docs/git-checkout)) command can be used to switch to the new branch as well. @@ -317,7 +324,7 @@ for writing the commit message. ### Back up your work on userRepo -Use the `git push`{:.language-shell .highlight} command ([docu](https://git-scm.com/docs/git-push)) +Use the `git push`{:.language-shell .highlight} ([docu](https://git-scm.com/docs/git-push)) command to update your remote repository. ~~~ shell