Changes between Version 30 and Version 31 of SourceCodeGit


Ignore:
Timestamp:
05/11/13 22:19:27 (5 years ago)
Author:
Bluefin Tuna
Comment:

Made clearer, added Git handling information, updated obviously out-of-date text regarding tags and branches (stemming from subversion times, I reckon), and brought in-line regarding to what I am currently seeing in the Git repository (tag names, branch names, server release names were all updated by these instructions were not). The text under "server releases" seems nonsensensical, anyone who can check it??

Legend:

Unmodified
Added
Removed
Modified
  • SourceCodeGit

    v30 v31  
    55== Browsing source code on the web ==
    66
    7 You can browse the boinc code via [/browser a web-based interface]
    8 ([http://boinc.berkeley.edu/git alternative]).
     7You can browse the BOINC code using [/browser a web-based interface] ([http://boinc.berkeley.edu/git alternative]).
    98This is useful for getting individual files, or seeing the revision history.
    109
    11 == Getting a copy of the BOINC source ==
    12 
    13 The BOINC source code is stored in a [http://www.git-scm.com Git] repository.
    14 To get the source code on Unix:
    15 {{{
    16 git clone git://boinc.berkeley.edu/boinc-v2.git boinc
    17 or
    18 git clone http://boinc.berkeley.edu/git/boinc-v2.git boinc
    19 }}}
    20 
    21 This will give you a copy that you can modify locally,
    22 but not push changes to the BOINC repository.
    23 For write access, see below.
    24 
    25 On Windows, you'll need a Git client such as !TortoiseGit (see below).
    26 Right-click on the parent directory, select 'Git Clone...',
    27 and fill in the dialog with one of the above URLs. Don't forget
    28 to remove both 'git clone' and 'boinc' from the commands above.
    29 
    30 == Branches ==
    31 
    32 Various versions of the code are available at any given point:
    33 
    34 === Development ===
    35 
    36 The '''master''' branch contains the latest source code for all components of BOINC.
    37 It is always under development, and has not necessarily been thoroughly tested.
    38 
    39 To checkout the '''master''' branch:
    40 {{{
    41 git checkout master
    42 }}}
    43 
    44 === Client releases ===
    45 
    46 The client software (client and manager) is maintained as follows:
    47 
    48  * The code for each release is 'tagged'.
    49   For example, the code for version 6.3.14 is tagged with '''client_release_6_3_14'''.
    50  * A 'branch' is created for each released minor version.
    51   For example, the branch '''client_release_6_2''' is the code for the latest release of version 6.2.
    52 
    53 To checkout the '''client_release_6_12''' branch:
    54 {{{
    55 git checkout client_release_6_12
    56 }}}
    57 
    58 === Server releases ===
    59 
    60 For all software other than the client (i.e., server, web, and API)
    61 a "stable" version is kept in a branch, '''server_stable'''.
    62 Don't use the server software in a client tag or branch; it probably isn't stable.
    63 
    64 Notes:
    65  * There is no formal testing process for server software.
    66    Every so often, when no bugs have been reported recently,
    67    we merge the '''master''' branch into '''server_stable'''.
    68  * Because of limited resources, bug fixes to server software are normally
    69    NOT back-ported from '''master''' to '''server_stable'''.
    70 
    71 For these reasons: '''the master branch is typically a better choice
    72 than server_stable for server software'''.
    73 
    74 
    7510== Installing Git ==
    7611
    77 To access the BOINC Git repository you'll need Git client software:
    78 
    79  * On Windows, get a Git client like Git for Windows (console)] and !TortoiseGit (GUI) (see this [SourceCodeGit/Windows guide for Windows]).
    80   * Recommended free GUI: [http://www.sourcetreeapp.com SourceTree (includes an embedded git)],
    81  * On Linux, Git is usually provided by all modern distributions.
     12The BOINC source is stored in a [http://www.git-scm.com Git] repository. To access the BOINC Git repository you'll need the Git client software:
     13
     14 * On Windows, get a Git client like 'Git for Windows' (console) and !TortoiseGit (GUI) (see this [SourceCodeGit/Windows guide for Windows]).
     15 * On Linux, Git is usually provided by your distribution.
    8216   If not, check your package manager and look for "git" or "git-core"
    8317 * On Mac OS X, use [http://www.macports.org MacPorts]
    8418   (to keep git up to date, recommended) or a manual
    8519   [http://code.google.com/p/git-osx-installer installation package].
    86   * Recommended free GUIs: [http://www.sourcetreeapp.com SourceTree (includes an embedded git)],
     20 * Recommended free GUIs: [http://www.sourcetreeapp.com SourceTree (includes an embedded git)],
    8721   [http://www.syntevo.com/smartgit/ SmartGit (free for non-commercial use)],
    8822   [http://gitx.laullon.com GitX] ([https://github.com/laullon/gitx latest])
    8923
    90 To get a copy of the BOINC source code you don't need to understand Git -
    91 just follow the directions above.
    92 However, if you intend to modify BOINC or to look at branches,
    93 you'll need to know something about Git.
     24To get a copy of the BOINC source code you don't need to fully understand Git, just skim the instructions below. However, if you intend to modify BOINC or to look at branches, you'll need to know at least the basics.
     25
    9426Recommended reading/watching:
    9527
     
    9830 * [http://git-scm.com/doc All the rest]: Cheat sheets, tutorials and more videos
    9931
    100 
    101 == Write access to the main repository ==
     32== Getting a copy of the BOINC source ==
     33
     34To clone the BOINC Git repository into a local directory called (for example) 'boinc_repo', run:
     35
     36{{{
     37git clone git://boinc.berkeley.edu/boinc-v2.git boinc_repo
     38}}}
     39or
     40{{{
     41git clone http://boinc.berkeley.edu/git/boinc-v2.git boinc_repo
     42}}}
     43
     44This will give you a full copy that you can modify and compile locally, but you will not be able to push changes to the BOINC repository. For write access, see further below.
     45
     46If you change to the newly created directory 'boinc_repo', you will see a local copy of the BOINC source code tree.
     47These are the files corresponding to the 'remote master branch', the bleeding edge of development.
     48Running `git status` will show that this is actually true:
     49
     50{{{
     51$ cd boinc_repo
     52$ git status
     53# On branch master
     54nothing to commit, working directory clean
     55}}}
     56
     57You can replace the files on your 'master branch' by files from older branches or older tags using the appropriate git command - without
     58needing to contact the Git repository server again. This is called 'checking out'. The information to make your local copy of the Git repository a fully navigable development history is tucked away under the '.git' subdirectory.
     59
     60On Windows, you'll need a Git client such as !TortoiseGit (see below).
     61Right-click on the parent directory, select 'Git Clone...', and fill in the dialog with one of the above URLs. Don't forget to remove both 'git clone' and 'boinc' from the commands above.
     62
     63== Tags & Branches ==
     64
     65Various versions of the source code are available in the remote repository (and now, in your local copy of it):
     66
     67   * '''remote tags''':
     68   These are snapshots of the state of development taken at a specific point in time. You can check out a 'remote tag', but you should not modify the files thus checked out - for that you need a separate branch (which can be created later though).
     69   The tag's name indicates what's in there. For example, the release of BOINC client version 7.0.60 has been given then tag 'client_release/7.0/7.0.60'.
     70   Run `git tag` to list the remote tags.
     71   * '''remote branches''':
     72   BOINC developers perform long-running work on source code that needs to be visible to other members of the team by working on a 'remote branch'. There are:
     73      * The '''remote master branch''': This is the most recent version of the source code. It always exists, contains the freshest code and has not necessarily been thoroughly tested.
     74      * '''Other branches''': For example, work on version 6.12 of BOINC that is not done in the 'remote master branch', for example due to the need to apply an urgent fix may be done in a remote branch called 'client_release/6/6.12'.
     75        Run `git remote show origin` to list the remote branches.
     76       
     77As you cloned the Git repository, a 'local master branch' was created. This initially corresponds to the 'remote master branch', but once you start editing files, it will evidently deviate from it.
     78
     79You can create local branches and tags (both invisible to anyone but yourself). You can check out a specific 'remote tag' to compile, or you can create a local branch based on a specific 'remote tag' to work on the code.
     80
     81   * See [http://git-scm.com/book/en/Git-Basics-Tagging Git Basics - Tagging] for the concept of 'tagging'.
     82   * See [http://git-scm.com/book/en/Git-Branching-Remote-Branches Git Branching - Remote Branches] for the concept of 'remote branches' and the concepts of the 'local' and 'remote' master branches.
     83   * See [http://stackoverflow.com/questions/1457103/what-is-the-difference-between-a-tag-and-a-branch-in-git What is the difference between a tag and a branch in git?] for a short intro on 'tags' and 'branches'.
     84   * See [http://stackoverflow.com/questions/5582208/checkout-git-tag Checkout GIT tag] for an explanation about 'checking out git tags'.
     85
     86=== Development on the bleeding edge ===
     87
     88If you want to work on the remote 'master' branch, check it out locally:
     89
     90{{{
     91git checkout master
     92}}}
     93
     94Actually this has already happened when you cloned the repository, so the above command is mainly useful if you want to go back to the remote master branch after you modified some files in a hasty fashion.
     95
     96=== Check out a specific tag for compilation ===
     97
     98As said above, the code for each release is 'tagged'. For example, the code for version 7.0.65 is tagged with `client_release/7.0/7.0.65`.
     99
     100Run
     101{{{
     102git tag
     103}}}
     104to list all the visible tags.
     105
     106Run
     107{{{
     108git tag --list '*/7.0/*'
     109}}}
     110to list only the tags matching '/7.0/'.
     111
     112Run
     113{{{
     114git checkout client_release/7.0/7.0.65; git status
     115}}}
     116to check out BOINC client version 7.0.65.
     117
     118...and proceed with compilation.
     119
     120== Server releases ==
     121
     122For all software other than the client (i.e., server, web, and API)
     123a "stable" version is kept in a branch, '''server_release'''.
     124Don't use the server software in a client tag or branch; it probably isn't stable.
     125
     126Run
     127
     128{{{
     129git tag --list 'server_release*'
     130}}}
     131
     132to list the available tags for stable server releases.
     133
     134Notes:
     135
     136 * There is no formal testing process for server software. Every so often, when no bugs have been reported for some time, we tag the '''master''' branch to '''server_release'''.
     137 * Because of limited resources, bug fixes to server software are normally NOT back-ported from '''master''' to '''server_release'''.
     138
     139For these reasons: '''the master branch is typically a better choice than server_release for server software''' (should this not be the reverse?? .ed)
     140
     141== Write Access to the Git Repository ==
    102142
    103143Note: you don't need direct write access to contribute code to BOINC.
     
    106146or send your patches via mail (using {{{git format-patch}}}).
    107147
    108 Direct write access to the main repository is currently available via the SSH protocol
    109 with public-key authentication.
     148Direct write access to the main repository is currently available via the SSH protocol with public-key authentication.
    110149If you want direct write access, contact David Anderson and/or Rom Walton.
    111150They'll ask you for your public-key.
    112 Here's how you can create a public/private key pair and use it after you've been
    113 granted access to the repository:
     151Here's how you can create a public/private key pair and use it after you've been granted access to the repository:
    114152
    115153=== Windows ===