| ... |
... |
@@ -10,6 +10,12 @@ Major feature additions should be proposed on the |
|
10
|
10
|
before being considered for inclusion, we strongly recommend proposing
|
|
11
|
11
|
in advance of commencing work.
|
|
12
|
12
|
|
|
|
13
|
+If you are experiencing an issue with BuildStream or would like to submit a small patch/feature, then
|
|
|
14
|
+you can open issue `here <https://gitlab.com/BuildStream/buildstream/issues/new?issue%5Bassignee_id%5D=&issue%5Bmilestone_id%5D=>`
|
|
|
15
|
+
|
|
|
16
|
+For policies on how to submit and issue and how to use our project labels, we recommend that you read the policies guide
|
|
|
17
|
+`here <https://gitlab.com/BuildStream/nosoftware/alignment/blob/master/BuildStream_policies.md>`
|
|
|
18
|
+
|
|
13
|
19
|
New features must be well documented and tested either in our main
|
|
14
|
20
|
test suite if possible, or otherwise in the integration tests.
|
|
15
|
21
|
|
| ... |
... |
@@ -23,36 +29,26 @@ a reasonable timeframe for identifying these. |
|
23
|
29
|
|
|
24
|
30
|
Patch submissions
|
|
25
|
31
|
-----------------
|
|
26
|
|
-If you want to submit a patch, do ask for developer permissions on our
|
|
27
|
|
-IRC channel first (GitLab's button also works, but you may need to
|
|
28
|
|
-shout about it - we often overlook this) - for CI reasons, it's much
|
|
29
|
|
-easier if patches are in branches of the main repository.
|
|
|
32
|
+Branches must be submitted as merge requests in gitlab and should usually
|
|
|
33
|
+be associated to an issue report on gitlab.
|
|
30
|
34
|
|
|
31
|
|
-Branches must be submitted as merge requests in gitlab. If the branch
|
|
32
|
|
-fixes an issue or is related to any issues, these issues must be mentioned
|
|
33
|
|
-in the merge request or preferably the commit messages themselves.
|
|
|
35
|
+Commits in the branch which address specific issues must specify the
|
|
|
36
|
+issue number in the commit message.
|
|
34
|
37
|
|
|
35
|
|
-Branch names for merge requests should be prefixed with the submitter's
|
|
36
|
|
-name or nickname, e.g. ``username/implement-flying-ponies``.
|
|
37
|
|
-
|
|
38
|
|
-You may open merge requests for the branches you create before you
|
|
39
|
|
-are ready to have them reviewed upstream, as long as your merge request
|
|
40
|
|
-is not yet ready for review then it must be prefixed with the ``WIP:``
|
|
41
|
|
-identifier.
|
|
|
38
|
+Merge requests that are not yet ready for review must be prefixed with the
|
|
|
39
|
+``WIP:`` identifier. A merge request is not ready for review until the
|
|
|
40
|
+submitter expects that the patch is ready to actually land.
|
|
42
|
41
|
|
|
43
|
42
|
Submitted branches must not contain a history of the work done in the
|
|
44
|
43
|
feature branch. Please use git's interactive rebase feature in order to
|
|
45
|
44
|
compose a clean patch series suitable for submission.
|
|
46
|
45
|
|
|
47
|
|
-We prefer that documentation changes be submitted in separate commits from
|
|
48
|
|
-the code changes which they document, and new test cases are also preferred
|
|
49
|
|
-in separate commits.
|
|
|
46
|
+We prefer that test case and documentation changes be submitted
|
|
|
47
|
+in separate commits from the code changes which they test.
|
|
50
|
48
|
|
|
51
|
|
-If a commit in your branch modifies behavior such that a test must also
|
|
52
|
|
-be changed to match the new behavior, then the tests should be updated
|
|
53
|
|
-with the same commit. Ideally every commit in the history of master passes
|
|
54
|
|
-its test cases, this makes bisections more easy to perform, but is not
|
|
55
|
|
-always practical with more complex branches.
|
|
|
49
|
+Ideally every commit in the history of master passes its test cases. This
|
|
|
50
|
+makes bisections more easy to perform, but is not always practical with
|
|
|
51
|
+more complex branches.
|
|
56
|
52
|
|
|
57
|
53
|
|
|
58
|
54
|
Commit messages
|
| ... |
... |
@@ -64,6 +60,9 @@ the change. |
|
64
|
60
|
The summary line must start with what changed, followed by a colon and
|
|
65
|
61
|
a very brief description of the change.
|
|
66
|
62
|
|
|
|
63
|
+If there is an associated issue, it **must** be mentioned somewhere
|
|
|
64
|
+in the commit message.
|
|
|
65
|
+
|
|
67
|
66
|
**Example**::
|
|
68
|
67
|
|
|
69
|
68
|
element.py: Added the frobnicator so that foos are properly frobbed.
|
| ... |
... |
@@ -72,6 +71,8 @@ a very brief description of the change. |
|
72
|
71
|
the element. Elements that are not properly frobnicated raise
|
|
73
|
72
|
an error to inform the user of invalid frobnication rules.
|
|
74
|
73
|
|
|
|
74
|
+ This fixes issue #123
|
|
|
75
|
+
|
|
75
|
76
|
|
|
76
|
77
|
Coding style
|
|
77
|
78
|
------------
|
| ... |
... |
@@ -296,7 +297,7 @@ committed with that. |
|
296
|
297
|
To do this, first ensure you have ``click_man`` installed, possibly
|
|
297
|
298
|
with::
|
|
298
|
299
|
|
|
299
|
|
- pip3 install --user click_man
|
|
|
300
|
+ pip install --user click_man
|
|
300
|
301
|
|
|
301
|
302
|
Then, in the toplevel directory of buildstream, run the following::
|
|
302
|
303
|
|
| ... |
... |
@@ -390,9 +391,6 @@ Each *command* is a dictionary, the members of which are listed here: |
|
390
|
391
|
|
|
391
|
392
|
* ``command``: The command to run, without the leading ``bst``
|
|
392
|
393
|
|
|
393
|
|
-* ``shell``: Specifying ``True`` indicates that ``command`` should be run as
|
|
394
|
|
- a shell command from the project directory, instead of a bst command (optional)
|
|
395
|
|
-
|
|
396
|
394
|
When adding a new ``.run`` file, one should normally also commit the new
|
|
397
|
395
|
resulting generated ``.html`` file(s) into the ``doc/source/sessions-stored/``
|
|
398
|
396
|
directory at the same time, this ensures that other developers do not need to
|
| ... |
... |
@@ -455,7 +453,7 @@ To run the tests, just type:: |
|
455
|
453
|
At the toplevel.
|
|
456
|
454
|
|
|
457
|
455
|
When debugging a test, it can be desirable to see the stdout
|
|
458
|
|
-and stderr generated by a test, to do this use the ``--addopts``
|
|
|
456
|
+and stderr generated by a test, to do this use the --addopts
|
|
459
|
457
|
function to feed arguments to pytest as such::
|
|
460
|
458
|
|
|
461
|
459
|
./setup.py test --addopts -s
|
| ... |
... |
@@ -468,12 +466,7 @@ If you want to run a specific test or a group of tests, you |
|
468
|
466
|
can specify a prefix to match. E.g. if you want to run all of
|
|
469
|
467
|
the frontend tests you can do::
|
|
470
|
468
|
|
|
471
|
|
- ./setup.py test --addopts 'tests/frontend/'
|
|
472
|
|
-
|
|
473
|
|
-Specific tests can be chosen by using the :: delimeter after the test module.
|
|
474
|
|
-If you wanted to run the test_build_track test within frontend/buildtrack.py you could do::
|
|
475
|
|
-
|
|
476
|
|
- ./setup.py test --addopts 'tests/frontend/buildtrack.py::test_build_track'
|
|
|
469
|
+ ./setup.py test --addopts '-k tests/frontend/'
|
|
477
|
470
|
|
|
478
|
471
|
We also have a set of slow integration tests that are disabled by
|
|
479
|
472
|
default - you will notice most of them marked with SKIP in the pytest
|
| ... |
... |
@@ -540,7 +533,7 @@ tool. |
|
540
|
533
|
|
|
541
|
534
|
Python provides `cProfile <https://docs.python.org/3/library/profile.html>`_
|
|
542
|
535
|
which gives you a list of all functions called during execution and how much
|
|
543
|
|
-time was spent in each function. Here is an example of running ``bst --help``
|
|
|
536
|
+time was spent in each function. Here is an example of running `bst --help`
|
|
544
|
537
|
under cProfile:
|
|
545
|
538
|
|
|
546
|
539
|
python3 -m cProfile -o bst.cprofile -- $(which bst) --help
|
