1// Copyright 2019-2020 Rene Rivera 2// Copyright 2003, 2006 Vladimir Prus 3// Distributed under the Boost Software License, Version 1.0. 4// (See accompanying file LICENSE.txt or http://www.boost.org/LICENSE_1_0.txt) 5 6= B2 contributor guidelines 7 8B2 is an open-source project. This means that we welcome and appreciate 9all contributions -- be it ideas, bug reports, or patches. This document 10contains guidelines which helps to assure that development goes on smoothly, and 11changes are made quickly. 12 13The guidelines are not mandatory, and you can decide for yourself which one to 14follow. But note, that 10 mins that you spare writing a comment, for example, 15might lead to significantly longer delay for everyone. 16 17Before contributing, make sure you are subscribed to our mailing list 18at boost-build@lists.boost.org. 19 20== Additional resources include 21 22=== The issue tracker 23 24https://github.com/boostorg/build/issues 25 26=== Mailing list 27 28boost-build@lists.boost.org 29 30http://lists.boost.org/boost-build/ 31 32== BUGS and PATCHES 33 34Both bugs and patches can be submitted to the GitHub tracker. 35 36When reporting a bug, please try to provide the following information: 37 38* What you did. 39 * A minimal reproducible test case is very much appreciated. 40 * Shell script with some annotations is much better than verbose 41 description of the problem. 42 * A regression test is the best (see test/test_system.html). 43 44* What you got. 45 46* What you expected. 47 48* What version of B2 did you use. If possible, please try to test with the 49 develop branch state. 50 51When submitting a patch, please: 52 53* Make a single patch for a single logical change 54* Follow the policies and coding conventions below 55* Send patches as pull requests to the develop branch 56* Provide a good PR message together with the patch 57 58The purpose of message serves to communicate what was changed, and *why*. 59Without a good message, you might spend a lot of time later, wondering where 60a strange piece of code came from and why it was necessary. 61 62The good message mentions each changed file and each rule/method, saying 63what happened to it, and why. Consider, the following log message 64 65---- 66Better direct request handling. 67 68* new/build-request.jam 69 (directly-requested-properties-adjuster): Redo. 70 71* new/targets.jam 72 (main-target.generate-really): Adjust properties here. 73 74* new/virtual-target.jam 75 (register-actual-name): New rule. 76 (virtual-target.actualize-no-scanner): Call the above, to detected bugs, 77 where two virtual target correspond to one Jam target name. 78---- 79 80The messages for the last two files are good. They tell what was changed. 81The change to the first file is clearly under-commented. 82 83It's okay to use terse messages for uninteresting changes, like ones induced 84by interface changes elsewhere. 85 86== POLICIES 87 88=== Testing 89 90All serious changes must be tested. New rules must be tested by the module where 91they are declared. The test system (link:test/test_system.html[test/test_system.html]) 92should be used to verify user-observable behavior. 93 94=== Documentation 95 96It turns out that it's hard to have too much comments, but it's easy to have too 97little. Please prepend each rule with a comment saying what the rule does and 98what arguments mean. Stop for a minute and consider if the comment makes sense 99for anybody else, and completely describes what the rules does. Generic phrases 100like "adjusts properties" are really not enough. 101 102When applicable, make changes to the user documentation as well. 103 104== CODING CONVENTIONS 105 1061. All names of rules and variables are lowercase with "-" to separate 107 words. 108+ 109---- 110rule call-me-ishmael ( ) ... 111---- 112 1132. Names with dots in them are "intended globals". Ordinary globals use a 114 dot prefix: 115+ 116---- 117.foobar 118$(.foobar) 119---- 120 1213. Pseudofunctions or associations are <parameter>.<property>: 122+ 123---- 124$(argument).name = hello ; 125$($(argument).name) 126---- 127 1284. Class attribute names are prefixed with "self.": 129+ 130---- 131self.x 132$(self.x) 133---- 134 1355. Builtin rules are called via their ALL_UPPERCASE_NAMES: 136+ 137---- 138DEPENDS $(target) : $(sources) ; 139---- 140 1416. Opening and closing braces go on separate lines: 142+ 143---- 144if $(a) 145{ 146 # 147} 148else 149{ 150 # 151} 152---- 153 154== ENGINE 155 156Developing in the `b2` engine, the C++ part, requires two steps to be 157effective: building the "stable" engine, and developing the 158"in-progress" engine. 159 160What is the "stable" engine is up to you. It only refers to a build of the 161engine you know is at a good working state. When you are at a point the 162source is stable you can run `bootstrap.sh/bat` from the root. That will 163create the `b2` executable at the root. You can then use this version to run 164regular B2 builds as needed both within the B2 tree and in other projects. 165 166The "in-progress" engine is whatever build you happen to be testing at the 167moment. There are two ways to build this be engine. You can either 168(a) run `b2 b2` at the root, or (b) run `build.sh/bat` in `src/engine`. 169 170Using (a) will place, by default, a fully debuggable `b2` in the `.build` 171directories. You can run that one from a debugger with full symbols and 172stepping features. This should be the first choice in developing in the 173engine. 174 175After using (a) to implement functionality you can use (b) to fully test 176that functionality. The engine built from (b) is fully optimized and 177is the one used, by default, by the test system when running in the `test` 178directory. Before submitting patches it's required to build this way and 179run the tests in at least one toolset version (but preferably at least two).