doc/HACKING.md

   1
   2 # -*- mode: markdown ; coding: utf-8 -*-
   3
   4 HACKING
   5 =======
   6
   7 Hack on whatever you like. Ticket are [here][trac]. If you're doing something
   8 big that doesn't have a ticket, you should probably make one. If you don't
   9 want to register for a Trac account, you can use the ```cypherpunks``` account
  10 with password ```writecode```.
  11
  12 ## Generating bridge descriptors
  13
  14 Developers wishing to test BridgeDB will need to generate mock bridge
  15 descriptors. This is accomplished through the file **create-descriptors**.  To
  16 generate 20 bridge descriptors, change to the bridgedb running directory and do:
  17
  18     $ ./scripts/create-descriptors 20
  19
  20 It is recommended that you generate at least 250 descriptors for testing.
  21 Ideally, even more descriptors should be generated, somewhere in the realm of
  22 2000, as certain bugs do not emerge until BridgeDB is processing thousands of
  23 descriptors.
  24
  25 ## Git Workflow
  26
  27 See this article on git branching [workflow][workflow]. The only modifications
  28 we make are:
  29
  30   * Tagging is done in the ```release-*``` branches, rather than in master.
  31   * It's okay to use either the ```feature/*``` and ```fix/*``` branch naming
  32     scheme, or follow little-t Tor's branch naming scheme,
  33     i.e. ```bug666-description-r1```.
  34
  35 ## Making a release
  36
  37 ### Updating dependencies
  38
  39 We maintain three requirements.txt files:
  40
  41 * requirements.txt (for BridgeDB)
  42 * .travis.requirements.txt (for Travis CI)
  43 * .test.requirements.txt (for unit tests)
  44
  45 Each of these files contains pinned dependencies, which are guaranteed to work
  46 for a given release.  Before releasing a new version of BridgeDB, we should
  47 update our dependencies.  The tool [pur][pur] (available through pip) helps us
  48 with this.  It checks a given requirements.txt file and updates each dependency
  49 to its latest version:
  50
  51     pur -r REQUIREMENTS_FILE
  52
  53 ### Bumping the version number
  54
  55 Bumping the version number at release time (which, for BridgeDB really means
  56 deploy time, as of right now) means doing the following:
  57
  58     $ git checkout develop
  59     [merge some fix/bug/feature/etc branches]
  60     $ git checkout -b release-0.0.2 develop
  61     [bump version number in CHANGELOG]
  62     [pip maintainance commands *would* go here, if we ever have any]
  63     $ git checkout master
  64     $ git merge -S --no-ff release-0.0.2
  65     $ git tag -a -s bridgedb-0.0.2
  66     $ git checkout develop
  67     $ git merge -S --no-ff master
  68     $ git push <remote> master develop
  69
  70 And be sure not to forget to do:
  71
  72     $ git push --tags
  73
  74 If the currently installed version is *not* from one of the signed tags, the
  75 version number attribute created by versioneer will be the short ID of the git
  76 commit from which the installation took place, prefixed with the most recent
  77 tagged release at that point, i.e.:
  78
  79     >>> import bridgedb
  80     >>> bridgedb.__version__
  81     0.0.1-git528ff30c
  82
  83 References
  84 ----------
  85 [trac]: https://trac.torproject.org/projects/tor/query?status=!closed&component=Circumvention%2FBridgeDB
  86 [workflow]: https://nvie.com/posts/a-successful-git-branching-model/
  87 [pur]: https://pypi.org/project/pur/