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