Changes between Version 1 and Version 2 of WorkingWithTheRepository


Ignore:
Timestamp:
07/01/15 09:47:43 (9 years ago)
Author:
jdreed
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WorkingWithTheRepository

    v1 v2  
    1 == For Core Developers == 
     1= Working With The Repository = 
     2 
     3== Background == 
     4 
     5The "central" Athena repository is located on `git.mit.edu` (aka `drugstore`), accessible via git+ssh.  You must be on the `athena-commiters` [yes, the typo is deliberate] list in order to read or write to any of the Athena repositories on this server.  
     6 
     7Our git repository is automatically mirrored to the `mit-athena` organization on Github, and anyone without `drugstore` access should clone from there. 
     8 
     9*Note*: This document will use the canonical paths.  In general, you can replace `git+ssh://git.mit.edu/git/athena` with `https://github.com/mit-athena` in a repository URL. 
     10 
     11=== Submodules === 
     12 
     13Because of the vast number of repositories, we use submodules.  The `debathena` repository is the parent repository, and its `.gitmodules` file contains all the submodule information.  If you're not familiar with submodules, please check out [[https://git-scm.com/book/en/v2/Git-Tools-Submodules]] 
     14 
     15Submodule configuration is stored in the `.gitmodules` file, which is itself under version control.  Submodules know both their path, and the last SHA1 they were updated with.  In theory, we would update the central repository every time we make a change to a submodule, so it always points to the submodule's `HEAD`, or at least a reasonable tag.  However, we don't.  It is therefore vital that you ensure your submodule is up to date and that you're on `master` before working on it, lest you find yourself attempt to commit to a detached `HEAD`. 
     16 
     17=== Repository Layout === 
     18 
     19At the top level of the repository are 4 sub-directories: 
     20 
     21* `athena` - This typically contains software we write.  These are "non-native" packages (i.e. packages that consist of more than just a `debian/` directory and some configuration files).  Basically, if something is of value on distributions other than Ubuntu and Debian, it should go in here. 
     22* `debathena` - This typically contains "native" packages (i.e. packages which are "native" to Ubuntu and Debian, and which would not make sense on other distributions) 
     23* `misc` - Things needed as part of the Debathena build infrastructure. 
     24 * `build-system` - The "new" build system components 
     25 * `debathena-common` - Along with manual-config (below), used for manual-config packages 
     26 * `installer` - The installer, both the PXE versions and the script 
     27 * `manual-config` - The "manual-config" packages.  These have the same names as debathena-config packages, but only provide dependencies, and are otherwise empty.  Used by a few users so that, for example, they can install something that depends on `debathena-printing-config` without actually configuring printing. 
     28 * `scripts` - Various scripts, and the "old" build system components 
     29* `third` - A few packages that we build, but for which we are not the upstream source.  These count as "non-native" packages. 
     30 
     31== Initial Repository Cloning == 
     32 
     33If you're only working on a single project, you can of course clone that project as you would any other Git repository.  However, core developers should clone all the submodules at once for simplicity.  This is about 150MB or so. 
     34 
    235{{{ 
    3 $ git clone git+ssh://git.mit.edu/git/athena/debathena athena 
    4 $ cd athena 
     36$ git clone git+ssh://git.mit.edu/git/athena/debathena athena-source-tree 
     37$ cd athena-source-tree 
    538$ git submodule init 
    639$ git submodule update 
    740}}} 
    841 
    9 This will checkout specific SHA1s for each submodule, but will not switch to the master branch.  Checkout the master branch in a submodule _before_ working on it. 
     42(You can of course replace `athena-source-tree` with whatever you'd like your local clone to be called.) 
     43 
     44This will checkout specific SHA1s for each submodule (specifically, whatever the SHA1 was when it was first added as a submodule), but *will not switch to the master branch*. 
     45 
     46== Working on a Package == 
     47 
     48In the example below, we will prepare to work on the `getcluster` package: 
     49 
     50{{{ 
     51jdreed@infinite-loop:~/src/athena-source-tree$ cd athena/getcluster 
     52jdreed@infinite-loop:~/src/athena-source-tree/athena/getcluster$ git status 
     53HEAD detached at 3f5c288 
     54nothing to commit, working directory clean 
     55}}} 
     56 
     57As you can see, this is a deatched HEAD, because the `getcluster` submodule was at `3f5c288` when initially added to the parent repository.  So to work on it, we should ensure we're up to date: 
     58 
     59{{{ 
     60jdreed@infinite-loop:~/src/athena-source-tree/athena/getcluster$ git checkout master 
     61Previous HEAD position was 3f5c288... Revert unintended changelog changes from r25887 
     62Switched to branch 'master' 
     63Your branch is up-to-date with 'origin/master'. 
     64jdreed@infinite-loop:~/src/athena-source-tree/athena/getcluster$ git pull 
     65remote: Counting objects: 6, done. 
     66remote: Compressing objects: 100% (4/4), done. 
     67remote: Total 5 (delta 0), reused 0 (delta 0) 
     68Unpacking objects: 100% (5/5), done. 
     69From git+ssh://git.mit.edu/git/athena/getcluster 
     70   db5520e..772d62f  pristine-tar -> origin/pristine-tar 
     71 * [new tag]         10.2.2-0debathena2 -> 10.2.2-0debathena2 
     72Already up-to-date. 
     73}}} 
     74 
     75We checked out the master branch, and then did a `git pull`.  There were no changes to fetch, but there was a new branch (`pristine-tar`) and a new tag. 
     76 
     77== Branches == 
     78 
     79Non-native packages have two branches: `debian` and `master`.  The `master` branch contains the software itself, but no `debian` directory.  The `debian` branch contains the software plus a `debian/` directory. 
     80 
     81There is also a `pristine-tar` branch, where "pristine" upstream tarballs are stored as part of the build process.  You can check it out remotely, but you basically never want to be working on it.  Continuing from the `getcluster` example above: 
     82 
     83{{{ 
     84jdreed@infinite-loop:~/src/athena-source-tree/athena/getcluster$ ls 
     85getcluster  getcluster.1  setup.py  tests.sh 
     86jdreed@infinite-loop:~/src/athena-source-tree/athena/getcluster$ git branch 
     87  debian 
     88* master 
     89jdreed@infinite-loop:~/src/athena-source-tree/athena/getcluster$ git checkout origin/pristine-tar  
     90Note: checking out 'origin/pristine-tar'. 
     91 
     92You are in 'detached HEAD' state. You can look around, make experimental 
     93changes and commit them, and you can discard any commits you make in this 
     94state without impacting any branches by performing another checkout. 
     95 
     96If you want to create a new branch to retain commits you create, you may 
     97do so (now or later) by using -b with the checkout command again. Example: 
     98 
     99  git checkout -b <new-branch-name> 
     100 
     101HEAD is now at 772d62f... pristine-tar data for getcluster-10.2.2.tar.gz 
     102jdreed@infinite-loop:~/src/athena-source-tree/athena/getcluster$ ls 
     103getcluster-10.2.1.tar.gz.delta  getcluster-10.2.1.tar.gz.id  getcluster-10.2.2.tar.gz.delta  getcluster-10.2.2.tar.gz.id 
     104jdreed@infinite-loop:~/src/athena-source-tree/athena/getcluster$ git checkout master 
     105Previous HEAD position was 772d62f... pristine-tar data for getcluster-10.2.2.tar.gz 
     106Switched to branch 'master' 
     107Your branch is up-to-date with 'origin/master'. 
     108jdreed@infinite-loop:~/src/athena-source-tree/athena/getcluster$ ls 
     109getcluster  getcluster.1  setup.py  tests.sh 
     110}}} 
     111 
     112Native packages only have a `master` branch -- no pristine-tar or debian branches.