mirror of
https://github.com/boostorg/build.git
synced 2026-02-02 20:52:13 +00:00
154 lines
4.9 KiB
Plaintext
154 lines
4.9 KiB
Plaintext
|
|
----------------------------------
|
|
Boost.Build contributor guidelines
|
|
----------------------------------
|
|
|
|
Boost.Build is an open-source project. This means that we welcome and
|
|
appreciate all contributions --- be it ideas, bug reports, or patches.
|
|
This document contains guidelines which helps to assure that development
|
|
goes on smoothly, and changes are made quickly.
|
|
|
|
The guidelines are not mandatory, and you can decide for yourself which one
|
|
to follow. But note, that 10 mins that you spare writing a comment, for
|
|
example, might lead to significally longer delay for everyone.
|
|
|
|
Before contributing, make sure you are subscribed to our mailing list
|
|
|
|
jamboost@yahoogroups.com
|
|
|
|
Additional resources include
|
|
|
|
- brief issues list
|
|
http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl?Boost.Build/Issues
|
|
|
|
- the issue tracker
|
|
http://zigzag.cs.msu.su:7814
|
|
|
|
- commits mailing list:
|
|
boost-build@lists.sourceforge.net
|
|
http://sourceforge.net/mailarchive/forum.php?forum_id=9097
|
|
|
|
|
|
BUGS and PATCHES
|
|
|
|
Both bugs and patches can be send to our mailing list.
|
|
|
|
When reporting a bug, please try to provide the following information.
|
|
|
|
- What you did. A minimal reproducible testcase is very much appreciated.
|
|
Shell script with some annotations is much better than verbose description of
|
|
the problem. A regression test is the best (see test/test_system.html).
|
|
- What you got.
|
|
- What you expected.
|
|
- What version of Boost.Build and Boost.Jam did you use. If possible,
|
|
please try to test with the CVS HEAD state.
|
|
|
|
When submitting a patch, please:
|
|
|
|
- make a single patch for a single logical change
|
|
- follow the policies and coding conventions below,
|
|
- send patches in unified diff format,
|
|
(using either "cvs diff -u" or "diff -u")
|
|
- provide a log message together with the patch
|
|
- put the patch and the log message as attachment to your email.
|
|
|
|
The purpose of log message serves to communicate what was changed, and
|
|
*why*. Without a good log message, you might spend a lot of time later,
|
|
wondering where a strange piece of code came from and why it was necessary.
|
|
|
|
The good log message mentions each changed file and each rule/method, saying
|
|
what happend to it, and why. Consider, the following log message
|
|
|
|
Better direct request handling.
|
|
|
|
* new/build-request.jam
|
|
(directly-requested-properties-adjuster): Redo.
|
|
|
|
* new/targets.jam
|
|
(main-target.generate-really): Adjust properties here.
|
|
|
|
* new/virtual-target.jam
|
|
(register-actual-name): New rule.
|
|
(virtual-target.actualize-no-scanner): Call the above, to detected bugs,
|
|
where two virtual target correspond to one Jam target name.
|
|
|
|
The log messages for the last two files are good. They tell what was
|
|
changed. The change to the first file is clearly undercommented.
|
|
|
|
It's OK to use terse log messages for uninteresting changes, like
|
|
ones induces by interface changes elsewhere.
|
|
|
|
|
|
POLICIES.
|
|
|
|
1. Testing.
|
|
|
|
All serious changes must be tested. New rules must be tested by the module
|
|
where they are declared. Test system (test/test_system.html) should be used
|
|
to verify user-observable behaviour.
|
|
|
|
2. Documentation.
|
|
|
|
It turns out that it's hard to have too much comments, but it's easy to have
|
|
too little. Please predend each rule with a comment saying what the rule does
|
|
and what arguments means. Stop for a minute and consider if the comment makes
|
|
sense for anybody else, and completely describes what the rules does. Generic
|
|
phrases like "adjusts properties" are really not enough.
|
|
|
|
When applicable, make changes to the user documentation as well.
|
|
|
|
|
|
CODING CONVENTIONS.
|
|
|
|
1. All names of rules and variables are lowercase with "-" to separate
|
|
words.
|
|
|
|
rule call-me-ishmael ( ) ...
|
|
|
|
2. Names with dots in them are "intended globals". Ordinary globals use
|
|
a dot prefix:
|
|
|
|
.foobar
|
|
$(.foobar)
|
|
|
|
3. Pseudofunctions or associations are <parameter>.<property>:
|
|
|
|
$(argument).name = hello ;
|
|
$($(argument).name)
|
|
|
|
4. Class attribute names are prefixed with "self.":
|
|
|
|
self.x
|
|
$(self.x)
|
|
|
|
5. Builtin rules are called via their ALL_UPPERCASE_NAMES:
|
|
|
|
DEPENDS $(target) : $(sources) ;
|
|
|
|
6. Opening and closing braces go on separate lines:
|
|
|
|
if $(a)
|
|
{
|
|
#
|
|
}
|
|
else
|
|
{
|
|
#
|
|
}
|
|
|
|
HTML DOCUMENTATION.
|
|
|
|
Please pass HTML files though HTML Tidy (http://tidy.sf.net) before
|
|
comitting. This has to important purposes:
|
|
- detecting bad HTML
|
|
- converting files to uniform indentation style, which inverses effect
|
|
of different editors and makes differences between revisions much
|
|
smaller and easy for review.
|
|
|
|
Alas, the way Tidy indents HTML differs between version. Please use
|
|
the version awailable at
|
|
|
|
http://tidy.sourceforge.net/src/old/tidy_src_020411.tgz
|
|
|
|
and "-i -wrap 78" command line parameters.
|