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
|
# rules_pkg - Information for Developers
NOTE: This is perpetually a work in progress. We will revise it as we need.
## PR guidelines
Please discuss proposed major features and structural changes before sending a
PR. The best way to do that is to do one or more of the following.
1. Create an issue
1. Discuss it in the issue or in rules-pkg-discuss@googlegroups.com
1. Bring it up at the monthly engineering meeting. (See #325 for
details)[https://github.com/bazelbuild/rules_pkg/issues/325].
### A few small PRs are better than one big one.
If you need to refactor a lot of code before you can add new behavior, please
send a refactoring PR first (which should not add or change tests), then send a
smaller change that implements the new behavior.
## Functionality
### General solutions are better than package specific ones.
- Favor solutions that can be reused for all package formats. We will not
accept contributions that add specific features to one package format when
they could be incorporated into existing `pkg_files` and related rules such
that they could be used by all formats.
- We are moving towards aligning attribute names across rules. If we want
backwards compatibility with older versions, do that in the macro wrapper.
### Tests
- All behavioral changes require tests. Even if you are fixing what is most
likely a bug, please add a test that would have failed before the fix and
passes after.
- Aim for minimal tests. Favor unit tests over integration tests. It is better
to have many small tests rather than one that checks many conditions.
- Continuous testing is defined under `.bazel_ci`.
### Portability
- All of the code must work on Linux, macOS, and Windows. Other OSes are
optional, but we do not have CI to ensure it. If you are making changes that
require something specifically for portability, your change should include
inline comments about why, so a future maintainer does not accidentally
revert it.
- Some features can not work on all platforms. Favor solutions that allow
auto-skipping tests that are platform specific rather than requiring
exclusion lists in CI.
### Major features require commitment
We would love to have features like an MSI builder or macOS application support.
Before accepting a PR for something like that, we want to know that your
organization will commit to maintaining that feature and responding to issues.
## About the code
### Repository structure: run time vs build time
- pkg/... contains what is needed at run time. Everything else is not part of
the packaged distribution releases.
- docs/... is served as github pages. We mostly generate that rather than edit
by hand.
- distro/... contains the rules to create the distribution package.
- examples/... contains runnable examples which serve as additional
documentation. These are tested in CI.
- tests/... contains unit and integration tests. It is a distinct folder so
that it is not needed in the distribution runtime.
- <root> contains shims for the .bzl files in pkg/*.bzl. They add backwards
compatibility to to older releases.
### Starlark style
- We are moving towards fully generated docs. If you touch an attribute, you
must update the docstring to explain it.
- Add docstrings args defined in macros. We are targeting the future time when
stardoc can build unified documentation for the rule and the wrapper.
- Actions should not write quoted strings to command lines. If your rule must
pass file paths to another program, write the paths to an intermediate file
and pass that as an arg to the other program.
[See #214](https://github.com/bazelbuild/rules_pkg/issues/214).
- Run buildifier on you .bzl files before sending a PR.
### Python style
- We use Python 3. We are not trying to support Python 2 at all.
- Always import with a full path from the root of the source tree.
- Compatibility back to python 3.6 (for CentOS 7 and Ubuntu 18.04 LTS) is
required.
### Dependencies
- No new dependencies on language toolchains. We take a dependency on Python
because it is generally available on all OSes.
- No new python package dependencies. Use only what is part of the core
distribution.
- Other new dependencies are strongly discouraged. The exception is that we
may take dependencies on other modules maintained by the Bazel team.
### Write for vendoring the source tree.
We presume that some users will vendor this entire rule set into their source
tree and want to test it from their WORKSPACE. Towards that end we try to
minimize the places where we assume the path to any package is absolute
from WORKSPACE. See tests/package_naming_aggregate_test.sh for an example
of how we can write a sh_test that works after re-rooting the sources.
|
