README.developers

RELEASE PROCESS
===============

Before tagging the release
--------------------------

Releases should be tagged bdr/version, e.g bdr/0.6.1 .

Before tagging a release:

* run "make check"

  Note that you need contrib/{btree_gist,cube,hstore,pg_trgm} installed to run
  tests.

* Ensure that the version in bdr_version.h.in matches the intended tag

* Ensure that bdr--[ver].sql matches the version in bdr_version.h.in

* Test this version against the previous release to ensure that it
  can successfully replicate data to/from the prior version.

* "git log -- bdr--[ver].sql" to see if there were any changes since it
  was created. If there are, you MUST bump the version in bdr.control to
  the current release version.

* For non-point releases (e.g. 0.6 to 0.7), increase the version in
  bdr.control even if nothing changed in the bdr extension script.

  You should also bump the version in the control file if it's already a
  point-release version like "0.7.1" because it's confusing (but legal) to have
  extension version 0.7.1 with code version 0.7.2 .

* If bdr.control's version was changed since the last release, as shown by
  "git diff bdr/prevver bdr-next -- bdr.control" ensure that a
  "bdr--[oldver]--[ver].sql" script exists and is listed in the Makefile's
  DATA section. Make sure it actually produces the expected results.

  (If there were no changes between the previous and current version's
  extension script, the upgrade script can be empty but must exist).

  It's OK to have versions like "0.7" or versions like "0.7.1" in bdr.control.
  Start with the x.y form, move to x.y.z if you have to change the extension
  script in a patch release.

* TEST that the prior release upgrades to the current release sucessfully.
  You should do this by doing a

      PATH=/path/to/old/release/bin:$PATH make USE_PGXS=1 clean install

  to upgrade the old release's 'bdr' extension to the latest, then restarting
  the server and making sure it upgraded correctly. Check the logs and check
  pg_catalog.pg_extensions for a DB with BDR enabled.

After tagging the release
-------------------------

After tagging a release, immediately bump the version in bdr_version.h.in and
rename bdr--[ver].sql to the new version. This ensures that we don't have a
released 0.6 control file floating around that's different to what's in the
repo)

At a version bump a control file upgrade script must be created, e.g
bdr--0.6--0.7.sql. This needs to be *tested* whenever the main control file is
modified. It needs to be listed in bdr.control .

Dist tarballs
-------------

To prepare a release dist tarball for a tagged release:

    PATH=/usr/pgsql-9.4/bin:$PATH make USE_PGXS=1 git-dist

If you're preparing a dist tarball for a snapshot, not a tagged release, please add the git rev to the filename, e.g.:

    PATH=/usr/pgsql-9.4/bin:$PATH make USE_PGXS=1 git-dist distdir='bdr-$(BDR_VERSION)-git'$(git rev-parse --short HEAD)

Patch releases vs major releases
--------------------------------

There is no firm policy for patch vs major releases.

Anything that affects compatibility should generally get a major release, as
should nontrivial changes to the extension setup script. Code bug fixes,
performance work, etc should generally be minor releases.

Bumping the protocl version
---------------------------

If new release is not protocol compatible with some of the older releases,
BDR_MIN_REMOTE_VERSION_NUM should be bumped accordingly.

GIT INFO
========

The main branch is bdr-next and the official tree is 2ndquadrant_bdr.git at
git.postgresql.org.

This tree is subject to periodic rebasing (as 9.4 is updated) so care must
be taken. Rebases are announced on chat first.

COMMIT GUIDELINES
=================

Prefix the first line of commits against contrib/bdr with "bdr: ". This makes
rebasing easier.

If you're altering the deparse functoinality, apply your changes to the
'deparse' and 'deparse_9_4' (if appropriate) branches, then "git merge" them
into bdr-next. Do not make the changes directly in bdr-next. Prefix the first
line of the commit message with "deparse: ".

If you're patching core, where possible please apply the patch in a separate
working branch then merge it into bdr-next. Prefix the first line of the commit
message with "core: ".

Minor fixes to recent commits should be commited as

    fixup! bdr: original commit message

followed by an explanation. These will get auto-squashed during the next rebase
of bdr-next.

Don't "git push --force" to a tree others might be using without asking. It can
be appropriate to force-push a fix to a recent mistake, but always ask first,
as you can silently clobber other people's changes.

Perform non-trivial work in a working branch then request that it be merged
back in to bdr-next. e.g.

    git checkout bdr-next
    git checkout -b bdr-magic-beans
    ... do your work ...
    git push origin bdr-magic-beans

(If you don't have commit rights to the main 2ndQuadrant_bdr repo, you can push
to a clone on github instead, then email us and ask to merge.)

It's OK to --force push to this working branch, and you should consider doing a
"git rebase --interactive bdr-next", cleaning it up, and then force-pushing the
cleanup before requesting a merge. Don't force-push a branch once you've asked
someone to review it or asked them to pull it.

Read the error message style guide:
http://www.postgresql.org/docs/current/static/error-style-guide.html
and the NLS/translator message guide:
http://www.postgresql.org/docs/current/static/nls-programmer.html#NLS-GUIDELINES
Key points:

* Don't prefix errors with 'bdr: ' or similar. That's what log_error_verbosity is for.
* Primary error messages: Do not capitalize the first letter. Do not end a message with a period.
* Detail and hint messages: Use complete sentences, and end each with a period. Capitalize the first word of sentences.
* Avoid passive voice
* Pay attention to tense
* Avoid contractions and abbreviations
* Avoid "unable", "unknown" (see docs)
* Don't construct messages from chunks of text at runtime