Sketch new "Maintenance tasks and scripts" contributing dev docs #21061
Conversation
huonw
added
category:documentation
release-notes:not-required
huonw
force-pushed
the
huonw/21034-common-tasks-contributing
branch
from
3e1eca5 to
b754deb
Compare
huonw
force-pushed
the
huonw/21034-common-tasks-contributing
branch
from
b754deb to
64d1aa6
Compare
| 1. Adjust `default_version` and/or `default_artifacts` as required. | ||
| 2. Run `build-support/bin/generate_builtin_lockfiles.py $scope`, where `$scope` is the `options_scope` of the subsystem class. | ||
|
|
||
| Example: none yet. |
There was a problem hiding this comment.
I couldn't find a single JVMToolBase that we've updated since it was first added, i.e. no pull request that does the update. I might've missed one though. Let me know if you know of one.
| ## Generate a new JSON schema file: `generate_json_schema.py` | ||
|
|
||
| Some editors can use JSON Schema for better completions (etc.) when editing TOML files like `pants.toml`. To generate such a schema: | ||
|
|
||
| 1. Run `./pants help-all > all-help.json` | ||
| 2. Run `./pants run build-support/bin/generate_json_schema.py -- --all-help-file=all-help.json` | ||
| 3. For a new release, upload the resulting file to https://www.schemastore.org/json/ |
There was a problem hiding this comment.
I'm not sure of the details here: maybe @AlexTereshenkov is the right person to provide insight? 😄
| ### AWS Lambda | ||
|
|
||
| 1. Adjust `PythonAwsLambdaRuntime.known_runtimes` as required | ||
| 2. Run `build-support/bin/generate_faas_complete_platforms.py` to create any new files and update the existing ones, using AWS's published docker images | ||
|
|
||
| Example: [#21004](https://github.com/pantsbuild/pants/pull/21004). |
There was a problem hiding this comment.
This is the section that (hopefully!) satisfies the original request from #21004 (review)
| 1. For each platform and version to add: | ||
| 1. Download the archive/binary. | ||
| 2. Verify it: check signatures and/or hashes if available. | ||
| 3. Compute the sha256 hash and byte length. For example, if it's called `archive.zip`: `tee >(shasum -a 256) >(wc -c) > /dev/null < archive.zip`. |
There was a problem hiding this comment.
I really like the one line approach with curl, such as:
pants/src/python/pants/core/target_types.py
Lines 225 to 228 in e44697e
There was a problem hiding this comment.
I considered that style, but I thought step 2 was fairly important: if Pants distributed an obviously-incorrect artifact by default (e.g. someone has uploaded a different binary that doesn't match signature), that would be very bad behaviour on our part!
It seems more acceptable/less egregious if a user does it to themselves, in their own local config.
| 1. Run `./pants help-all > all-help.json` | ||
| 2. Run `./pants run build-support/bin/generate_json_schema.py -- --all-help-file=all-help.json` |
There was a problem hiding this comment.
is the ./ prefix here intentional? The previous pants invocation was without.. I guess it'll be a matter of preference to whom ever runs the command, I just wonder if we should be consistent/prefer one over the other in the documentation?
There was a problem hiding this comment.
Ah, just copied from the generate_json_schema.py script. Will adjust. Good catch.
|
Added a section about the auto-cherry-picking based on @lilatomic's idea in #21034 (comment) |
|
I'm gonna get this in as is, and others can iterate/collaborate easily too. Of course, let me know if you have any feedback on this and I'll do a follow-up PR. |
Fixes #21034
This adds a new page to the "contributing > development" section of the docs, that describes various common tasks that happen as part of the development flow. This is partly reminding us of various scripts in
build-support/bin/, but not entirely.This is just a starting point: it doesn't list all the scripts in
build-support/bin/(although some aren't intended for human use anyway, I believe), probably doesn't list all the tasks. Easy to expand in future!Rendered table of contents: