Large scale VCS change management
Project description
Silver-Platter makes it possible to contribute automatable changes to source code in a version control system (codemods).
It automatically creates a local checkout of a remote repository, makes user-specified changes, publishes those changes on the remote hosting site and then creates a pull request.
In addition to that, it can also perform basic maintenance on branches that have been proposed for merging - such as restarting them if they have conflicts due to upstream changes.
Silver-Platter powers the Debian Janitor (https://janitor.debian.org/) and Kali Janitor (https://kali.janitor.org/). However, it is an independent project and can be used fine as a standalone tool. The UI is still a bit rough around the edges, I’d be grateful for any feedback from people using it - please file bugs in the issue tracker at https://github.com/jelmer/silver-platter/issues/new.
Getting started
To log in to a code-hosting site, use svp login:
svp login https://github.com/
The simplest way to create a change as a merge proposal is to run something like:
svp run --mode=propose ./framwork.sh https://github.com/jelmer/dulwich
where framwork.sh makes some modifications to a working copy and prints the commit message and body for the pull request to standard out. For example:
#!/bin/sh sed -i 's/framwork/framework/' README.rst echo "Fix common typo: framwork ⇒ framework"
If you leave pending changes, silver-platter will automatically create a commit and use the output from the script as the commit message. Scripts also create their own commits if they prefer - this is especially useful if they would like to create multiple commits.
Recipes
To make this process a little bit easier to repeat, recipe files can be used. For the example above, we could create a framwork.yaml with the following contents:
--- name: framwork command: |- sed -i 's/framwork/framework/' README.rst echo "Fix common typo: framwork ⇒ framework" mode: propose merge-request: commit-message: Fix a typo description: markdown: |- I spotted that we often mistype *framework* as *framwork*.
To execute this recipe, run:
svp run --recipe=framwork.yaml https://github.com/jelmer/dulwich
See example.yaml for an example recipe with plenty of comments.
In addition, you can run a particular recipe over a set of repositories by specifying a candidate list. For example, if candidates.yaml looked like this:
--- - url: https://github.com/dulwich/dulwich - url: https://github.com/jelmer/xandikos
then the following command would process each repository in turn:
svp run --recipe=framwork.yaml --candidates=candidates.yaml
Batch Mode
Use batch mode when you’re going to make a large number of changes and would like to review or modify the diffs before sending them out:
svp batch generate --recipe=framwork.yaml --candidates=candidate.syml framwork
This will then create a directory called “framwork”, with a file called batch.yaml with all the pending changes:
name: framwork work: - url: https://github.com/dulwich/dulwich name: dulwich description: I spotted that we often mistype *framework* as *framwork*. commit-message: Fix a typo mode: propose - url: https://github.com/jelmer/xandikos name: dulwich description: I spotted that we often mistype *framework* as *framwork*. commit-message: Fix a typo mode: propose recipe: ../framwork.yaml
For each of the candidates, a clone with the changes is created. You can introspect and modify the clones as appropriate.
After you review the changes, edit batch.yaml as you see fit - remove entries that don’t appear to be correct, edit the details for the merge requests, etc.
Once you’re happy, you can publish the results:
svp batch publish framwork
This will publish all the changes, using the mode and parameters specified in batch.yaml.
batch.yaml is automatically stripped of any entries in work that have fully landed, i.e. where the pull request has been merged or where the changes were pushed to the origin.
To check up on the status of your changes, run svp batch status:
svp batch status framwork
And to refresh any merge proposals that may have become out of date, run publish again:
svp batch publish framwork
Supported hosters
At the moment, the following code hosters are supported:
GitLab instances, such as Debian’s Salsa or GNOME’s GitLab
Working with Debian packages
Several common operations for Debian packages have dedicated subcommands under the debian-svp command. These will also automatically look up packaging repository location for any Debian package names that are specified.
upload-pending: Build and upload a package and push/propose the changelog updates.
run: Similar to svp run but specific to Debian packages: it ensures that the upstream and pristine-tar branches are available as well, can optionally update the changelog, and can test that the branch still builds.
Some Debian-specific example recipes are provided in examples/debian/:
lintian-fixes.yaml: Run the lintian-brush command to fix common issues reported by lintian.
new-upstream-release.yaml: Merge in a new upstream release.
multi-arch-hints.yaml: Apply multi-arch hints.
orphan.yaml: Mark a package as orphaned, update its Maintainer field and move it to the common Debian salsa group.
rules-requires-root.yaml: Mark a package as “Rules-Requires-Root: no”
cme.yaml: Run “cme fix dpkg”, from the cme package.
debian-svp run takes package name arguments that will be resolved to repository locations from the Vcs-Git field in the package.
See debian-svp COMMAND --help for more details.
Examples running debian-svp:
# Create merge proposal running lintian-brush against Samba debian-svp run --recipe=examples/lintian-brush.yaml samba # Upload pending changes for tdb debian-svp upload-pending tdb # Upload pending changes for any packages maintained by Jelmer, # querying vcswatch. debian-svp upload-pending --vcswatch --maintainer jelmer@debian.org # Import the latest upstream release for tdb, without testing # the build afterwards. debian-svp run --recipe=examples/debian/new-upstream-release.yaml \ --no-build-verify tdb # Apply multi-arch hints to tdb debian-svp run --recipe=examples/debian/multiarch-hints.yaml tdb
The following environment variables are provided for Debian packages:
DEB_SOURCE: the source package name
DEB_UPDATE_CHANGELOG: indicates whether a changelog entry should be added. Either “leave” (leave alone) or “update” (update changelog).
Credentials
The svp hosters subcommand can be used to display the hosting sites that silver-platter is aware of:
svp hosters
And to log into a new hosting site, simply run svp login BASE-URL, e.g.:
svp login https://launchpad.net/
Exit status
svp run will exit 0 if no changes have been made, 1 if at least one repository has been changed and 2 in case of trouble.
Python API
Other than the command-line API, silver-platter also has a Python API. The core class is the Workspace context manager, which exists in two forms:
silver_platter.workspace.Workspace (for generic projects)
silver_platter.debian.Workspace (for Debian packages)
An example, adding a new entry to a changelog file in the dulwich Debian package and creating a merge proposal with that change:
from silver_platter.debian import Workspace import subprocess with Workspace.from_apt_package(package="dulwich") as ws: subprocess.check_call(['dch', 'some change'], cwd=ws.path) ws.commit() # Behaves like debcommit ws.publish(mode='propose')
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for silver_platter-0.5.25-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d1687158e8e84be5102fb93f9cf67185e6394e4cd7c9e82267603db7cc61dff0 |
|
MD5 | c7a166c41d2b411d94b1d8f016c4b6bd |
|
BLAKE2b-256 | adb2f9ac9e36fe2e4fa2642fd382b5a1f0f793768c2e9e6f6fc8b6f20a4b7545 |
Hashes for silver_platter-0.5.25-cp312-cp312-manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 564e1beef609d67e93c109862ca1d45e86aca4ed4adb3fe9603e60a537324a8a |
|
MD5 | 57a16d7d03b1dae7aeeba92cd66ff203 |
|
BLAKE2b-256 | beaa6c07d3e1725eedded9c4fbdcdaca73e14bba8050476e93d67fcd483f5651 |
Hashes for silver_platter-0.5.25-cp312-cp312-macosx_11_0_arm64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 42dd737d8fd8039451c60d8083bf77fc080d8f6788fb277c635576e71741ec0c |
|
MD5 | 2ed6378f0c7780688c92f49cb89c3305 |
|
BLAKE2b-256 | 412090a0f33e2809fb5bbf4f0e62c5ee86dd18d8efb77a0c34bfaa3e8287ffba |
Hashes for silver_platter-0.5.25-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2eb11df46d7ff5c41401cdf7f64ccf504dc13e4cdd521c62a2cdbe54c82377c9 |
|
MD5 | 4d743dfaafb74a8e5878a9a04256b08e |
|
BLAKE2b-256 | 099f8ed6d24741f4f5aab1f63c1688ea39dd8f286dbcec98f1213cf5f699f8af |
Hashes for silver_platter-0.5.25-cp311-cp311-manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 77a15ee353cbf8da217d291d3cfa417a42c478e87c5678e9dc47be6e33cde41c |
|
MD5 | 7e5d4ad750d429f97f07c64ed8608b1e |
|
BLAKE2b-256 | e8155a068440914b99cddc5fdccaf99e9849f59184cc3d37a7f27232469c1a50 |
Hashes for silver_platter-0.5.25-cp311-cp311-macosx_11_0_arm64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a70b0880b2914e890138d8ae17fc5f2bf270f61e447dc487a7a070a785190283 |
|
MD5 | b5f6b5dc40bc2acdf6d6ee6b78730cd4 |
|
BLAKE2b-256 | 4dfb1d07fcb33f0d9b4f25e1ea16b2db245749d4eb2e9ab4fd76f6d6aeb15122 |
Hashes for silver_platter-0.5.25-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ef6bbe780306719a2298a7c7d01095585bc9c69661366ca05887099eaf7c3521 |
|
MD5 | fb285260373ff73bdf74c18a61d6096b |
|
BLAKE2b-256 | cf877eb8bab34efc98717f008171129c8ade150026abee68686c1520de1ecffd |
Hashes for silver_platter-0.5.25-cp310-cp310-manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | fa1284fe47f78c4c17958184da2554589908e095467d4daa2b1f7690924fa982 |
|
MD5 | 9432a06c64bf074340545a4ae0ec8b4b |
|
BLAKE2b-256 | 3c544ee36ee48af227f4acfdcbb7a02f83d0b3db01289354bbc3fc9640c1fc20 |
Hashes for silver_platter-0.5.25-cp310-cp310-macosx_11_0_arm64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 708eecf084e2c9b15bcccfbdcf3ac2c06105509a1bede08ec0e2e46328f4b463 |
|
MD5 | 0df2ccc2b3a4f7e8aa0570e568f7e746 |
|
BLAKE2b-256 | dfa48c403f8f067ebb4babf46e41c9915544f82cf7a6ec946da15d58e60de955 |
Hashes for silver_platter-0.5.25-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c0e90df000268efc696fe275929a49a1ecdac9fed90983be5855857319d4f5bf |
|
MD5 | 047885d229386f0201c8b3fe47856c07 |
|
BLAKE2b-256 | ab8ad0bf5a1fd315b505bb96da6741b21b7523d1da7a728155537b49ee3cb3f8 |
Hashes for silver_platter-0.5.25-cp39-cp39-manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 81c4e6062dff11918e45b5f30149796c10335385725f514a696976ec79d1ef2f |
|
MD5 | a2e3af8a8c1c8e620f5e013854ae3496 |
|
BLAKE2b-256 | c5f8000b254c0711cb76503a4ba29bc204bad3c9bf9cb2d2234e33a6c2cf6175 |
Hashes for silver_platter-0.5.25-cp39-cp39-macosx_11_0_arm64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7ebf33127a0999416decc54154e6d73f7f85950b0802041d18daf2aaad96ff75 |
|
MD5 | 6937910bd8274fe702f0eb3940f9aa88 |
|
BLAKE2b-256 | e37d0eb26e385ac6d26b6a9ea77dec9c7fcce1d284d7704dbd21cd8dd5b95c21 |
Hashes for silver_platter-0.5.25-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e1f434684e1a45b294d15e5c8cd572f875dc4ce33eecbd31d357c25ac7e10357 |
|
MD5 | 4a5b6b44919ad362b23bd1d0bf1502ca |
|
BLAKE2b-256 | ac2d621018c94736c2e98726fa60f1a42abf33184823d9f8ac26442efaf18e8e |
Hashes for silver_platter-0.5.25-cp38-cp38-manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a1c4202a4d6bfcdcb15f18c3aea47a2a13dad5c23c8b9767c1e1f1a9895662d8 |
|
MD5 | 33393bc700c57736c56a57a23efff703 |
|
BLAKE2b-256 | 6e42b68adcedbc19893c936de4a9934524ffc2eef17afd0f00651e65ab3e4774 |
Hashes for silver_platter-0.5.25-cp38-cp38-macosx_11_0_arm64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4b9007a4a6f4de508a9478b76f0892918ecfa87ca77a4aa5ecae68d0b763ed6a |
|
MD5 | e7f76db910ab46df90642558132cc1e4 |
|
BLAKE2b-256 | 94105bfee16cab04169abdf2e246d07496bf72bef73b299d9e70375423936308 |
Hashes for silver_platter-0.5.25-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4d6e00cc0a3c0d76c4f0f2c059cbb814d039677e3793995f84124676f17a7056 |
|
MD5 | 7f55ecb825b8c4a00fea0419f176c1a5 |
|
BLAKE2b-256 | 8e1d662cfaa701196ee68f63fa1c093f7a619281bd6cd61892f20fd844c92c6b |
Hashes for silver_platter-0.5.25-cp37-cp37m-manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4e8d8e03e9ba403ebe70028276c4b0f3534cf3e1431280941d2d9e0263dd3335 |
|
MD5 | 1846199f43e7805a701f7eeccd8c080a |
|
BLAKE2b-256 | 0d4a8b1f4eb16f5f243518299ecf10a390de0eb4830ad5465e4e316591460a5f |