doc/GIT-WORKFLOW.md

   1 # Git workflow for SBCL
   2
   3 ## Version numbering
   4
   5 Historically each SBCL commit incremented the number in
   6 version.lisp-expr, and prepended that version number to the first line
   7 of the commit message. For CVS this served us well, but since Git
   8 makes it easier for anyone to create branches that run in parallel to
   9 the current "master" timeline, it destroys the illusion of a single
  10 official timeline defined through version.lisp-expr.
  11
  12 In Git workflow, version.lisp-expr no longer exists in the repository,
  13 nor is the version number prepended to commit messages.
  14
  15 Instead, we construct a version number as follows when building SBCL
  16 or generating a source tarball:
  17
  18 For branch master:
  19
  20   release.commits-on-master-since-release.sha1
  21
  22   Eg. 1.0.48.20-152c97d
  23
  24                           Last release: 1.0.48
  25        Commits on master after release: 20
  26           SHA1 abbrev for current HEAD: 152c97d
  27
  28   If there are no commits on master since the last release, both the
  29   count and the SHA1 are dropped.
  30
  31 For other branches:
  32
  33   release.commits-on-branch-and-master-since-release.branch.commits-on-branch.sha1
  34
  35   Eg. 1.0.44.26.wip-pretty-backtraces.4-674f875
  36
  37                           Last release: 1.0.44
  38        Commits on master after release: 26
  39                                 Branch: wip-pretty-backtraces
  40    Commits on branch but not on master: 4
  41           SHA1 abbrev for current HEAD: 674f875
  42
  43 In both cases -dirty is appended to the version number if the tree
  44 isn't clean when building.
  45
  46 Anyone who publishes binaries built using an altered version, should
  47 do so on a branch named appropriately, so that the binaries identify
  48 themselves as 1.0.50.debian.2 or whatever. If they wish to use a
  49 source release instead working from Git, they should identify their
  50 changes with an appropriate edit to version.lisp-expr.
  51
  52 To cater for those whose existing processes really don't like the
  53 SHA1s part in version numbers, setting NO_GIT_HASH_IN_VERSION=t in the
  54 environment for make.sh will make the version number generator leave
  55 out the hash.
  56
  57 ## Making a release (release.sh)
  58
  59 Short story: use `release.sh`.
  60
  61 `release.sh` makes a release *locally.* This means it will perform all
  62 actions required for the release in the local git checkout, and will
  63 then instruct you how to proceed in order to push the release to the
  64 outside world.
  65
  66 ###Synopsis:
  67
  68     ./release.sh VERSION [-s]
  69
  70 **VERSION** is the version to make a release for. Example: `1.0.46`.
  71
  72 **-s** instructs `git tag` to create a gpg-signed tag for this
  73 release. Highly recommended.
  74
  75 ###Description:
  76
  77 `release.sh` will perform these actions:
  78
  79 * Check that the local checkout is clean.
  80 * Update NEWS and make a commit stating the release version number
  81 * Make an sbcl.<VERSION> tag and optionally sign it.
  82 * Build SBCL
  83 * Run tests
  84 * Build SBCL with the SBCL that just had tests pass
  85 * Build docs
  86 * Create source, binary, documentation tarballs
  87 * Sign these tarballs
  88 * Give you further instructions.
  89
  90 After release.sh is done, you can inspect the results, and commence
  91 struggling with the SF.net file release system from hell. You are very
  92 brave.