[Monotone-commits-diffs] net.venge.monotone.source-tree-cleanup: 80e2ae7c591336ae927ea6bcfd7fabf2e6336179

[code]

revision:            80e2ae7c591336ae927ea6bcfd7fabf2e6336179
date:                2011-01-24T00:17:23
author:              address@hidden
branch:              net.venge.monotone.source-tree-cleanup
changelog:
* rework the Patche submission guidelines section and include the
  issue tracker as number one patch submission tool; also make unit
  and / or functional tests for bug fixes and patches that include
  new functionality a requirement 
* rework Third-party code section; we no longer include the listed
  libraries there as code in-tree and we want to keep it that way;
  also add a small section about copyright checking and documentation
* fix source paths

manifest:
format_version "1"

new_manifest [a50c458bf079d88a999d288d807850ac499a88d7]

old_revision [fdb579b6682d78fac24912e7a82a8209b9a54099]

patch "HACKING"
 from [35cb8c36edb8f8c915b47c5c16f5612247ac4f4a]
   to [eec61a4767dee544ad080408e0ebe7757821c66a]
============================================================
--- HACKING	35cb8c36edb8f8c915b47c5c16f5612247ac4f4a
+++ HACKING	eec61a4767dee544ad080408e0ebe7757821c66a
@@ -33,23 +33,24 @@ astyle --style=gnu -s2 -p
 
 astyle --style=gnu -s2 -p
 
-monotone's source includes a number of third party libraries.  These have
+monotone's source includes third party code and libraries.  These have
 been imported from upstream, and should retain the original coding style of
 the particular library in all cases.  This makes life easier when a
 developer needs to send our fixes upstream or wants to import new upstream
 versions into monotone.
 
-There is a special header file, base.hh, that should be the very first
-#include in every .cc file, without exception.  It makes a small
+There is a special header file, src/base.hh, that should be the very
+first #include in every .cc file, without exception.  It makes a small
 number of inclusions and declarations that we want to be globally
 visible.  Do not include this header in any other header file;
 however, in header files, assume the contents of base.hh are already
 visible.  "make distcheck" will verify that these rules are followed.
-If you modify base.hh, make sure you keep the "audit-includes" script
-consistent with it.  Try not to add things to base.hh; it's intended
+If you modify src/base.hh, make sure you keep the "util/audit-includes"
+script consistent with it.  Try not to add things to base.hh; it's intended
 to be a minimal set of declarations that really do need to be visible
 everywhere.
 
+
 Dialect issues
 --------------
 
@@ -160,6 +161,7 @@ continued to adhere to the dialect we wr
   - prefer character constants ('x') to single-character strings ("x") in
     formatted output sequences.
 
+
 Interfacing with Lua
 --------------------
 
@@ -171,6 +173,7 @@ interfaces with Lua must obey the follow
     and using the arrays otherwise may break hooks that use standard
     functions.
 
+
 Test suites, and writing test cases
 -----------------------------------
 
@@ -187,7 +190,7 @@ for very small changes.  The tests are l
 All changes to monotone that alter monotone's behaviour should include a new
 test.  This includes most changes, but use your judgment about adding tests
 for very small changes.  The tests are located in the source tree in the
-tests/ directory, documentation on writing tests is available in
+test/ directory, documentation on writing tests is available in
 notes/README.testing.
 
 When fixing a bug, check for an existing test case for that bug and
@@ -201,6 +204,7 @@ results_collector.hpp).
 theboost::unit_test::first_failed_assertion function (see
 results_collector.hpp).
 
+
 Documenting large, user visible or otherwise important changes
 --------------------------------------------------------------
 
@@ -211,6 +215,7 @@ save the release master a lot of hassle 
 as soon after the change has been committed as possible.  That will
 save the release master a lot of hassle at the time of release.
 
+
 Single-character macros
 -----------------------
 
@@ -278,6 +283,7 @@ bare capital letters scattered around.  
              function.  You can easily add an overload to "dump" to
              support new types.
 
+
 "Application state" objects
 ---------------------------
 
@@ -344,6 +350,7 @@ the list below.
 
  * "workspace" is responsible for manipulating checked-out source trees.
 
