~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/HACKING.txt

  • Committer: Martin Pool
  • Date: 2010-06-11 07:44:09 UTC
  • mto: This revision was merged to the branch mainline in revision 5307.
  • Revision ID: mbp@canonical.com-20100611074409-6q0n1niwmt6c297s
Remove obsolete documentation about using bzr-pqm (thanks bialix)

Show diffs side-by-side

added added

removed removed

Lines of Context:
885
885
how to set it up and configure it.
886
886
 
887
887
 
888
 
Submitting Changes
889
 
==================
890
 
 
891
 
An Overview of PQM
892
 
------------------
893
 
 
894
 
Of the many workflows supported by Bazaar, the one adopted for Bazaar
895
 
development itself is known as "Decentralized with automatic gatekeeper".
896
 
To repeat the explanation of this given on
897
 
http://wiki.bazaar.canonical.com/Workflows:
898
 
 
899
 
.. pull-quote::
900
 
  In this workflow, each developer has their own branch or
901
 
  branches, plus read-only access to the mainline. A software gatekeeper
902
 
  (e.g. PQM) has commit rights to the main branch. When a developer wants
903
 
  their work merged, they request the gatekeeper to merge it. The gatekeeper
904
 
  does a merge, a compile, and runs the test suite. If the code passes, it
905
 
  is merged into the mainline.
906
 
 
907
 
In a nutshell, here's the overall submission process:
908
 
 
909
 
#. get your work ready (including review except for trivial changes)
910
 
#. push to a public location
911
 
#. ask PQM to merge from that location
912
 
 
913
 
.. note::
914
 
  At present, PQM always takes the changes to merge from a branch
915
 
  at a URL that can be read by it. For Bazaar, that means a public,
916
 
  typically http, URL.
917
 
 
918
 
As a result, the following things are needed to use PQM for submissions:
919
 
 
920
 
#. A publicly available web server
921
 
#. Your OpenPGP key registered with PQM (contact RobertCollins for this)
922
 
#. The PQM plugin installed and configured (not strictly required but
923
 
   highly recommended).
924
 
 
925
 
 
926
 
Selecting a Public Branch Location
927
 
----------------------------------
928
 
 
929
 
If you don't have your own web server running, branches can always be
930
 
pushed to Launchpad. Here's the process for doing that:
931
 
 
932
 
Depending on your location throughout the world and the size of your
933
 
repository though, it is often quicker to use an alternative public
934
 
location to Launchpad, particularly if you can set up your own repo and
935
 
push into that. By using an existing repo, push only needs to send the
936
 
changes, instead of the complete repository every time. Note that it is
937
 
easy to register branches in other locations with Launchpad so no benefits
938
 
are lost by going this way.
939
 
 
940
 
.. note::
941
 
  For Canonical staff, http://people.ubuntu.com/~<user>/ is one
942
 
  suggestion for public http branches. Contact your manager for information
943
 
  on accessing this system if required.
944
 
 
945
 
It should also be noted that best practice in this area is subject to
946
 
change as things evolve. For example, once the Bazaar smart server on
947
 
Launchpad supports server-side branching, the performance situation will
948
 
be very different to what it is now (Jun 2007).
949
 
 
950
 
 
951
 
Configuring the PQM Plug-In
952
 
---------------------------
953
 
 
954
 
While not strictly required, the PQM plugin automates a few things and
955
 
reduces the chance of error. Before looking at the plugin, it helps to
956
 
understand  a little more how PQM operates. Basically, PQM requires an
957
 
email indicating what you want it to do. The email typically looks like
958
 
this::
959
 
 
960
 
  star-merge source-branch target-branch
961
 
 
962
 
For example::
963
 
 
964
 
  star-merge http://bzr.arbash-meinel.com/branches/bzr/jam-integration http://bazaar-vcs.org/bzr/bzr.dev
965
 
 
966
 
Note that the command needs to be on one line. The subject of the email
967
 
will be used for the commit message. The email also needs to be ``gpg``
968
 
signed with a key that PQM accepts.
969
 
 
970
 
The advantages of using the PQM plugin are:
971
 
 
972
 
#. You can use the config policies to make it easy to set up public
973
 
   branches, so you don't have to ever type the full paths you want to merge
974
 
   from or into.
975
 
 
976
 
#. It checks to make sure the public branch last revision matches the
977
 
   local last revision so you are submitting what you think you are.
978
 
 
979
 
#. It uses the same public_branch and smtp sending settings as bzr-email,
980
 
   so if you have one set up, you have the other mostly set up.
981
 
 
982
 
#. Thunderbird refuses to not wrap lines, and request lines are usually
983
 
   pretty long (you have 2 long URLs in there).
984
 
 
985
 
Here are sample configuration settings for the PQM plugin. Here are the
986
 
lines in bazaar.conf::
987
 
 
988
 
  [DEFAULT]
989
 
  email = Joe Smith <joe.smith@internode.on.net>
990
 
  smtp_server=mail.internode.on.net:25
991
 
 
992
 
And here are the lines in ``locations.conf`` (or ``branch.conf`` for
993
 
dirstate-tags branches)::
994
 
 
995
 
  [/home/joe/bzr/my-integration]
996
 
  push_location = sftp://joe-smith@bazaar.launchpad.net/%7Ejoe-smith/bzr/my-integration/
997
 
  push_location:policy = norecurse
998
 
  public_branch = http://bazaar.launchpad.net/~joe-smith/bzr/my-integration/
999
 
  public_branch:policy = appendpath
1000
 
  pqm_email = Bazaar PQM <pqm@bazaar-vcs.org>
1001
 
  pqm_branch = http://bazaar-vcs.org/bzr/bzr.dev
1002
 
 
1003
 
Note that the push settings will be added by the first ``push`` on
1004
 
a branch. Indeed the preferred way to generate the lines above is to use
1005
 
``push`` with an argument, then copy-and-paste the other lines into
1006
 
the relevant file.
1007
 
 
1008
 
 
1009
 
Submitting a Change
1010
 
-------------------
1011
 
 
1012
 
Here is one possible recipe once the above environment is set up:
1013
 
 
1014
 
#. pull bzr.dev => my-integration
1015
 
#. merge patch => my-integration
1016
 
#. fix up any final merge conflicts (NEWS being the big killer here).
1017
 
#. commit
1018
 
#. push
1019
 
#. pqm-submit
1020
 
 
1021
 
.. note::
1022
 
  The ``push`` step is not required if ``my-integration`` is a checkout of
1023
 
  a public branch.
1024
 
 
1025
 
  Because of defaults, you can type a single message into commit and
1026
 
  pqm-commit will reuse that.
1027
 
 
1028
 
 
1029
 
Tracking Change Acceptance
1030
 
--------------------------
1031
 
 
1032
 
The web interface to PQM is https://pqm.bazaar-vcs.org/. After submitting
1033
 
a change, you can visit this URL to confirm it was received and placed in
1034
 
PQM's queue.
1035
 
 
1036
 
When PQM completes processing a change, an email is sent to you with the
1037
 
results.
1038
 
 
1039
888
 
1040
889
Planning Releases
1041
890
=================