wiki/src/contribute/git.mdwn

   1 [[!meta title="Git repositories"]]
   2
   3 <div id="intro">
   4
   5 <p>Tails and its website are developed in numerous Git repositories.</p>
   6
   7 <p><span class="application">Git</span> is a distributed version control
   8 system. It allows several people to work on the same source code and
   9 handle changes in a distributed and efficient way.</p>
  10
  11 </div>
  12
  13 [[!toc levels=3]]
  14
  15 <a id="learn_Git"></a>
  16
  17 Learn Git
  18 =========
  19
  20 <p>To learn more about <span class="application">Git</span>, refer to
  21 its <a href="http://git-scm.com/">homepage</a>, and <a
  22 href="http://git-scm.com/documentation">official documentation</a>.</p>
  23
  24 Here are a couple of links to get started with Git:
  25
  26 - Pro Git: [online](http://git-scm.com/book),
  27   [PDF](https://github.s3.amazonaws.com/media/progit.en.pdf), a book on Git from
  28   basic to advanced usage.
  29 - [OpenHatch Missions: Using Git](https://openhatch.org/missions/git), concrete
  30   exercises to train yourself in using Git.
  31 - [Git For Ages 4 And
  32   Up](http://mirror.linux.org.au/linux.conf.au/2013/mp4/Git_For_Ages_4_And_Up.mp4),
  33   a video on learning Git.
  34
  35 <a id="general-information"></a>
  36
  37 General information
  38 ===================
  39
  40 Git hosting setup at immerda
  41 ----------------------------
  42
  43 Documentation for our Git hosting setup at immerda:
  44
  45 * [main documentation](https://wiki.immerda.ch/index.php/GitRepositoriesImmerda)
  46 * [SSL and SSH fingerprints](https://www.immerda.ch/services/certs.html)
  47
  48 Merge policy
  49 ------------
  50
  51 See our [[contribute/merge_policy]].
  52
  53 Caution!
  54 --------
  55
  56 If you want to commit patches that may be published later, you might
  57 want to anonymize them a bit; to do so, run the following commands
  58 in every of your local clones' directories:
  59
  60         git config user.name 'Tails developers'
  61         git config user.email amnesia@boum.org
  62
  63 If you intend to prepare Tails releases, you'll also need to make
  64 the development team signing key the default one for Git tags:
  65
  66         git config user.signingkey 1202821CBE2CD9C1
  67
  68 Creating a new repository
  69 -------------------------
  70
  71 1. Create a new repository at immerda.
  72 2. Create a pull-style mirror at repo.or.cz.
  73
  74 Repositories
  75 ============
  76
  77 Main repository
  78 ---------------
  79
  80 This repository contains the Tails source code and the wiki source.
  81
  82 Anyone can check it out like this:
  83
  84         git clone https://git-tails.immerda.ch/tails
  85
  86 Developers with write access to the repositories should instead:
  87
  88         git clone 'ssh://boum_org_amnesia@webmasters.boum.org/~/wiki.git'
  89
  90 We have a [web interface](https://git-tails.immerda.ch/tails/)
  91 available for the main repository.
  92
  93 ### Branches
  94
  95 Tails development uses several branches modeled a bit like the
  96 Debian development process. Here they are.
  97
  98 #### master
  99
 100 The `master` branch is used by the online wiki.
 101
 102 **FIXME**: document what should go in there, when other branches are
 103 merged into it, etc.
 104
 105 #### stable
 106
 107 The `stable` branch is intended to contain:
 108
 109 - the state of the code tagged for the last stable release
 110 - fixes for security or important bugs.
 111
 112 Its purpose is to prepare minor releases.
 113
 114 #### testing
 115
 116 The `testing` branch is used to prepare an imminent release: at some
 117 point of the development process, the `devel` branch code is merged
 118 into `testing`, frozen, and endures careful testing and bug-fixing
 119 until this branch is considered good enough to become a stable
 120 release. The `testing` branch is then merged into the `stable` and
 121 `master` ones, images built and shipped and we go back to code shiny
 122 new stuff in the `devel` branch.
 123
 124 Please note that the `testing` branch generally has not been granted
 125 the same testing and attention as code that has made it into a
 126 stable release: please use it for testing purposes but do not rely
 127 on it for anything. No guarantee, blablabla.
 128
 129 #### devel
 130
 131 Most of the development work that is done in Tails, is done in the
 132 `devel` branch. This branch will never get released; instead, code
 133 from it will be merged into testing and then into a real release.
 134
 135 Please note that the `devel` branch can be broken, have awful security
 136 problems and so on. No guarantee, blablabla.
 137
 138 The `master` branch is merged into `devel` from time to time.
 139
 140 #### Topic branches
 141
 142 We use topic branches called `bugfix/*` and
 143 `feature/*`, respectively aimed at fixing a single bug and
 144 implementing a single new feature. Once ready, a topic branch is
 145 merged (with `--no-ff`) into the appropriate branch (generally
 146 `devel`). Until it has been merged, a topic branch's history may be
 147 rewritten, e.g. it may be rebased on top of `devel`.
 148
 149 Unless there are good reasons to do otherwise, bugfix branches must be
 150 forked off the latest stable release tag, while feature branches
 151 should are forked off the devel branch.
 152
 153 #### experimental
 154
 155 Generally, it's `devel` plus a few topic branches merged in.
 156 These topic branches are not ready enough to be merged into devel, but
 157 we seriously would like to get them fit for the next stable release,
 158 so this branch serves to test all these new features and bugfixes by
 159 building / getting a single image. The history of this branch is
 160 frequently rewritten and must not be used as the basis of
 161 any development.
 162
 163 Please note that the `experimental` branch can be broken, have awful
 164 security problems and so on. No guarantee, blablabla.
 165
 166 <a id="puppet"></a>
 167
 168 Puppet modules
 169 --------------
 170
 171 Those who have SSH access to these repositories must configure their
 172 SSH client a bit, e.g.:
 173
 174         Host git.puppet.tails.boum.org
 175                 HostName d53ykjpeekuikgoq.onion
 176                 ProxyCommand torsocks monkeysphere ssh-proxycommand %h %p
 177
 178 ### tails
 179
 180 This is the main *public* Puppet module to manage Tails infrastructure,
 181 including classes such as `tails::reprepro` and `tails::whisperback::relay`.
 182
 183 Anyone can check it out like this:
 184
 185         git clone git://git.puppet.tails.boum.org/puppet-tails
 186
 187 Developers with write access to the repositories should instead:
 188
 189         git clone gitolite@git.puppet.tails.boum.org:puppet-tails
 190
 191 ### Other Puppet modules
 192
 193 We use and publish a lot of other Puppet modules. See the section
 194 about our [[other repositories|git#other-repositories]].
 195
 196 ### tails_lizard_manifests
 197
 198 Developers with access to the APT secrets can check it out like this:
 199
 200         git clone gitolite@git.puppet.tails.boum.org:puppet-lizard-manifests
 201
 202 ### tails_secrets_apt
 203
 204 Developers with access to the APT secrets can check it out like this:
 205
 206         git clone gitolite@git.puppet.tails.boum.org:puppet-tails_secrets_apt
 207
 208 ### tails_secrets_whisperback
 209
 210 Developers with access to the WhisperBack secrets can check it out like this:
 211
 212         git clone gitolite@git.puppet.tails.boum.org:puppet-tails_secrets_whisperback
 213
 214 <a id="other-repositories"></a>
 215
 216 Other repositories
 217 ------------------
 218
 219 All other public Tails Git repositories are at
 220 <https://git-tails.immerda.ch/>.
 221
 222 Unauthenticated access is of the form:
 223
 224         git clone https://git-tails.immerda.ch/$REPOSITORY
 225
 226 Developers with write access to the repositories should instead:
 227
 228         git clone tails@git.tails.boum.org:$REPOSITORY