1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
// Copyright 2019-2020 Rene Rivera
// Copyright 2003, 2006 Vladimir Prus
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.txt or https://www.bfgroup.xyz/b2/LICENSE.txt)
= B2 contributor guidelines
B2 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, the 10 mins that you spare writing a comment, for example,
might lead to significantly longer delay for everyone.
== Additional resources include
=== The issue tracker
https://github.com/bfgroup/b2/issues
=== Discussion forums
https://github.com/bfgroup/b2/discussions
== BUGS and PATCHES
Both bugs and patches can be submitted to the GitHub tracker.
When reporting a bug, please try to provide the following information:
* What you did.
* A minimal reproducible test case 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 B2 did you use. If possible, please try to test with the
main branch state.
When submitting a patch, please:
* Make a single patch for a single logical change
* Follow the policies and coding conventions below
* Send patches as pull requests to the main branch
* Provide a good PR message together with the patch
The purpose of message serves to communicate what was changed, and *why*.
Without a good 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 message mentions each changed file and each rule/method, saying
what happened 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 messages for the last two files are good. They tell what was changed.
The change to the first file is clearly under-commented.
It's okay to use terse messages for uninteresting changes, like ones induced
by interface changes elsewhere.
== POLICIES
=== Testing
All serious changes must be tested. New rules must be tested by the module where
they are declared. The test system (link:test/test_system.html[test/test_system.html])
should be used to verify user-observable behavior.
=== Documentation
It turns out that it's hard to have too much comments, but it's easy to have too
little. Please prepend each rule with a comment saying what the rule does and
what arguments mean. 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
{
#
}
----
== ENGINE
Developing in the `b2` engine, the C++ part, requires two steps to be
effective: building the "stable" engine, and developing the
"in-progress" engine.
What is the "stable" engine is up to you. It only refers to a build of the
engine you know is at a good working state. When you are at a point the
source is stable you can run `bootstrap.sh/bat` from the root. That will
create the `b2` executable at the root. You can then use this version to run
regular B2 builds as needed both within the B2 tree and in other projects.
The "in-progress" engine is whatever build you happen to be testing at the
moment. There are two ways to build this be engine. You can either
(a) run `b2 b2` at the root, or (b) run `build.sh/bat` in `src/engine`.
Using (a) will place, by default, a fully debuggable `b2` in the `.build`
directories. You can run that one from a debugger with full symbols and
stepping features. This should be the first choice in developing in the
engine.
After using (a) to implement functionality you can use (b) to fully test
that functionality. The engine built from (b) is fully optimized and
is the one used, by default, by the test system when running in the `test`
directory. Before submitting patches it's required to build this way and
run the tests in at least one toolset version (but preferably at least two).
|
