tools/build/notes/hacking.txt

   1 Copyright 2003, 2006 Vladimir Prus
   2 Distributed under the Boost Software License, Version 1.0.
   3 (See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt)
   4
   5
   6              ----------------------------------
   7              Boost.Build contributor guidelines
   8              ----------------------------------
   9
  10 Boost.Build is an open-source project. This means that we welcome and appreciate
  11 all contributions --- be it ideas, bug reports, or patches. This document
  12 contains guidelines which helps to assure that development goes on smoothly, and
  13 changes are made quickly.
  14
  15 The guidelines are not mandatory, and you can decide for yourself which one to
  16 follow. But note, that 10 mins that you spare writing a comment, for example,
  17 might lead to significally longer delay for everyone.
  18
  19 Before contributing, make sure you are subscribed to our mailing list
  20
  21    boost-build@lists.boost.org
  22
  23 Additional resources include
  24
  25    - The issue tracker
  26      http://trac.lvk.cs.msu.su/boost.build/
  27
  28    - mailing list:
  29      boost-build@lists.boost.org
  30      http://lists.boost.org/boost-build/
  31
  32
  33 BUGS and PATCHES
  34
  35 Both bugs and patches can be send to our mailing list.
  36
  37 When reporting a bug, please try to provide the following information.
  38
  39    - What you did. A minimal reproducible testcase is very much appreciated.
  40      Shell script with some annotations is much better than verbose description
  41      of the problem. A regression test is the best (see test/test_system.html).
  42    - What you got.
  43    - What you expected.
  44    - What version of Boost.Build and Boost.Jam did you use. If possible,
  45      please try to test with the CVS HEAD state.
  46
  47 When submitting a patch, please:
  48
  49   - make a single patch for a single logical change
  50   - follow the policies and coding conventions below,
  51   - send patches in unified diff format,
  52     (using either "cvs diff -u" or "diff -u")
  53   - provide a log message together with the patch
  54   - put the patch and the log message as attachment to your email.
  55
  56 The purpose of log message serves to communicate what was changed, and *why*.
  57 Without a good log message, you might spend a lot of time later, wondering where
  58 a strange piece of code came from and why it was necessary.
  59
  60 The good log message mentions each changed file and each rule/method, saying
  61 what happend to it, and why. Consider, the following log message
  62
  63     Better direct request handling.
  64
  65      * new/build-request.jam
  66        (directly-requested-properties-adjuster): Redo.
  67
  68      * new/targets.jam
  69        (main-target.generate-really): Adjust properties here.
  70
  71      * new/virtual-target.jam
  72        (register-actual-name): New rule.
  73        (virtual-target.actualize-no-scanner): Call the above, to detected bugs,
  74        where two virtual target correspond to one Jam target name.
  75
  76 The log messages for the last two files are good. They tell what was changed.
  77 The change to the first file is clearly undercommented.
  78
  79 It's OK to use terse log messages for uninteresting changes, like ones induced
  80 by interface changes elsewhere.
  81
  82
  83 POLICIES.
  84
  85 1. Testing.
  86
  87 All serious changes must be tested. New rules must be tested by the module where
  88 they are declared. Test system (test/test_system.html) should be used to verify
  89 user-observable behaviour.
  90
  91 2. Documentation.
  92
  93 It turns out that it's hard to have too much comments, but it's easy to have too
  94 little. Please prepend each rule with a comment saying what the rule does and
  95 what arguments mean. Stop for a minute and consider if the comment makes sense
  96 for anybody else, and completely describes what the rules does. Generic phrases
  97 like "adjusts properties" are really not enough.
  98
  99 When applicable, make changes to the user documentation as well.
 100
 101
 102 CODING CONVENTIONS.
 103
 104     1. All names of rules and variables are lowercase with "-" to separate
 105     words.
 106
 107         rule call-me-ishmael ( ) ...
 108
 109     2. Names with dots in them are "intended globals". Ordinary globals use a
 110     dot prefix:
 111
 112         .foobar
 113         $(.foobar)
 114
 115     3. Pseudofunctions or associations are <parameter>.<property>:
 116
 117         $(argument).name = hello ;
 118         $($(argument).name)
 119
 120     4. Class attribute names are prefixed with "self.":
 121
 122         self.x
 123         $(self.x)
 124
 125     5. Builtin rules are called via their ALL_UPPERCASE_NAMES:
 126
 127         DEPENDS $(target) : $(sources) ;
 128
 129     6. Opening and closing braces go on separate lines:
 130
 131         if $(a)
 132         {
 133             #
 134         }
 135         else
 136         {
 137             #
 138         }