1  # rust-maint-common - maintenance scripts for Rust projects
 2  
 3  This repo contains a number of scripts and utilities
 4  which are particularly useful for projects written in Rust,
 5  especially if using (gitlab) CI.
 6  
 7  ## Functionality and configuration
 8  
 9  Each script has its own documentation, typically in its head comment.
10  
11  Scripts will typically be driven by normal in-tree metadata
12  such as `Cargo.toml`.
13  
14  In some cases the scripts may
15  read files in `maint/` for configuration,
16  or execute scripts in `maint/`
17  (possibly scripts that also exist in this repo,
18  in which case you should make a suitable symlink - see below.)
19  
20  ## How to incorporate this into your project
21  
22  The repo is designed to be merged into your history 
23  using `git subtree`.
24  
25  It is good practice to merge it under its full name,
26  and to commit a symlink through which you make all references.
27  This will allow a downstream to replace the embedded copy,
28  with a reference to a shared copy.
29  
30  ```
31  git subtree add -P maint/rust-maint-common https://gitlab.torproject.org/tpo/core/rust-maint-common main
32  ln -s rust-maint-common main maint/common
33  ```
34  
35  Then, you can use scripts directly like this:
36  
37  ```
38  maint/common/check-blocking-todos
39  ```
40  
41  Or, you make another symlink like this
42  (which will make it easier to diverge, if you want to):
43  
44  ```
45  ln -s common/check-blocking-todos maint/
46  maint/common/check-blocking-todos
47  ```
48  
49  You can update to a new version of `rust-maint-common`
50  with `git subtree pull` or `git subtree merge`.
51  
52  ## Invocation
53  
54  The script are designed to be invoked from your toplevel,
55  as `maint/name-of-script` or `maint/common/name-of-script`.
56  
57  They will assume that `maint/common/` is this tree
58  (as recommended above).
59  
60  ## Security considerations
61  
62  These scripts can be configured by files found
63  relative to the current directory,
64  and they can execute other scripts from this package,
65  hoping to find them via relative paths.
66  
67  These scripts are not safe to run in an untrusted cwd.
68  They must not be put on `PATH`.
69  
70  ## Making changes
71  
72  You should try to make only changes which would be
73  suitable for all users of these scripts.
74  But you may make them in the same commits
75  as you change other parts of your tree.
76  
77  After you have made changes and are satisfied with them,
78  you should use `git subtree split` or `git subtree push`
79  to split off the changes you have made,
80  into a branch of (a fork of) this repo.
81  Then you can make a Merge Request for your changes.
82  
83  ## Copyright and licence
84  
85  Copyright The Tor Project, Inc, and contributors.
86  
87  This whole repository is Free Software.
88  You may share and modify under the terms of the MIT License
89  or the Apache License version 2.0.
90  
91  SPDX-License-Identifier: MIT OR Apache-2.0