← Back to branch summary

~drizzle-trunk/drizzle/development

« back to all changes in this revision

Viewing changes to docs/contributing/code.rst

  • Committer: Mark Atwood
  • Date: 2012-01-04 16:59:32 UTC
  • mfrom: (2478.2.3 real-key-use-catalog)
  • Revision ID: me@mark.atwood.name-20120104165932-cm0xqs4by0u3p4cy
merge lp:~stewart/drizzle/key-use-catalog

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/contributing/code.rst
 
1
.. _contributing_code:
 
2
 
 
3
Contributing Code
 
4
=================
 
5
 
 
6
We recommend that anyone new to Drizzle who wants to learn the code shoult
 
7
see the
 
8
`Low hanging fruit <https://bugs.launchpad.net/drizzle/+bugs?field.tag=low-hanging-fruit>`_
 
9
list of bugs on Launchpad for possible tasks to take on.
 
10
 
 
11
SSH Keys
 
12
--------
 
13
 
 
14
You will need to add a public SSH key to Launchpad to be able to push branches
 
15
up for merging.  To do this:
 
16
 
 
17
 #. Generate an SSH key (information on how to do this is in `Launchpad's help pages <https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair>`_)
 
18
 #. Go to `your SSH keys page <https://launchpad.net/people/+me/+editsshkeys>`_
 
19
 #. Paste your public key into the text box and click the *Import public key*
 
20
    button
 
21
 
 
22
Logging into Launchpad
 
23
----------------------
 
24
 
 
25
You will need to set up your local bzr configuration with your Launchpad account
 
26
so that you can push branches for merging.  To do this:
 
27
 
 
28
 # bzr launchpad-login username
 
29
 
 
30
Getting the Code
 
31
----------------
 
32
 
 
33
You will need to prepare a directory for working with Drizzle. The following
 
34
example will assume you want to do this in ~/repos/drizzle:
 
35
 
 
36
.. code-block:: bash
 
37
 
 
38
   mkdir ~/repos
 
39
   cd ~/repos
 
40
   bzr init-repo drizzle
 
41
 
 
42
At this stage you now have an initialized a directory named ~/repos/drizzle
 
43
for bzr to use.  Revision data will be stored in this directory so that it
 
44
does not have to be separately downloaded and stored for every branch.
 
45
 
 
46
.. code-block:: bash
 
47
 
 
48
   cd drizzle
 
49
   bzr branch lp:drizzle trunk
 
50
 
 
51
This will take a little while, it is getting all the revisions since the
 
52
beginning of the repository.  This should only ever need to be done once though.
 
53
 
 
54
.. code-block:: bash
 
55
 
 
56
   bzr branch trunk drizzle-bug-NNNNNN
 
57
   cd drizzle-bug-NNNNNN
 
58
 
 
59
This creates a branch from trunk for you to work on.
 
60
 
 
61
Committing Work
 
62
---------------
 
63
 
 
64
All commits need to have a proper description of the changes made.  This is so
 
65
that future developers can read through the bzr log to find out why a certain
 
66
change happened.
 
67
 
 
68
When committing a bug fix please use:
 
69
 
 
70
.. code-block:: bash
 
71
 
 
72
   bzr commit --fixes lp:NNNNNN
 
73
 
 
74
This will automatically attach the branch to the bug report when the branch is
 
75
pushed up.
 
76
 
 
77
Coding Standards
 
78
----------------
 
79
 
 
80
Our coding standards can be found at the
 
81
`Drizzle wiki <http://wiki.drizzle.org/Coding_Standards>`_.
 
82
 
 
83
Test Cases
 
84
----------
 
85
 
 
86
.. program:: test-run
 
87
 
 
88
Where possible, SQL test cases should be created for your code.  Our test cases
 
89
for bug fixes should be in the ``tests/suite/regression`` directory.  For more
 
90
information about creating test cases please see the :ref:`test run <test-run-label>`
 
91
section of our documentation.
 
92
 
 
93
If writing a plugin, the other plugins in trunk have many examples of test cases.
 
94
 
 
95
You should attempt to test your code on multiple platforms before publishing
 
96
it or proposing it for merging.  Your tests must pass on all
 
97
:ref:`supported_platforms` and be idempotent (pass when ran with
 
98
:option:`--repeat-test` 2).  You can test on other platforms by using
 
99
`VirtualBox <https://www.virtualbox.org/>`_ or another virtualization
 
100
server, or by requesting access to the `Drizzle Jenkins server <http://jenkins.drizzle.org/>`_.
 
101
 
 
102
Pushing Work
 
103
------------
 
104
 
 
105
When you want to push your branch to Launchpad for others to see or for merging
 
106
you can use:
 
107
 
 
108
.. code-block:: bash
 
109
 
 
110
   bzr push lp:~username/drizzle/trunk-bug-NNNNNN
 
111
 
 
112
This will create the branch on Launchpad which you will be able to see on the
 
113
`code page <https://code.launchpad.net/drizzle>`_.  If you commit more changes
 
114
to your branch, just ``bzr push`` to publish the new changes.
 
115
 
 
116
Merge Proposals
 
117
---------------
 
118
 
 
119
Once your work is done and ready for review, go to
 
120
`code page <https://code.launchpad.net/drizzle>`_, then click on your branch.
 
121
You will see a link labeled *Propose for merging*.
 
122
 
 
123
In this screen simply fill in what this branch does and click the
 
124
*Propose Merge* button.  Members of the
 
125
`Drizzle merge team <https://launchpad.net/~drizzle-merge>`_
 
126
will review the branch, usually within a few days.
 
127
If approved, it will go though our rigourous testing process, which can
 
128
take several hours.  If it needs more work, feedback will always be given to
 
129
explain why.