+
 Reporting errors to the user
 ----------------------------
 
@@ -378,45 +385,69 @@ Patch submission guidelines
 Patch submission guidelines
 ---------------------------
 
-Mail patches to 'address@hidden' with a subject beginning with
-'[PATCH]' and followed by a brief description of the patch.  The body of the
-message should contain a description of the patch with reasoning for why the
-changes are required, followed by a prepared commit message.  Patches may
-be included inline in a message, or attached as a text/plain, text/x-diff,
-or text/x-patch attachment.  Make sure your mailer does not mangle the
-patch (e.g. by wrapping lines in the patch) before sending your patch to the
-list.
+Register an account on our code forge at <https://code.monotone.ca> and go to
+the "Issues" view of the "monotone" project listed there.  Then create a
+separate issue for the patch you want to send; describe it briefly in the
+issue's title and explain the reasoning more in detail in the description
+text.  Afterwards append the patch file to the issue so we can review and
+comment on it.  Please do not paste or upload it somewhere else, external
+resources tend to expire from time to time and we would like to preserve
+the information as they are as long as possible. Please do also not include
+your patch inline in the issue's description, so its formatting is not
+destroyed.
 
-All changes to the monotone source require an accompanying commit message.
+If you prefer old-style mail, send your patches to 'address@hidden'
+with a subject beginning with '[PATCH]', again followed by a brief description of
+the patch.  The body of the message should then also contain more information
+with reasoning for why the changes are required.  Patches may be included inline
+in a message, or attached as a text/plain, text/x-diff, or text/x-patch attachment.
+Make sure your mailer does not mangle the patch (e.g. by wrapping lines in the
+patch) before sending your patch to the list.
+
+All changes to the monotone source require an accompanying commit message, so
+please add a prepared commit message to your submission, as it will make our
+lives a little easier.
+
 Any changes that affect the user interface (e.g. adding command-line
 options, changing the output format) or affect the documented behaviour of
-monotone must include appropriate changes to the documentation.
+monotone must include appropriate changes to the documentation.  Please also
+think about adding unit and / or functional tests for bug fixes or new features
+in your patch.
 
-Please review your patch prior to submission, to not include
+Finally, please review your patch prior to submission, to not include
 accidental white-space-only changes or changes to the language
 files. Usually you should revert po/*.po files before generating a
 patch - unfortunately these are often changed when you build but do
 not contain any reasonable changes. Alternatively restrict mtn diff to
 the files you've actually changed.
 
-The monotone development team review and comment on all patches on a
+The monotone development team will review and comment on all patches on a
 best-efforts basis.  Patches are never ignored, but a patch may not be
 discussed or applied immediately according to the amount of spare time the
 developers have.  Don't be discouraged if you don't receive an immediate
 response, and if you feel that your patch has slipped through the cracks,
-post a follow up reminder message with a pointer to the original message in
-the mailing list archives.
+post a follow up reminder message with a pointer to the original issue
+or message to the mailing list archives.
 
 
 Third-party code
 ----------------
 
-monotone contains parts of a number of third-party libraries, including but
-not limited to: Lua, Popt, Botan, SQLite, Netxx, and libidn.  See AUTHORS
-for complete details on the included third-party code and the copyrights and
-licenses of each portion.
+monotone used to include a number of libraries directly in its source
+tree for a long time.  Today we prefer to keep big external sources
+outside of our tree, with the exception of our network library "Netxx"
+which has been abandoned by its original author long ago and which has
+also seen minor modifications from our side in the meantime.
 
-From time to time, bug fixes to this third-party code are required.  These
+So if you write new code that depends on third-party code or libraries,
+then try to rely on packaged versions of this code as much as possible.
+If this is impractical, for example because its only one file or even
+a single method you need, check the copyrights of the code in question for
+compatibility with the GPL that is used for monotone and add individual
+copyrights to the AUTHORS file before you copy it into monotone's
+source tree.
+
+Also from time to time, bug fixes to third-party code are required.  These
 fixes should be made in the monotone versions of the code first to solve the
 immediate problem.  In all cases that make sense (i.e. for general bug
 fixes), the change should also be sent to the upstream developers for