Changeset f4782c9 in rtems-docs


Ignore:
Timestamp:
Dec 3, 2018, 5:33:31 AM (5 months ago)
Author:
Marçal Comajoan Cara <mcomajoancara@…>
Branches:
master
Children:
7e91a8f
Parents:
32a4a0a
git-author:
Marçal Comajoan Cara <mcomajoancara@…> (12/03/18 05:33:31)
git-committer:
Joel Sherrill <joel@…> (12/18/18 00:45:49)
Message:

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.

Files:
1 added
1 edited

Legend:

Unmodified
Added
Removed
  • eng/vc-authors.rst

    r32a4a0a rf4782c9  
    88**********************************
    99
    10 TBD - Convert https://devel.rtems.org/wiki/Developer/Git/Committers
    11 TBD - and insert here.
     10.. COMMENT: TBD - Convert https://devel.rtems.org/wiki/Developer/Git/Committers
     11.. COMMENT: TBD - and insert here.
     12
     13.. COMMENT: TBD - Some guidelines for anyone who wishes to contribute to
     14.. COMMENT: TBD - rtems... Patches? Pull Requests?...
     15
     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.
     22
     23SSH Access
     24----------
     25
     26Currently all committer's should have an ssh account on the main git server,
     27dispatch.rtems.org. If you have been granted commit access and do have an
     28account on dispatch.rtems.org one should be requested on the devel@
 list.
     29SSH access for git uses key logins instead of passwords. The key should be at
     30least 1024bits in length.
     31
     32The public repositories can by cloned with
     33
     34.. code-block:: shell
     35
     36  git clone ssh://user@dispatch.rtems.org/data/git/rtems.git
     37
     38Or replace `rtems.git` with another repo to clone another one.
     39
     40Personal Repository
     41-------------------
     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
     47list
     48
     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.
     57
     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.
     61
     62Create a personal repository
     63----------------------------
     64
     65Set up the server side repository. In the following substitute user with your
     66username.
     67
     68.. code-block:: shell
     69
     70  # ssh git.rtems.org
     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
     76
     77Provide a description for the repository, for example "Clone of master
     78repository."
     79
     80.. code-block:: shell
     81
     82  [user@git git]$ echo "Clone of master repository." > rtems.git/description
     83  [user@git git]$ logout
     84
     85Clone the repository on your local machine
     86
     87.. code-block:: shell
     88
     89  # git clone ssh://user@dispatch.rtems.org/home/user/git/rtems.git
     90  # cd rtems
     91
     92Add the RTEMS repository as a remote repository and get the remote tags
     93and branches
     94
     95.. code-block:: shell
     96
     97  # git remote add upstream ssh://user@dispatch.rtems.org/data/git/rtems.git
     98  # git fetch upstream
     99
     100After a little while you should be able to see your personal repo
     101at https://git.rtems.org/@USER@/rtems.git/ and you can create other
     102repositories in your git directory that will propagate
     103to https://git.rtems.org/@USER@/ if you need. For example, `joel`'s personal
     104repos appear at https://git.rtems.org/joel/.
     105
     106
     107.. figure:: ../images/eng/Git-personalrepo.png
     108  :width: 50%
     109  :align: center
     110  :alt: Git Personal Repositories
     111
     112Check your setup
     113~~~~~~~~~~~~~~~~
     114
     115.. code-block:: shell
     116
     117  git remote show origin
     118
     119Should print something similar to
     120
     121.. code-block:: shell
     122
     123 * remote origin
     124   Fetch URL: ssh://user@dispatch.rtems.org/home/user/git/rtems.git
     125   Push  URL: ssh://user@dispatch.rtems.org/home/user/git/rtems.git
     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)
     136
     137Push commits to personal repo master from local master
     138~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     139
     140.. code-block:: shell
     141
     142  # git push
     143
     144Push a branch onto personal repo
     145~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     146
     147.. code-block:: shell
     148
     149  # git push origin branchname
     150
     151Update from upstream master (RTEMS head)
     152~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     153
     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.
     157
     158.. code-block:: shell
     159
     160  # git checkout new_features
     161  # git pull --rebase upstream master
     162
     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.
     165
     166When you have committed changes on a branch that is public/shared with another
     167developer you should not rebase that branch.
     168
     169GIT Push Configuration
     170----------------------
     171
     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``).
     176
     177Lets suppose we have a test branch intended for integration into the master
     178branch of the main repository.
     179
     180.. code-block:: shell
     181
     182  # git branch
     183    master
     184   *  test
     185
     186There are two options for pushing with the branch. First,
     187
     188.. code-block:: shell
     189
     190  # git push origin test
     191
     192Will push the test branch to the personal repository. To delete the remote
     193branch
     194
     195.. code-block:: shell
     196
     197  # git push origin :test
     198
     199You'll still need to delete your local branch if you are done with it.
     200
     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:
     205
     206.. code-block:: shell
     207
     208  # git config remote.origin.push test:master
     209
     210Now git push will merge into your master branch on your personal repository.
     211You can also setup a remote branch:
     212
     213.. code-block:: shell
     214
     215  # git config remote.origin.push test:test
     216
     217You can see what branch is configured for pushing with
     218
     219.. code-block:: shell
     220
     221  # git remote show origin
     222
     223And reset to the default
     224
     225.. code-block:: shell
     226
     227  # git config remote.origin.push master
     228
     229Pull a Developer's Repo
     230-----------------------
     231
     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:
     235
     236.. code-block:: shell
     237
     238  # git remote add devname git://dispatch.rtems.org/devname/rtems.git
     239  # git fetch devname
     240  # git remote show devname
     241  # git branch -a
     242
     243Replace devname with the developer's user name on git, which you can see by
     244accessing https://git.rtems.org. Now you can switch to the branches
     245for this developer.
     246
     247Use a tracking branch if the developer's branch is changing:
     248
     249.. code-block:: shell
     250
     251  # git branch --track new_feature devname/new_feature
     252
     253Committing
     254----------
     255
     256Ticket Updates
     257~~~~~~~~~~~~~~
     258
     259Our trac instance supports updating a related ticket with the commit message.
     260
     261Any references to a ticket for example #1234 will insert the message into
     262he ticket as an 'update'. No command is required.
     263
     264Closing a ticket can be done by prefixing the ticket number with any of the
     265following commands:
     266
     267``close``, ``closed``, ``closes``, ``fix``, ``fixed``, or ``fixes``
     268
     269For example:
     270
     271``closes #1234``
     272
     273``This is a random update it closes #1234 and updates #5678``
     274
     275Commands
     276~~~~~~~~
     277
     278When merging someone's work, whether your own or otherwise, we have some
     279suggested procedures to follow.
     280
     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
     287
     288The basic workflow looks like
     289
     290.. code-block:: shell
     291
     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
     297
     298If someone pushed since you updated the server rejects your push until you
     299are up to date.
     300
     301For example a workflow where you will commit a series of patches from
     302``../patches/am/`` directory:
     303
     304.. code-block:: shell
     305
     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
     315
     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.
     319
     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:
     322
     323.. code-block:: shell
     324
     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
     334
     335Pushing Multiple Commits
     336------------------------
     337
     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:
     340
     341.. code-block:: shell
     342
     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
     351
     352Ooops!
     353------
     354
     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<https://stackoverflow.com/questions/1270514/undoing-a-git-push>`_. 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.