Changeset f4782c9 in rtems-docs

Dec 3, 2018, 5:33:31 AM (22 months ago)
Marçal Comajoan Cara <mcomajoancara@…>
5, am, master
Marçal Comajoan Cara <mcomajoancara@…> (12/03/18 05:33:31)
Joel Sherrill <joel@…> (12/18/18 00:45:49)

eng/vc-authors: Convert wiki page to Rest (GCI 2018)

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.

1 added
1 edited


  • eng/vc-authors.rst

    r32a4a0a rf4782c9  
    10 TBD - Convert
    11 TBD - and insert here.
     10.. COMMENT: TBD - Convert
     11.. COMMENT: TBD - and insert here.
     13.. COMMENT: TBD - Some guidelines for anyone who wishes to contribute to
     14.. COMMENT: TBD - rtems... Patches? Pull Requests?...
     16 The preferred workflow for making changes to RTEMS is to push patches to a
     17 committer's personal repository in public view and then merge changes from
     18 there. For working on enhancements or bug fixes committers are encouraged to
     19 push to branches on their personal repositories and to merge into the main
     20 RTEMS repository from their personal repository. Personal branches should
     21 not be pushed to the RTEMS repository.
     23SSH Access
     26Currently all committer's should have an ssh account on the main git server, If you have been granted commit access and do have an
     28account on one should be requested on the devel@
     29SSH access for git uses key logins instead of passwords. The key should be at
     30least 1024bits in length.
     32The public repositories can by cloned with
     34.. code-block:: shell
     36  git clone ssh://
     38Or replace `rtems.git` with another repo to clone another one.
     40Personal Repository
     42Personal repositories keep the clutter away from the master repository. A
     43user with a personal repository can make commits, create and delete branches,
     44plus more without interfering with the master repository. Commits to the
     45master repository generate email to the vc@
 list and development type commits
     46by a developer would only add noise and lessen the effectiveness of the commit
     49A committer should maintain a personal clone of the RTEMS repository through
     50which all changes merged into the RTEMS head are sent. The personal repository
     51is also a good place for committers to push branches that contain works in
     52progress. The following instructions show how to setup a personal repositor
     53that by default causes commits to go to your private local repository and
     54pushes to go to your publicly visible personal repository. The RTEMS head is
     55configured as a remote repository named 'upstream' to which you can push
     56changes that have been approved for merging into RTEMS.
     58Branches aren't automatically pushed until you tell git to do the initial push
     59after which the branch is pushed automatically. In order to keep code private
     60just put it on a branch in your local clone and do not push the branch.
     62Create a personal repository
     65Set up the server side repository. In the following substitute user with your
     68.. code-block:: shell
     70  # ssh
     71  [user@git ~]$ ln -s /data/git/user git
     72  [user@git ~]$ ls -l
     73  lrwxrwxrwx 1 user rtems 16 Feb  1 11:52 git -> /data/git/user
     74  [user@git ~]$ cd git
     75  [user@git git]$ git clone --mirror /data/git/rtems.git
     77Provide a description for the repository, for example "Clone of master
     80.. code-block:: shell
     82  [user@git git]$ echo "Clone of master repository." > rtems.git/description
     83  [user@git git]$ logout
     85Clone the repository on your local machine
     87.. code-block:: shell
     89  # git clone ssh://
     90  # cd rtems
     92Add the RTEMS repository as a remote repository and get the remote tags
     93and branches
     95.. code-block:: shell
     97  # git remote add upstream ssh://
     98  # git fetch upstream
     100After a little while you should be able to see your personal repo
     101at and you can create other
     102repositories in your git directory that will propagate
     103to if you need. For example, `joel`'s personal
     104repos appear at
     107.. figure:: ../images/eng/Git-personalrepo.png
     108  :width: 50%
     109  :align: center
     110  :alt: Git Personal Repositories
     112Check your setup
     115.. code-block:: shell
     117  git remote show origin
     119Should print something similar to
     121.. code-block:: shell
     123 * remote origin
     124   Fetch URL: ssh://
     125   Push  URL: ssh://
     126   HEAD branch: master
     127   Remote branches:
     128     4.10   tracked
     129     4.8    tracked
     130     4.9    tracked
     131     master tracked
     132   Local branch configured for 'git pull':
     133     master merges with remote master
     134   Local ref configured for 'git push':
     135     master pushes to master (up to date)
     137Push commits to personal repo master from local master
     140.. code-block:: shell
     142  # git push
     144Push a branch onto personal repo
     147.. code-block:: shell
     149  # git push origin branchname
     151Update from upstream master (RTEMS head)
     154 When you have committed changes on a branch that is private (hasn't been
     155 pushed to your personal repo) then you can use rebase to obtain a linear
     156 history and avoid merge commit messages.
     158.. code-block:: shell
     160  # git checkout new_features
     161  # git pull --rebase upstream master
     163If you cannot do a fast-forward merge then you could use the ``--no-commit``
     164flag to prevent merge from issuing an automatic merge commit message.
     166When you have committed changes on a branch that is public/shared with another
     167developer you should not rebase that branch.
     169GIT Push Configuration
     172People with write access to the main repository should make sure that they
     173push the right branch with the git push command. The above setup ensures
     174that git push will not touch the main repository, which is identified as
     175upstream, unless you specify the upstream (by ``git push upstream master``).
     177Lets suppose we have a test branch intended for integration into the master
     178branch of the main repository.
     180.. code-block:: shell
     182  # git branch
     183    master
     184   *  test
     186There are two options for pushing with the branch. First,
     188.. code-block:: shell
     190  # git push origin test
     192Will push the test branch to the personal repository. To delete the remote
     195.. code-block:: shell
     197  # git push origin :test
     199You'll still need to delete your local branch if you are done with it.
     201If you are going to work exclusively with one branch for a while, you might
     202want to configure git to automatically push that branch when you use git push.
     203By default git push will use the local master branch, but you can use the
     204`test` branch as the source of your changes:
     206.. code-block:: shell
     208  # git config remote.origin.push test:master
     210Now git push will merge into your master branch on your personal repository.
     211You can also setup a remote branch:
     213.. code-block:: shell
     215  # git config remote.origin.push test:test
     217You can see what branch is configured for pushing with
     219.. code-block:: shell
     221  # git remote show origin
     223And reset to the default
     225.. code-block:: shell
     227  # git config remote.origin.push master
     229Pull a Developer's Repo
     232The procedures for creating personal repositories ensure that every developer
     233can post branches that anyone else can review. To pull a developer's personal
     234repository into your local RTEMS git clone, just add a new remote repo:
     236.. code-block:: shell
     238  # git remote add devname git://
     239  # git fetch devname
     240  # git remote show devname
     241  # git branch -a
     243Replace devname with the developer's user name on git, which you can see by
     244accessing Now you can switch to the branches
     245for this developer.
     247Use a tracking branch if the developer's branch is changing:
     249.. code-block:: shell
     251  # git branch --track new_feature devname/new_feature
     256Ticket Updates
     259Our trac instance supports updating a related ticket with the commit message.
     261Any references to a ticket for example #1234 will insert the message into
     262he ticket as an 'update'. No command is required.
     264Closing a ticket can be done by prefixing the ticket number with any of the
     265following commands:
     267``close``, ``closed``, ``closes``, ``fix``, ``fixed``, or ``fixes``
     269For example:
     271``closes #1234``
     273``This is a random update it closes #1234 and updates #5678``
     278When merging someone's work, whether your own or otherwise, we have some
     279suggested procedures to follow.
     281* Never work in the master branch. Checkout a new branch and apply
     282  patches/commits to it.
     283* Before pushing upstream:
     284  - Update master by fetching from the server
     285  - Rebase the working branch against the updated master
     286  - Push the working branch to the server master
     288The basic workflow looks like
     290.. code-block:: shell
     292  # git checkout -b somebranch upstream/master
     293  # patch .. git add/rm/etc
     294  # git commit ...
     295  # git pull --rebase upstream master
     296  # git push upstream somebranch:master
     298If someone pushed since you updated the server rejects your push until you
     299are up to date.
     301For example a workflow where you will commit a series of patches from
     302``../patches/am/`` directory:
     304.. code-block:: shell
     306  # git checkout -b am
     307  # git am ../patches/am*
     308  # git pull --rebase upstream master
     309  # git push upstream am:master
     310  # git checkout master
     311  # git pull upstream master
     312  # git log
     313  # git branch -d am
     314  # git push
     316The git log stage will show your newly pushed patches if everything worked
     317properly, and you can delete the am branch created. The git push at the end
     318will push the changes up to your personal repository.
     320Another way to do this which pushes directly to the upstream is shown here
     321in an example which simply (and quickly) applies a patch to the branch:
     323.. code-block:: shell
     325  git checkout -b rtems4.10 --track remotes/upstream/4.10
     326  cat /tmp/sp.diff | patch
     327  vi sparc.t
     328  git add sparc.t
     329  git commit -m "sparc.t: Correct for V8/V9"
     330  git push upstream rtems4.10:4.10
     331  git checkout master
     332  git log
     333  git branch -d rtems4.10
     335Pushing Multiple Commits
     338A push with more than one commit results in Trac missing them. Please use the
     339following script to push a single commit at a time:
     341.. code-block:: shell
     343  #! /bin/sh
     344  commits=$(git log --format='%h' origin/master..HEAD | tail -r)
     345  for c in $commits
     346  do
     347    cmd=$(echo $c | sed 's%\(.*\)%git push origin \1:master%')
     348    echo $cmd
     349  $cmd
     350  done
     355So you pushed something upstream and broke the repository. First things first:
     356stop what you're doing and notify devel@... so that (1) you can get help and
     357(2) no one pulls from the broken repo. For an extended outage also notify
     358users@.... Now, breathe easy and let's figure out what happened. One thing
     359that might work is to just `undo the push
     360<>`_. To get an
     361idea of what you did, run ``git reflog``, which might be useful for getting
     362assistance in undoing whatever badness was done.
Note: See TracChangeset for help on using the changeset viewer.