1 | | == For Core Developers == |
| 1 | = Working With The Repository = |
| 2 | |
| 3 | == Background == |
| 4 | |
| 5 | The "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 | |
| 7 | Our 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 | |
| 13 | Because 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 | |
| 15 | Submodule 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 | |
| 19 | At 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 | |
| 33 | If 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 | |
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 | |
| 44 | This 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 | |
| 48 | In the example below, we will prepare to work on the `getcluster` package: |
| 49 | |
| 50 | {{{ |
| 51 | jdreed@infinite-loop:~/src/athena-source-tree$ cd athena/getcluster |
| 52 | jdreed@infinite-loop:~/src/athena-source-tree/athena/getcluster$ git status |
| 53 | HEAD detached at 3f5c288 |
| 54 | nothing to commit, working directory clean |
| 55 | }}} |
| 56 | |
| 57 | As 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 | {{{ |
| 60 | jdreed@infinite-loop:~/src/athena-source-tree/athena/getcluster$ git checkout master |
| 61 | Previous HEAD position was 3f5c288... Revert unintended changelog changes from r25887 |
| 62 | Switched to branch 'master' |
| 63 | Your branch is up-to-date with 'origin/master'. |
| 64 | jdreed@infinite-loop:~/src/athena-source-tree/athena/getcluster$ git pull |
| 65 | remote: Counting objects: 6, done. |
| 66 | remote: Compressing objects: 100% (4/4), done. |
| 67 | remote: Total 5 (delta 0), reused 0 (delta 0) |
| 68 | Unpacking objects: 100% (5/5), done. |
| 69 | From 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 |
| 72 | Already up-to-date. |
| 73 | }}} |
| 74 | |
| 75 | We 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 | |
| 79 | Non-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 | |
| 81 | There 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 | {{{ |
| 84 | jdreed@infinite-loop:~/src/athena-source-tree/athena/getcluster$ ls |
| 85 | getcluster getcluster.1 setup.py tests.sh |
| 86 | jdreed@infinite-loop:~/src/athena-source-tree/athena/getcluster$ git branch |
| 87 | debian |
| 88 | * master |
| 89 | jdreed@infinite-loop:~/src/athena-source-tree/athena/getcluster$ git checkout origin/pristine-tar |
| 90 | Note: checking out 'origin/pristine-tar'. |
| 91 | |
| 92 | You are in 'detached HEAD' state. You can look around, make experimental |
| 93 | changes and commit them, and you can discard any commits you make in this |
| 94 | state without impacting any branches by performing another checkout. |
| 95 | |
| 96 | If you want to create a new branch to retain commits you create, you may |
| 97 | do so (now or later) by using -b with the checkout command again. Example: |
| 98 | |
| 99 | git checkout -b <new-branch-name> |
| 100 | |
| 101 | HEAD is now at 772d62f... pristine-tar data for getcluster-10.2.2.tar.gz |
| 102 | jdreed@infinite-loop:~/src/athena-source-tree/athena/getcluster$ ls |
| 103 | getcluster-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 |
| 104 | jdreed@infinite-loop:~/src/athena-source-tree/athena/getcluster$ git checkout master |
| 105 | Previous HEAD position was 772d62f... pristine-tar data for getcluster-10.2.2.tar.gz |
| 106 | Switched to branch 'master' |
| 107 | Your branch is up-to-date with 'origin/master'. |
| 108 | jdreed@infinite-loop:~/src/athena-source-tree/athena/getcluster$ ls |
| 109 | getcluster getcluster.1 setup.py tests.sh |
| 110 | }}} |
| 111 | |
| 112 | Native packages only have a `master` branch -- no pristine-tar or debian branches. |