[Rt-commit] rt branch, 4.0/hacking-docs, created. rt-4.0.0rc6-100-gf9b0b74

[Kevin Falcone]

The branch, 4.0/hacking-docs has been created
        at  f9b0b74110a303439c08b9a0fc1348ad3544dd8c (commit)

- Log -----------------------------------------------------------------
commit f9b0b74110a303439c08b9a0fc1348ad3544dd8c
Author: Alex Vandiver <alexmv at bestpractical.com>
Date:   Thu Mar 17 10:41:16 2011 -0400

    Initial cut at a hacking doc

diff --git a/docs/hacking.pod b/docs/hacking.pod
new file mode 100644
index 0000000..26a45c1
--- /dev/null
+++ b/docs/hacking.pod
@@ -0,0 +1,205 @@
+=head1 Development of RT
+
+RT's source code is stored in a C<git> repository.  If you are not
+familiar with git, see L</git quickstart>, below, for a short tutorial
+which will give you enough information to get started submitting patches
+to RT.
+
+The rest of this document details conventions and tips surrounding the
+organization of RT's version control, source code conventions, and how
+to submit patches.
+
+
+
+=head1 Organization of rt.git
+
+The RT source repository is available via git from GitHub; you can
+browse it at L<http://github.com/bestpractical/rt/> or obtain a local
+copy via:
+
+    git clone git://github.com/bestpractical/rt.git
+
+The bleeding-edge development happens in the C<master> branch.  When a
+major release is anticipated, a "trunk" branch will be branched from
+this -- for example, C<4.0-trunk>.  This will allow the trunk to
+stabilize while feature development continues on C<master>.
+Additionally, as a release is impending for a particular series, a
+release engineering branch will be created, named, for example
+C<4.0.0-releng>.
+
+New feature development should always be based off of the C<master>
+branch.  Branches to fix bugs should be based off of whichever trunk the
+bug originated in.
+
+Feature branches should be named based on the trunk they are branched
+from -- which is to say, the earliest branch they might be merged into.
+For example, a bugfix branched from C<4.0-trunk> might be named
+C<4.0/fail-taint-mode-early>.  A feature branched from C<master> when
+there exists a C<4.0-trunk> but no C<4.2-trunk> might be named
+C<4.2/rename-LogToScreen>.  For consistency, branches should use dashes,
+not underscores, to separate words.
+
+Branches should be reviewed by another developer before being merged.
+Reviewers should make sure that the branch accomplishes what it claims
+to, and does not introduce any unwanted behavior in doing so.  Commit
+messages explain the B<why> as much as the B<what> of each commit, and
+not include extranous changes.
+
+
+=head1 Code conventions
+
+The RT codebase is more than ten years old; as such, there are sections
+which do not (yet) conform to the guidelines below.  Please attempt to
+follow them, even if the code surrounding your changes does not yet.
+
+RT also includes a F<.perltidyrc> in its top-level which encodes many of
+the conventions.
+
+=over
+
+=item Indentation
+
+Each level of indentation should be four spaces; tabs should never be
+used for indentation.
+
+=back
+
+
+
+=head1 Development tips
+
+=head2 Setting up a development environment
+
+=head2 Testsuite
+
+RT also comes with a fairly complete testsuite.  To run it, you will
+need to set environment variables to a database user and password which
+can create and drop databases:
+
+    export RT_DBA_USER=root
+    export RT_DBA_PASSWORD=
+
+To run the testsuite:
+
+    prove -l t/*,t t/*/*.t
+
+If you have multiple processors, you can run the testsuite in parallel,
+which will be significantly faster (obviously, adjust the parameter to
+C<-j> as necessary):
+
+    export RT_TEST_PARALLEL=1
+    prove -l -j5 t/*.t t/*/*.t
+
+The C<*-trunk> and C<master> branches are expected to be passing always
+be passing all tests.  While it is acceptable to break tests in an
+intermediate commit, a branch which does not pass tests will not be
+merged.  Ideally, commits which fix a bug should also include a testcase
+which fails before the fix and succeeds after.
+
+
+
+=head1 git quickstart
+
+=over
+
+=item 1.
+
+You will first need to obtain a copy of git; this is accomplished via
+C<sudo yum install git> in RedHat and derivatives, or C<sudo apt-get
+install git> for Debian or Ubuntu.
+
+=item 2.
+
+Next, obtain a copy of the RT source from git:
+
+    git clone git://github.com/bestpractical/rt.git
+    cd rt
+
+=item 3.
+
+Configure git to know your name and email address; git uses these when
+it makes commits.
+
+    git config user.email your.email at example.com
+    git config user.name Examp L. Name
+
+=item 4.
+
+Switch to the appropriate point to base your work on; this is generally
+C<origin/> followed by the major version, followed by C<-trunk>.  For
+example, if your bug was observed in version 3.8.9, you would choose
+C<origin/3.8-trunk>; if it was in 4.0.0, you would choose
+C<origin/4.0-trunk>.  New features should be based on C<origin/master>.
+
+    git checkout --track origin/4.0-trunk
+
+=item 5.
+
+Give your branch a name based on what you are attempting to accomplish.
+We suggest that branch names be lower-case and separate words with
+dashes, but this branch name is purely for your own reference.
+
+    git branch -M gnupg-encryption
+
+=item 6.
+
+Edit the source tree to make your changes.  A few commands you may find
+useful in doing so are listed below.
+
+To see what files you have changed:
+
+    git status
+
+To see a line-by-line list of changes:
+
+    git diff
+
+To revert a file to the original version:
+
+    git checkout path/to/file
+
+To revert only individual parts of a file:
+
+    git checkout -p path/to/file
+
+See L</Development tips> for more tips for working with the RT codebase.
+
+=item 7.
+
+Check that you have no extraneous changes using C<git diff>, then commit
+your changes:
+
+    git commit -a
+
+You will be prompted to type your commit message.  The first line should
+be a short (E<lt> 80 character) summary of the changes, followed by a
+blank line, followed by a longer description, if necessary.  The commit
+message should not simply restate the diff of which lines were added and
+subtracted, but should rather explain B<what> those changes accomplish,
+and B<why> they are desired.
+
+If your changes are easily split into multiple components, you may wish
+to split your changes into more than one commit; simply return to step 6
+and repeat the with the next related change.  If your changes are B<not>
+related to each other, you should submit them separately; finish step 9,
+then start over from step 4.
+
+=item 8.
+
+Save your commits to patch files:
+
+    git format-patch @{u}
+
+This will print out the names of the files as it creates them.
+
+=item 9.
+
+Attach these files to an email using your standard email client, and
+send it to C<rt-devel at bestpractical.com>.
+
+=back
+
+If you have another bug or feature to implement, simply restart the
+process at step 4.
+
+=cut

-----------------------------------------------------------------------