← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/HACKING.txt

Use _merge_type_registry for per_merger tests.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/HACKING.txt
62
62
to involving the community before you spend much time on a change.
63
63
These include:
64
64
 
65
 
* you get to build on the wisdom of others, saving time
 
65
* you get to build on the wisdom on others, saving time
66
66
 
67
67
* if others can direct you to similar code, it minimises the work to be done
68
68
 
120
120
`your_lp_username`.  You can push your branch to Launchpad directly from
121
121
Bazaar::
122
122
 
123
 
  $ bzr push lp:~your_lp_username/bzr/meaningful_name_here
 
123
  $ bzr push lp:~your_lp_username/bzr/giveback
124
124
 
125
125
After you have pushed your branch, you will need to propose it for merging to
126
 
the Bazaar trunk.  Go to
127
 
<https://launchpad.net/your_lp_username/bzr/meaningful_name_here> and choose
128
 
"Propose for merging into another branch".  Select "~bzr/bzr/trunk" to hand
129
 
your changes off to the Bazaar developers for review and merging.
130
 
 
131
 
Using a meaningful name for your branch will help you and the reviewer(s)
132
 
better track the submission. Use a very succint description of your submission
133
 
and prefix it with bug number if needed (lp:~mbp/bzr/484558-merge-directory
134
 
for example). Alternatively, you can suffix with the bug number
135
 
(lp:~jameinel/bzr/export-file-511987).
136
 
 
 
126
the Bazaar trunk.  Go to <https://launchpad.net/your_lp_username/bzr/giveback>
 
127
and choose "Propose for merging into another branch".  Select "~bzr/bzr/trunk"
 
128
to hand your changes off to the Bazaar developers for review and merging.
137
129
 
138
130
Why make a local copy of bzr.dev?
139
131
---------------------------------
688
680
``only_raises`` decorator (from ``bzrlib.decorators``) for methods that
689
681
are typically called in ``finally`` blocks, such as ``unlock`` methods.
690
682
For example, ``@only_raises(LockNotHeld, LockBroken)``.  All errors that
691
 
are unlikely to be a knock-on failure from a previous failure should be
 
683
are unlikely to be a knock-on failure from an previous failure should be
692
684
allowed.
693
685
 
694
686
 
697
689
 
698
690
In some places we have variables which point to callables that construct
699
691
new instances.  That is to say, they can be used a lot like class objects,
700
 
but they shouldn't be *named* like classes::
 
692
but they shouldn't be *named* like classes:
701
693
 
702
694
> I think that things named FooBar should create instances of FooBar when
703
695
> called. Its plain confusing for them to do otherwise. When we have
731
723
those parameters, and this instance then has methods for operations
732
724
between the objects.
733
725
 
734
 
::
735
 
 
736
726
  inter = InterRepository.get(source_repo, target_repo)
737
727
  inter.fetch(revision_id)
738
728
 
1021
1011
time until the finally block runs.
1022
1012
 
1023
1013
 
1024
 
Message guidelines
1025
 
------------------
1026
 
 
1027
 
When filenames or similar variables are presented inline within a message,
1028
 
they should be enclosed in double quotes (ascii 0x22, not chiral unicode
1029
 
quotes)::
1030
 
 
1031
 
  bzr: ERROR: No such file "asdf"
1032
 
 
1033
 
When we print just a list of filenames there should not be any quoting:
1034
 
see `bug 544297`_.
1035
 
 
1036
 
.. _bug 544297: https://bugs.launchpad.net/bugs/544297
1037
 
 
1038
 
https://wiki.ubuntu.com/UnitsPolicy provides a good explanation about
1039
 
which unit should be used when. Roughly speaking, IEC standard applies
1040
 
for base-2 units and SI standard applies for base-10 units:
1041
 
 
1042
 
* for network bandwidth and disk sizes, use base-10 (Mbits/s, kB/s, GB)
1043
 
 
1044
 
* for RAM sizes, use base-2 (GiB, TiB)
1045
 
 
1046
 
 
1047
 
 
1048
1014
Displaying help
1049
1015
===============
1050
1016
 
1053
1019
and on other help topics.  (See ``help_topics.py``.)
1054
1020
 
1055
1021
As for python docstrings, the first paragraph should be a single-sentence
1056
 
synopsis of the command. These are user-visible and should be prefixed with
1057
 
``__doc__ =`` so help works under ``python -OO`` with docstrings stripped.
 
1022
synopsis of the command.
1058
1023
 
1059
1024
The help for options should be one or more proper sentences, starting with
1060
1025
a capital letter and finishing with a full stop (period).
1182
1147
 * new features - should be brought to their attention
1183
1148
 * bug fixes - may be of interest if the bug was affecting them, and
1184
1149
   should include the bug number if any
1185
 
 * major documentation changes, including fixed documentation bugs
 
1150
 * major documentation changes
1186
1151
 * changes to internal interfaces
1187
1152
 
1188
1153
People who made significant contributions to each change are listed in
1189
1154
parenthesis.  This can include reporting bugs (particularly with good
1190
1155
details or reproduction recipes), submitting patches, etc.
1191
1156
 
1192
 
To help with merging, NEWS entries should be sorted lexicographically
1193
 
within each section.
1194
 
 
1195
1157
Commands
1196
1158
--------
1197
1159