617
650
the form of URL components.
626
We have a commitment to 6 months API stability - any supported symbol in a
627
release of bzr MUST NOT be altered in any way that would result in
628
breaking existing code that uses it. That means that method names,
629
parameter ordering, parameter names, variable and attribute names etc must
630
not be changed without leaving a 'deprecated forwarder' behind. This even
631
applies to modules and classes.
633
If you wish to change the behaviour of a supported API in an incompatible
634
way, you need to change its name as well. For instance, if I add an optional keyword
635
parameter to branch.commit - that's fine. On the other hand, if I add a
636
keyword parameter to branch.commit which is a *required* transaction
637
object, I should rename the API - i.e. to 'branch.commit_transaction'.
639
When renaming such supported API's, be sure to leave a deprecated_method (or
640
_function or ...) behind which forwards to the new API. See the
641
bzrlib.symbol_versioning module for decorators that take care of the
642
details for you - such as updating the docstring, and issuing a warning
643
when the old api is used.
645
For unsupported API's, it does not hurt to follow this discipline, but it's
646
not required. Minimally though, please try to rename things so that
647
callers will at least get an AttributeError rather than weird results.
650
Deprecation decorators
651
----------------------
653
``bzrlib.symbol_versioning`` provides decorators that can be attached to
654
methods, functions, and other interfaces to indicate that they should no
657
To deprecate a static method you must call ``deprecated_function``
658
(**not** method), after the staticmethod call::
661
@deprecated_function(zero_ninetyone)
662
def create_repository(base, shared=False, format=None):
664
When you deprecate an API, you should not just delete its tests, because
665
then we might introduce bugs in them. If the API is still present at all,
666
it should still work. The basic approach is to use
667
``TestCase.applyDeprecated`` which in one step checks that the API gives
668
the expected deprecation message, and also returns the real result from
669
the method, so that tests can keep running.
671
653
Coding Style Guidelines
672
=======================
654
#######################
677
659
``hasattr`` should not be used because it swallows exceptions including
678
660
``KeyboardInterrupt``. Instead, say something like ::
932
908
being phased out.
911
Object string representations
912
=============================
914
Python prints objects using their ``__repr__`` method when they are
915
written to logs, exception tracebacks, or the debugger. We want
916
objects to have useful representations to help in determining what went
919
If you add a new class you should generally add a ``__repr__`` method
920
unless there is an adequate method in a parent class. There should be a
923
Representations should typically look like Python constructor syntax, but
924
they don't need to include every value in the object and they don't need
925
to be able to actually execute. They're to be read by humans, not
926
machines. Don't hardcode the classname in the format, so that we get the
927
correct value if the method is inherited by a subclass. If you're
928
printing attributes of the object, including strings, you should normally
929
use ``%r`` syntax (to call their repr in turn).
931
Try to avoid the representation becoming more than one or two lines long.
932
(But balance this against including useful information, and simplicity of
935
Because repr methods are often called when something has already gone
936
wrong, they should be written more defensively than most code. The object
937
may be half-initialized or in some other way in an illegal state. The
938
repr method shouldn't raise an exception, or it may hide the (probably
939
more useful) underlying exception.
945
return '%s(%r)' % (self.__class__.__name__,
948
return 'FooObject(**unprintable**)'
957
We have a commitment to 6 months API stability - any supported symbol in a
958
release of bzr MUST NOT be altered in any way that would result in
959
breaking existing code that uses it. That means that method names,
960
parameter ordering, parameter names, variable and attribute names etc must
961
not be changed without leaving a 'deprecated forwarder' behind. This even
962
applies to modules and classes.
964
If you wish to change the behaviour of a supported API in an incompatible
965
way, you need to change its name as well. For instance, if I add an optional keyword
966
parameter to branch.commit - that's fine. On the other hand, if I add a
967
keyword parameter to branch.commit which is a *required* transaction
968
object, I should rename the API - i.e. to 'branch.commit_transaction'.
970
When renaming such supported API's, be sure to leave a deprecated_method (or
971
_function or ...) behind which forwards to the new API. See the
972
bzrlib.symbol_versioning module for decorators that take care of the
973
details for you - such as updating the docstring, and issuing a warning
974
when the old api is used.
976
For unsupported API's, it does not hurt to follow this discipline, but it's
977
not required. Minimally though, please try to rename things so that
978
callers will at least get an AttributeError rather than weird results.
981
Deprecation decorators
982
----------------------
984
``bzrlib.symbol_versioning`` provides decorators that can be attached to
985
methods, functions, and other interfaces to indicate that they should no
986
longer be used. For example::
988
@deprecated_method(deprecated_in((0, 1, 4)))
990
return self._new_foo()
992
To deprecate a static method you must call ``deprecated_function``
993
(**not** method), after the staticmethod call::
996
@deprecated_function(deprecated_in((0, 1, 4)))
997
def create_repository(base, shared=False, format=None):
999
When you deprecate an API, you should not just delete its tests, because
1000
then we might introduce bugs in them. If the API is still present at all,
1001
it should still work. The basic approach is to use
1002
``TestCase.applyDeprecated`` which in one step checks that the API gives
1003
the expected deprecation message, and also returns the real result from
1004
the method, so that tests can keep running.
1006
Deprecation warnings will be suppressed for final releases, but not for
1007
development versions or release candidates, or when running ``bzr
1008
selftest``. This gives developers information about whether their code is
1009
using deprecated functions, but avoids confusing users about things they
1756
1864
As well as prioritizing bugs and nominating them against a
1757
1865
target milestone, Launchpad lets core developers offer to mentor others in
1767
To start a new release cycle:
1769
#. Send mail to the list with the key dates, who will be the release
1770
manager, and the main themes or targetted bugs. Ask people to nominate
1771
objectives, or point out an high-risk things that are best done early,
1772
or that interact with other changes.
1774
#. Add a new "series" in Launchpad at <https://launchpad.net/bzr/+addseries>. There is one
1775
series for every *x.y* release.
1777
Weekly Status Updates
1778
---------------------
1780
TODO: Things to cover:
1782
* Early communication to downstream teams (e.g. Launchpad) about changes in dependencies.
1783
* Reminder re lifecycle and where we're up to right now
1784
* Summary of recent successes and pending work
1785
* Reminder re release objectives
1786
* Reminder re things needing attention, e.g. bug triage, reviews, testing of certain things, etc.
1792
TODO: Get material from http://bazaar-vcs.org/FeatureFreeze.
1796
Making a Release or Release Candidate
1797
-------------------------------------
1799
.. Was previously at http://bazaar-vcs.org/ReleaseChecklist
1801
.. TODO: Still needs more clarity on what's in a RC versus a final
1804
.. TODO: Too much of this is manual but could be automated...
1806
This is the procedure for making a new bzr release:
1808
#. If the release is the first candidate, make a new branch in PQM. (Contact RobertCollins for this step).
1810
Register the branch at https://launchpad.net/products/bzr/+addbranch
1812
#. Run the automatic test suite and any non-automated tests. (For example, try a download over http; these should eventually be scripted though not automatically run.). Try to have all optional dependencies installed so that there are no tests skipped. Also make sure that you have the c extensions compiled (``make`` or ``python setup.py build_ext -i``).
1814
#. In the release branch, update ``version_info`` in ``./bzrlib/__init__.py``
1816
#. Add the date and release number to ``./NEWS``.
1818
#. Update the release number in the README. (It's not there as of 0.15, but please check).
1820
#. Commit these changes to the release branch, using a command like::
1822
bzr commit -m "(jam) Release 0.12rc1."
1824
The diff before you commit will be something like::
1826
=== modified file 'NEWS'
1827
--- NEWS 2006-10-23 13:11:17 +0000
1828
+++ NEWS 2006-10-23 22:50:50 +0000
1831
+bzr 0.12rc1 2006-10-23
1836
=== modified file 'bzrlib/__init__.py'
1837
--- bzrlib/__init__.py 2006-10-16 01:47:43 +0000
1838
+++ bzrlib/__init__.py 2006-10-23 22:49:46 +0000
1840
# Python version 2.0 is (2, 0, 0, 'final', 0)." Additionally we use a
1841
# releaselevel of 'dev' for unreleased under-development code.
1843
-version_info = (0, 12, 0, 'dev', 0)
1844
+version_info = (0, 12, 0, 'candidate', 1)
1846
if version_info[3] == 'final':
1847
version_string = '%d.%d.%d' % version_info[:3]
1849
#. Send the changes to PQM, to update the official master branch.
1851
#. When PQM succeeds, pull down the master release branch.
1853
#. Merge the release branch back into the trunk. Check that changes in NEWS were merged into the right sections. If it's not already done, advance the version number in bzr and bzrlib/__init__.py Submit this back into pqm for bzr.dev.
1855
#. Make a distribution directory by running e.g. ``bzr export /tmp/bzr-<version>/`` in the working directory.
1857
#. Run make in /tmp/bzr-<version>. This creates the extensions from the pyrex source.
1859
#. Run the test suite in the distribution directory
1861
#. Run ``setup.py install`` --root=prefix to do a test install into your system directory, home directory, or some other prefix. Check the install worked and that the installed version is usable. (run the bzr script from the installed path with PYTHONPATH set to the site-packages directory it created). i.e. ::
1863
python setup.py install --root=installed
1864
PYTHONPATH=installed/usr/lib/python2.4/site-packages installed/usr/bin/bzr
1866
#. Clean the tree to get rid of .pyc files etc: make clean && rm -rf build && rm bzrlib/_*.c bzrlib/_*.so
1868
#. Generate the reference documentation in text format: make doc/en/user-reference/bzr_man.txt.
1870
#. Change back to your original branch and then run: make clean && make to create the compiled pyrex extensions. You then need to copy the .c files over to the exported directory.
1872
``find . -name "*.c"`` will tell you which files you need.
1874
#. Create the release tarball::
1876
cd /tmp && tar czf bzr-<version>.tar.gz bzr-<version>
1878
#. Sign the tarball with e.g. ``gpg --detach-sign -a bzr-0.10rc1.tar.gz``
1881
Publishing the release
1882
----------------------
1884
Now you have the releasable product. The next step is making it
1885
available to the world.
1887
#. In <https://launchpad.net/bzr/> click the "Release series" for this
1888
series, to take you to e.g. <https://launchpad.net/bzr/1.1>. Then
1889
click "Register a release", and add information about this release.
1891
#. Within that release, upload the source tarball and the GPG signature.
1893
(These used to also be uploaded to
1894
<sftp://escudero.ubuntu.com/srv/bazaar.canonical.com/www/releases/src>
1895
but that's not accessible to all developers, and gets some mime types
1898
#. Link from http://bazaar-vcs.org/Download to the tarball and signature.
1900
#. Update http://doc.bazaar-vcs.org/ to have a directory of documentation
1901
for this release. (Controlled by the ``update-bzr-docs`` script on
1902
escudero, and also update the ``latest`` symlink in
1903
``/srv/bazaar.canonical.com/doc/``.)
1905
#. Announce on the `Bazaar home page`__
1907
__ http://bazaar-vcs.org/
1910
Announcing the release
1911
----------------------
1913
Now that the release is publicly available, tell people about it.
1915
#. Announce to ``bazaar-announce`` and ``bazaar`` mailing lists.
1916
The announce mail will look something like this:
1918
| Subject: bzr 0.11 release candidate 1
1920
| INTRO HERE. Mention the release number and date, and why the release. (i.e. release candidate for testing, final release of a version, backport/bugfix etc).
1923
| http://bazaar-vcs.org/releases/src/bzr-VERSION.tar.gz
1924
| and GPG signature:
1925
| http://bazaar-vcs.org/releases/src/bzr-VERSION.tar.gz.sig
1927
| DESCRIBE-CHANGES-IN-OVERVIEW-HERE
1929
| DESCRIBE-when the next release will be (if there is another - i.e. this is a release candidate)
1931
| Many thanks to all the contributors to this release! I've included the
1932
| contents of NEWS for VERSION below:
1934
To generate the data from NEWS, just copy and paste the relevant news section and clean it up as appropriate. The main clean-up task is to confirm that all major changes are indeed covered. This can be done by running ``bzr log`` back to the point when the branch was opened and cross checking the changes against the NEWS entries.
1936
(RC announcements should remind plugin maintainers to update their plugins.)
1938
* For point releases (i.e. a release candidate, or an incremental fix to a released version) take everything in the relevant NEWS secion : for 0.11rc2 take everything in NEWS from the bzr 0.11rc2 line to the bzr 0.11rc1 line further down.
1940
* For major releases (i.e. 0.11, 0.12 etc), take all the combined NEWS sections from within that version: for 0.11 take all of the 0.11 specific section, plus 0.11rc2, plus 0.11rc1 etc.
1942
#. Update the `news side menu`__ -- this currently requires downloading the file, editing it, deleting it, and uploading a replacement.
1944
__ http://bazaar-vcs.org/site/menu?action=AttachFile&do=view&target=news.html
1946
#. Update the IRC channel topic. Use the ``/topic`` command to do this, ensuring the new topic text keeps the project name, web site link, etc.
1948
#. Announce on http://freshmeat.net/projects/bzr/
1950
This should be done for both release candidates and final releases. If you do not have a Freshmeat account yet, ask one of the existing admins.
1952
#. Update http://en.wikipedia.org/wiki/Bzr -- this should be done for final releases but not Release Candidates.
1954
#. Package maintainers should update packages when they see the
1959
#. Post to http://mail.python.org/mailman/listinfo/python-announce-list for major releases
1961
#. Update the python package index: <http://pypi.python.org/pypi/bzr> - best
1964
python setup.py register
1966
Remember to check the results afterwards.
1969
Making Win32 installers
1970
-----------------------
1972
**XXX:** This information is now probably obsolete, as Alexander uploads
1973
direct to Launchpad. --mbp 20080116
1975
Alexander Belchenko has been very good about getting packaged installers compiled (see Win32ReleaseChecklist for details). He generally e-mails John Arbash Meinel when they are ready. This is just a brief checklist of what needs to be done.
1977
#. Download and verify the sha1 sums and gpg signatures. Frequently the sha1 files are in dos mode, and need to be converted to unix mode (strip off the trailing ``\r``) before they veryify correctly.
1979
#. Upload to the Launchpad page for this release.
1981
#. Upload to escudero (to the b.c.c/www/releases/win32 directory) using sftp, lftp or rsync
1983
#. Cat the contents of the .sha1 files into the SHA1SUM.
1985
#. Update the SHA1SUM and MD5SUM files using something like ``md5sum bzr-0.14.0.win32.exe >> MD5SUM``. Make sure you use append (>>) rather than overwrite (>).
1987
#. Verify once again that everything is correct with ``sha1sum -c SHA1SUM`` and ``md5sum -c MD5SUM``.
1989
#. Update ``.htaccess`` so that the 'bzr-latest.win32.exe' links point to the latest release. This is not done for candidate releases, only for final releases. (example: bzr-0.14.0, but not bzr-0.14.0rc1).
1991
#. Make sure these urls work as expected:
1993
http://bazaar-vcs.org/releases/win32/bzr-latest.win32-py2.5.exe
1995
http://bazaar-vcs.org/releases/win32/bzr-latest.win32-py2.5.exe.asc
1997
http://bazaar-vcs.org/releases/win32/bzr-latest.win32-py2.4.exe
1999
http://bazaar-vcs.org/releases/win32/bzr-latest.win32-py2.4.exe.asc
2001
http://bazaar-vcs.org/releases/win32/bzr-setup-latest.exe
2003
http://bazaar-vcs.org/releases/win32/bzr-setup-latest.exe.asc
2005
They should all try to download a file with the correct version number.
2007
#. Update http://bazaar-vcs.org/Download to indicate the newly available versions.
2009
#. Update http://bazaar-vcs.org/WindowsDownloads to have the correct version number as well as the correct sha1sum displayed.
2012
The Bazaar PPA archive
2013
----------------------
2015
We build Ubuntu ``.deb`` packages for Bazaar as an important part of the release
2016
process. These packages are hosted in a `Personal Package Archive (PPA)`__ on
2017
Launchpad, at <https://launchpad.net/~bzr/+archive>.
2019
__ https://help.launchpad.net/PPAQuickStart
2021
We build packages for every supported Ubuntu release
2022
<https://wiki.ubuntu.com/Releases>. Packages need no longer be updated
2023
when the release passes end-of-life because all users should have then
2026
The ``debian/`` directory containing the packaging information is kept in
2027
branches on Launchpad, named like
2028
<https://code.launchpad.net/~bzr/bzrtools/packaging-dapper>
2030
Updating the PPA for a new release
2031
----------------------------------
2033
Preconditions for building these packages:
2035
* You must have a Launchpad account and be a member of the `~bzr`__ team
2037
__ https://edge.launchpad.net/~bzr/+members>
2039
* You must have a GPG key registered to your Launchpad account.
2041
* Configure ``dput`` to upload to our PPA with this section in your
2045
fqdn = ppa.launchpad.net
2047
incoming = ~bzr/ubuntu
2049
allow_unsigned_uploads = 0
2051
* You need a Ubuntu (or probably Debian) machine, and ::
2053
sudo apt-get install build-essential devscripts dput
2055
Here is the process; there are some steps which should be automated in
2058
#. You will need a working directory for each supported release, such as
2059
``~/bzr/Packaging/dapper``
2061
#. Download the official tarball of the release to e.g. ``~/bzr/Releases``
2063
#. Copy the original tarball into your per-disto directory, then untar it
2064
and if necessary rename it::
2066
cp -l ~/bzr/Releases/bzrtools-1.3.0.tar.gz bzrtools_1.3.0.orig.tar.gz
2067
tar xfvz bzrtools_1.3.0.orig.tar.gz
2068
mv bzrtools bzrtools-1.3.0
2070
#. Change into that directory and check out the packaging branch::
2074
bzr+ssh://bazaar.launchpad.net/~bzr/bzrtools/packaging-dapper \
2077
#. For Bazaar plugins, change the ``debian/control`` file to express a
2078
dependency on the correct version of ``bzr``.
2080
For bzrtools this is typically::
2082
Build-Depends-Indep: bzr (>= 1.3~), rsync
2083
Depends: ${python:Depends}, bzr (>= 1.3~), bzr (<< 1.4~), patch
2085
#. Make a new ``debian/changelog`` entry for the new release,
2086
either by using ``dch`` or just editing the file::
2088
dch -v '1.3.0-1~bazaar1~dapper1' -D dapper
2090
dch will default to the distro you're working in and this isn't checked
2091
against the version number (which is just our conversion). So make
2094
Make sure you have the correct email address for yourself, version
2095
number, and distribution. It should look something like this::
2097
> bzrtools (1.3.0-1~bazaar1~dapper1) dapper; urgency=low
2099
> * New upstream release.
2101
> -- John Sample <sample@example.com> Mon, 31 Mar 2008 12:36:27 +1100
2103
If you need to upload the package again to fix a problem, normally you
2104
should increment the last number in the version number, following the
2105
distro name. Make sure not to omit the initial ``-1``, and make sure
2106
that the distro name in the version is consistent with the target name
2107
outside the parenthesis.
2109
#. Commit these changes into the packaging branch::
2111
bzr ci -m '1.3.0-1~bazaar1~dapper1: New upstream release.' debian
2113
#. Build a source package::
2117
This will create a ``.changes`` file in the per-distro directory,
2118
and should invoke gpg to sign it with your key.
2119
Check that file is reasonable: it should be uploading to the intended
2120
distribution, have a .orig file included, and the right version number.
2122
#. Upload into the PPA::
2124
dput bzr-ppa ../bzrtools__1.3.0-1\~bazaar1\~dapper1_source.changes
2126
Don't forget the ``bzr-ppa`` component or dput will try to upload into
2127
the main archive by default. You can disable this by adding this
2128
section to your ``.dput.cf``::
2131
fqdn = SPECIFY.A.PPA.NAME
2133
#. You should soon get an "upload accepted" mail from Launchpad, which
2134
means that your package is waiting to be built. You can then track its
2135
progress in <https://launchpad.net/~bzr/+archive> and
2136
<https://launchpad.net/~bzr/+archive/+builds>.
added
removed
doc/developers/HACKING.txt
