Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

Commit ef205f5

Browse filesBrowse files
authored
docs: add some docs to help contributors get started (#2623)
A common pattern I've seen with PRs is they lack tests. I suspect part of the reason is authors aren't sure how to write tests or where to start. So here's some basic docs to help.
1 parent f9779ee commit ef205f5
Copy full SHA for ef205f5

File tree

Expand file treeCollapse file tree

2 files changed

+89
-13
lines changed
Filter options
Expand file treeCollapse file tree

2 files changed

+89
-13
lines changed

‎CONTRIBUTING.md

Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+12-13Lines changed: 12 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -65,20 +65,10 @@ git push origin my-feature
6565
Once the code is in your github repo, you can then turn it into a Pull Request
6666
to the actual rules_python project and begin the code review process.
6767

68+
## Developer guide
6869

69-
## Running tests
70-
71-
Running tests is particularly easy thanks to Bazel, simply run:
72-
73-
```
74-
bazel test //...
75-
```
76-
77-
And it will run all the tests it can find. The first time you do this, it will
78-
probably take long time because various dependencies will need to be downloaded
79-
and setup. Subsequent runs will be faster, but there are many tests, and some of
80-
them are slow. If you're working on a particular area of code, you can run just
81-
the tests in those directories instead, which can speed up your edit-run cycle.
70+
For more more details, guidance, and tips for working with the code base,
71+
see [DEVELOPING.md](DEVELOPING.md)
8272

8373
## Formatting
8474

@@ -192,6 +182,15 @@ merged:
192182
`compile_pip_requirements` update target, which is usually in the same directory.
193183
e.g. `bazel run //docs:requirements.update`
194184

185+
## Binary artifacts
186+
187+
Checking in binary artifacts is not allowed. This is because they are extremely
188+
problematic to verify and ensure they're safe
189+
190+
Examples include, but aren't limited to: prebuilt binaries, shared libraries,
191+
zip files, or wheels.
192+
193+
195194
(breaking-changes)=
196195
## Breaking Changes
197196

‎DEVELOPING.md

Copy file name to clipboardExpand all lines: DEVELOPING.md
+77Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,82 @@
11
# For Developers
22

3+
This document covers tips and guidance for working on the rules_python code
4+
base. A primary audience for it is first time contributors.
5+
6+
## Running tests
7+
8+
Running tests is particularly easy thanks to Bazel, simply run:
9+
10+
```
11+
bazel test //...
12+
```
13+
14+
And it will run all the tests it can find. The first time you do this, it will
15+
probably take long time because various dependencies will need to be downloaded
16+
and setup. Subsequent runs will be faster, but there are many tests, and some of
17+
them are slow. If you're working on a particular area of code, you can run just
18+
the tests in those directories instead, which can speed up your edit-run cycle.
19+
20+
## Writing Tests
21+
22+
Most code should have tests of some sort. This helps us have confidence that
23+
refactors didn't break anything and that releases won't have regressions.
24+
25+
We don't require 100% test coverage, testing certain Bazel functionality is
26+
difficult, and some edge cases are simply too hard to test or not worth the
27+
extra complexity. We try to judiciously decide when not having tests is a good
28+
idea.
29+
30+
Tests go under `tests/`. They are loosely organized into directories for the
31+
particular subsystem or functionality they are testing. If an existing directory
32+
doesn't seem like a good match for the functionality being testing, then it's
33+
fine to create a new directory.
34+
35+
Re-usable test helpers and support code go in `tests/support`. Tests don't need
36+
to be perfectly factored and not every common thing a test does needs to be
37+
factored into a more generally reusable piece. Copying and pasting is fine. It's
38+
more important for tests to balance understandability and maintainability.
39+
40+
### sh_py_run_test
41+
42+
The [`sh_py_run_test`](tests/support/sh_py_run_test.bzl) rule is a helper to
43+
make it easy to run a Python program with custom build settings using a shell
44+
script to perform setup and verification. This is best to use when verifying
45+
behavior needs certain environment variables or directory structures to
46+
correctly and reliably verify behavior.
47+
48+
When adding a test, you may find the flag you need to set isn't supported by
49+
the rule. To have it support setting a new flag, see the py_reconfig_test docs
50+
below.
51+
52+
### py_reconfig_test
53+
54+
The `py_reconfig_test` and `py_reconfig_binary` rules are helpers for running
55+
Python binaries and tests with custom build flags. This is best to use when
56+
verifying behavior that requires specific flags to be set and when the program
57+
itself can verify the desired state.
58+
59+
When adding a test, you may find the flag you need to set isn't supported by
60+
the rule. To have it support setting a new flag:
61+
62+
* Add an attribute to the rule. It should have the same name as the flag
63+
it's for. It should be a string, string_list, or label attribute -- this
64+
allows distinguishing between if the value was specified or not.
65+
* Modify the transition and add the flag to both the inputs and outputs
66+
list, then modify the transition's logic to check the attribute and set
67+
the flag value if the attribute is set.
68+
69+
### Integration tests
70+
71+
An integration test is one that runs a separate Bazel instance inside the test.
72+
These tests are discouraged unless absolutely necessary because they are slow,
73+
require much memory and CPU, and are generally harder to debug. Integration
74+
tests are reserved for things that simple can't be tested otherwise, or for
75+
simple high level verification tests.
76+
77+
Integration tests live in `tests/integration`. When possible, add to an existing
78+
integration test.
79+
380
## Updating internal dependencies
481

582
1. Modify the `./python/private/pypi/requirements.txt` file and run:

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.