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