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/services/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 Main repository
  82 ---------------
  83
  84 This repository contains the Tails source code and the wiki source.
  85
  86 Anyone can check it out like this:
  87
  88         git clone https://git-tails.immerda.ch/tails
  89
  90 Developers with write access to the repositories should instead:
  91
  92         git clone 'ssh://boum_org_amnesia@webmasters.boum.org/~/wiki.git'
  93
  94 We have a [web interface](https://git-tails.immerda.ch/tails/)
  95 available for the main repository.
  96
  97 ### Branches
  98
  99 Tails development uses several branches modeled a bit like the
 100 Debian development process. Here they are.
 101
 102 #### master
 103
 104 The `master` branch is used by the online wiki.
 105
 106 **FIXME**: document what should go in there, when other branches are
 107 merged into it, etc.
 108
 109 #### stable
 110
 111 The `stable` branch is intended to contain:
 112
 113 - the state of the code tagged for the last stable release
 114 - fixes for security or important bugs.
 115
 116 Its purpose is to prepare minor releases.
 117
 118 #### testing
 119
 120 The `testing` branch is used to prepare an imminent release: at some
 121 point of the development process, the `devel` branch code is merged
 122 into `testing`, frozen, and endures careful testing and bug-fixing
 123 until this branch is considered good enough to become a stable
 124 release. The `testing` branch is then merged into the `stable` and
 125 `master` ones, images built and shipped and we go back to code shiny
 126 new stuff in the `devel` branch.
 127
 128 Please note that the `testing` branch generally has not been granted
 129 the same testing and attention as code that has made it into a
 130 stable release: please use it for testing purposes but do not rely
 131 on it for anything. No guarantee, blablabla.
 132
 133 #### devel
 134
 135 Most of the development work that is done in Tails, is done in the
 136 `devel` branch. This branch will never get released; instead, code
 137 from it will be merged into testing and then into a real release.
 138
 139 Please note that the `devel` branch can be broken, have awful security
 140 problems and so on. No guarantee, blablabla.
 141
 142 The `master` branch is merged into `devel` from time to time.
 143
 144 #### Topic branches
 145
 146 We use topic branches called `bugfix/*` and
 147 `feature/*`, respectively aimed at fixing a single bug and
 148 implementing a single new feature. Once ready, a topic branch is
 149 merged (with `--no-ff`) into the appropriate branch (generally
 150 `devel`). Until it has been merged, a topic branch's history may be
 151 rewritten, e.g. it may be rebased on top of `devel`.
 152
 153 Unless there are good reasons to do otherwise, bugfix branches must be
 154 forked off the latest stable release tag, while feature branches
 155 should are forked off the devel branch.
 156
 157 #### experimental
 158
 159 Generally, it's `devel` plus a few topic branches merged in.
 160 These topic branches are not ready enough to be merged into devel, but
 161 we seriously would like to get them fit for the next stable release,
 162 so this branch serves to test all these new features and bugfixes by
 163 building / getting a single image. The history of this branch is
 164 frequently rewritten and must not be used as the basis of
 165 any development.
 166
 167 Please note that the `experimental` branch can be broken, have awful
 168 security problems and so on. No guarantee, blablabla.
 169
 170 <a id="puppet"></a>
 171
 172 Puppet modules
 173 --------------
 174
 175 Those who have SSH access to these repositories must configure their
 176 SSH client a bit, e.g.:
 177
 178         Host git.puppet.tails.boum.org
 179                 HostName d53ykjpeekuikgoq.onion
 180                 ProxyCommand torsocks monkeysphere ssh-proxycommand %h %p
 181
 182 ### tails
 183
 184 This is the main *public* Puppet module to manage Tails infrastructure,
 185 including classes such as `tails::reprepro` and `tails::whisperback::relay`.
 186
 187 Anyone can check it out like this:
 188
 189         git clone git://git.puppet.tails.boum.org/puppet-tails
 190
 191 Developers with write access to the repositories should instead:
 192
 193         git clone gitolite@git.puppet.tails.boum.org:puppet-tails
 194
 195 ### Other Puppet modules
 196
 197 We use and publish a lot of other Puppet modules. See the section
 198 about our [[other repositories|git#other-repositories]].
 199
 200 ### tails_lizard_manifests
 201
 202 Developers with access to the APT secrets can check it out like this:
 203
 204         git clone gitolite@git.puppet.tails.boum.org:puppet-lizard-manifests
 205
 206 ### tails_secrets_apt
 207
 208 Developers with access to the APT secrets can check it out like this:
 209
 210         git clone gitolite@git.puppet.tails.boum.org:puppet-tails_secrets_apt
 211
 212 ### tails_secrets_whisperback
 213
 214 Developers with access to the WhisperBack secrets can check it out like this:
 215
 216         git clone gitolite@git.puppet.tails.boum.org:puppet-tails_secrets_whisperback
 217
 218 <a id="other-repositories"></a>
 219
 220 Other repositories
 221 ------------------
 222
 223 All other public Tails Git repositories are at
 224 <https://git-tails.immerda.ch/>.
 225
 226 Unauthenticated access is of the form:
 227
 228         git clone https://git-tails.immerda.ch/$REPOSITORY
 229
 230 Developers with write access to the repositories should instead:
 231
 232         git clone tails@git.tails.boum.org:$REPOSITORY