From f4782c99b8bb5e93f1d3d69b5dd639cc3441fabb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mar=C3=A7al=20Comajoan=20Cara?= Date: Mon, 3 Dec 2018 06:33:31 +0100 Subject: eng/vc-authors: Convert wiki page to Rest (GCI 2018) Converted https://devel.rtems.org/wiki/Developer/Git/Committers to Rest, and TBDs and wiki TODOs into comments. Also changed http links to https (the ones that are possible), corrected some typos, created a folder for eng images and added some formatting. This work was part of GCI 2018. --- eng/vc-authors.rst | 355 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 353 insertions(+), 2 deletions(-) (limited to 'eng') diff --git a/eng/vc-authors.rst b/eng/vc-authors.rst index 68f28e3..7e6e763 100644 --- a/eng/vc-authors.rst +++ b/eng/vc-authors.rst @@ -7,5 +7,356 @@ Software Development (Git Writers) ********************************** -TBD - Convert https://devel.rtems.org/wiki/Developer/Git/Committers -TBD - and insert here. +.. COMMENT: TBD - Convert https://devel.rtems.org/wiki/Developer/Git/Committers +.. COMMENT: TBD - and insert here. + +.. COMMENT: TBD - Some guidelines for anyone who wishes to contribute to +.. COMMENT: TBD - rtems... Patches? Pull Requests?... + + The preferred workflow for making changes to RTEMS is to push patches to a + committer's personal repository in public view and then merge changes from + there. For working on enhancements or bug fixes committers are encouraged to + push to branches on their personal repositories and to merge into the main + RTEMS repository from their personal repository. Personal branches should + not be pushed to the RTEMS repository. + +SSH Access +---------- + +Currently all committer's should have an ssh account on the main git server, +dispatch.rtems.org. If you have been granted commit access and do have an +account on dispatch.rtems.org one should be requested on the devel@… list. +SSH access for git uses key logins instead of passwords. The key should be at +least 1024bits in length. + +The public repositories can by cloned with + +.. code-block:: shell + + git clone ssh://user@dispatch.rtems.org/data/git/rtems.git + +Or replace `rtems.git` with another repo to clone another one. + +Personal Repository +------------------- +Personal repositories keep the clutter away from the master repository. A +user with a personal repository can make commits, create and delete branches, +plus more without interfering with the master repository. Commits to the +master repository generate email to the vc@… list and development type commits +by a developer would only add noise and lessen the effectiveness of the commit +list + +A committer should maintain a personal clone of the RTEMS repository through +which all changes merged into the RTEMS head are sent. The personal repository +is also a good place for committers to push branches that contain works in +progress. The following instructions show how to setup a personal repositor +that by default causes commits to go to your private local repository and +pushes to go to your publicly visible personal repository. The RTEMS head is +configured as a remote repository named 'upstream' to which you can push +changes that have been approved for merging into RTEMS. + +Branches aren't automatically pushed until you tell git to do the initial push +after which the branch is pushed automatically. In order to keep code private +just put it on a branch in your local clone and do not push the branch. + +Create a personal repository +---------------------------- + +Set up the server side repository. In the following substitute user with your +username. + +.. code-block:: shell + + # ssh git.rtems.org + [user@git ~]$ ln -s /data/git/user git + [user@git ~]$ ls -l + lrwxrwxrwx 1 user rtems 16 Feb 1 11:52 git -> /data/git/user + [user@git ~]$ cd git + [user@git git]$ git clone --mirror /data/git/rtems.git + +Provide a description for the repository, for example "Clone of master +repository." + +.. code-block:: shell + + [user@git git]$ echo "Clone of master repository." > rtems.git/description + [user@git git]$ logout + +Clone the repository on your local machine + +.. code-block:: shell + + # git clone ssh://user@dispatch.rtems.org/home/user/git/rtems.git + # cd rtems + +Add the RTEMS repository as a remote repository and get the remote tags +and branches + +.. code-block:: shell + + # git remote add upstream ssh://user@dispatch.rtems.org/data/git/rtems.git + # git fetch upstream + +After a little while you should be able to see your personal repo +at https://git.rtems.org/@USER@/rtems.git/ and you can create other +repositories in your git directory that will propagate +to https://git.rtems.org/@USER@/ if you need. For example, `joel`'s personal +repos appear at https://git.rtems.org/joel/. + + +.. figure:: ../images/eng/Git-personalrepo.png + :width: 50% + :align: center + :alt: Git Personal Repositories + +Check your setup +~~~~~~~~~~~~~~~~ + +.. code-block:: shell + + git remote show origin + +Should print something similar to + +.. code-block:: shell + + * remote origin + Fetch URL: ssh://user@dispatch.rtems.org/home/user/git/rtems.git + Push URL: ssh://user@dispatch.rtems.org/home/user/git/rtems.git + HEAD branch: master + Remote branches: + 4.10 tracked + 4.8 tracked + 4.9 tracked + master tracked + Local branch configured for 'git pull': + master merges with remote master + Local ref configured for 'git push': + master pushes to master (up to date) + +Push commits to personal repo master from local master +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: shell + + # git push + +Push a branch onto personal repo +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: shell + + # git push origin branchname + +Update from upstream master (RTEMS head) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + When you have committed changes on a branch that is private (hasn't been + pushed to your personal repo) then you can use rebase to obtain a linear + history and avoid merge commit messages. + +.. code-block:: shell + + # git checkout new_features + # git pull --rebase upstream master + +If you cannot do a fast-forward merge then you could use the ``--no-commit`` +flag to prevent merge from issuing an automatic merge commit message. + +When you have committed changes on a branch that is public/shared with another +developer you should not rebase that branch. + +GIT Push Configuration +---------------------- + +People with write access to the main repository should make sure that they +push the right branch with the git push command. The above setup ensures +that git push will not touch the main repository, which is identified as +upstream, unless you specify the upstream (by ``git push upstream master``). + +Lets suppose we have a test branch intended for integration into the master +branch of the main repository. + +.. code-block:: shell + + # git branch + master + * test + +There are two options for pushing with the branch. First, + +.. code-block:: shell + + # git push origin test + +Will push the test branch to the personal repository. To delete the remote +branch + +.. code-block:: shell + + # git push origin :test + +You'll still need to delete your local branch if you are done with it. + +If you are going to work exclusively with one branch for a while, you might +want to configure git to automatically push that branch when you use git push. +By default git push will use the local master branch, but you can use the +`test` branch as the source of your changes: + +.. code-block:: shell + + # git config remote.origin.push test:master + +Now git push will merge into your master branch on your personal repository. +You can also setup a remote branch: + +.. code-block:: shell + + # git config remote.origin.push test:test + +You can see what branch is configured for pushing with + +.. code-block:: shell + + # git remote show origin + +And reset to the default + +.. code-block:: shell + + # git config remote.origin.push master + +Pull a Developer's Repo +----------------------- + +The procedures for creating personal repositories ensure that every developer +can post branches that anyone else can review. To pull a developer's personal +repository into your local RTEMS git clone, just add a new remote repo: + +.. code-block:: shell + + # git remote add devname git://dispatch.rtems.org/devname/rtems.git + # git fetch devname + # git remote show devname + # git branch -a + +Replace devname with the developer's user name on git, which you can see by +accessing https://git.rtems.org. Now you can switch to the branches +for this developer. + +Use a tracking branch if the developer's branch is changing: + +.. code-block:: shell + + # git branch --track new_feature devname/new_feature + +Committing +---------- + +Ticket Updates +~~~~~~~~~~~~~~ + +Our trac instance supports updating a related ticket with the commit message. + +Any references to a ticket for example #1234 will insert the message into +he ticket as an 'update'. No command is required. + +Closing a ticket can be done by prefixing the ticket number with any of the +following commands: + +``close``, ``closed``, ``closes``, ``fix``, ``fixed``, or ``fixes`` + +For example: + +``closes #1234`` + +``This is a random update it closes #1234 and updates #5678`` + +Commands +~~~~~~~~ + +When merging someone's work, whether your own or otherwise, we have some +suggested procedures to follow. + +* Never work in the master branch. Checkout a new branch and apply + patches/commits to it. +* Before pushing upstream: + - Update master by fetching from the server + - Rebase the working branch against the updated master + - Push the working branch to the server master + +The basic workflow looks like + +.. code-block:: shell + + # git checkout -b somebranch upstream/master + # patch .. git add/rm/etc + # git commit ... + # git pull --rebase upstream master + # git push upstream somebranch:master + +If someone pushed since you updated the server rejects your push until you +are up to date. + +For example a workflow where you will commit a series of patches from +``../patches/am/`` directory: + +.. code-block:: shell + + # git checkout -b am + # git am ../patches/am* + # git pull --rebase upstream master + # git push upstream am:master + # git checkout master + # git pull upstream master + # git log + # git branch -d am + # git push + +The git log stage will show your newly pushed patches if everything worked +properly, and you can delete the am branch created. The git push at the end +will push the changes up to your personal repository. + +Another way to do this which pushes directly to the upstream is shown here +in an example which simply (and quickly) applies a patch to the branch: + +.. code-block:: shell + + git checkout -b rtems4.10 --track remotes/upstream/4.10 + cat /tmp/sp.diff | patch + vi sparc.t + git add sparc.t + git commit -m "sparc.t: Correct for V8/V9" + git push upstream rtems4.10:4.10 + git checkout master + git log + git branch -d rtems4.10 + +Pushing Multiple Commits +------------------------ + +A push with more than one commit results in Trac missing them. Please use the +following script to push a single commit at a time: + +.. code-block:: shell + + #! /bin/sh + commits=$(git log --format='%h' origin/master..HEAD | tail -r) + for c in $commits + do + cmd=$(echo $c | sed 's%\(.*\)%git push origin \1:master%') + echo $cmd + $cmd + done + +Ooops! +------ + +So you pushed something upstream and broke the repository. First things first: +stop what you're doing and notify devel@... so that (1) you can get help and +(2) no one pulls from the broken repo. For an extended outage also notify +users@.... Now, breathe easy and let's figure out what happened. One thing +that might work is to just `undo the push +`_. To get an +idea of what you did, run ``git reflog``, which might be useful for getting +assistance in undoing whatever badness was done. -- cgit v1.2.3