diff --git a/docs/PROCEDURES.md b/docs/PROCEDURES.md index 639871ce7..2387fa288 100644 --- a/docs/PROCEDURES.md +++ b/docs/PROCEDURES.md @@ -8,36 +8,31 @@ dependencies they use: * to ensure reproducibility * to reduce the risk for rogue dependency updates to compromise software -It's important to note that this requires any changes to dependencies are properly review, and +It's important to note that this requires any changes to dependencies are properly reviewed, and these changes, by design, should not be automatic in themselves, though automated tools may provide recommendations. ### Python dependencies -Python dependencies used in the build process should be pinned to a specific version to ensure reproducibility. +Python dependencies used in the build process such as within `.github/workflows` should be pinned to a specific version to ensure reproducibility. -This is done by: - * Using the `--require-hashes` option on any `pip install` command line - * Adding the required hash in the `requirements.txt` +This is achieved by: - Currently this is used within `.github/workflows` but the same principle applies elsewhere. +* Ensuring the required hash is in the `requirements.txt`. +* Using the `--require-hashes` option on any `pip install` command line which causes pip to require hashes for all dependencies. - To make this easier, a version of the `requirements.txt` without hashes has been saved as `requirements.in`. This is - to make maintenance easier, but it is not used at script execution time. +To add a new, or changed dependency: - The `pip-compile` tool must be installed via the [pip-tools](https://pypi.org/project/pip-tools/) package. - - To add a new, or changed dependency: - ``` - pip-compile --generate-hashes --output-file=requirements.txt requirements.in - ``` +* Ensure the `pip-compile` tool is installed via the [pip-tools](https://pypi.org/project/pip-tools/) package. +* Update `requirements.in` with added, modified, or deleted dependencies. +* Update requirements.txt using `pip-compile --generate-hashes --output-file=requirements.txt requirements.in`. +* Verify correct functionality. +* Check in both `requirements.txt` and `requirements.in`. - This will update requirements.txt with the correct hashes. - - Correct functionality should be verified, and then both `requirements.txt` and `requirements.in` checked in. + Note: `requirements.in` acts purely as a template in this process. It is not used during the installation of a dependency. ### Github Actions -All actions used in `.github/worfklows' should pin the exact version of the action they are using, for +All actions used in `.github/worfklows` should pin the exact version of the action they are using, for example a step such as: ```yaml @@ -54,10 +49,12 @@ by, for example, running: pin-github-action unix.yml ``` -This will add the appropriate hash if not present, and also update each hash in accordance with the comment. +This will add the appropriate hash if not present, along with a comment, and also update each hash in accordance with any existing comment. For major updates, update the comment ie `pin@v4` to `pin@v5` and the tool will attempt to find the new hash. +The comment should not be removed, and should exclusively be used for updating the version. + A full explanation of how the tool operates can be found in the [documentation](https://github.com/mheap/pin-github-action). To help in explanation here's an example of a similar code fragment between tool executions: