#1706 scorecard - address review comments in docs

Signed-off-by: Nigel Jones <[email protected]>

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: