Linter code and workflow for SOPs

[M-casado]

Summary

I created a python script sop-linter.py that contains the set of rules for linting of SOPs. These rules include things like having required sections, or the format of some tables. Given that linting rules in the script are each a method, it's easy to add/modify them at any given time. The script can be run by anyone manually, prior to creating a PR, to see if SOPs pass the validation:

# With test SOPs:
python scripts/sop-linter.py tests/ -v 1

# With all real SOPs in the repo:
python scripts/sop-linter.py sops/ -v 1

I also created a GitHub workflow lint-sops.yml that triggers at any PR targeting main or dev branches in the repository. The workflow executes the linting SOP, and will be an easy check on whether new SOPs follow format/content rules we specify in the sop-linter.py script. When executed, its visual tag (❌ or ✔️ ) will quickly raise possible issues with the format of SOPs that are being added to the project.

Types of changes

• [ ] Bug fix (non-breaking change which fixes an issue)
• [x] New content (non-breaking change which adds new content)
• [ ] Modified content (non-breaking change which modifies existing content)
• [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)

Motivation and Context

In order to add SOPs quickly to the repository, by multiple contributors, and still maintain some structure, these automatic workflows are required. With this addition, we will be able to raise possible issues at source, and keep harmony across SOPs.

References

ZenHub #268

Changes Introduced

• Added python script scripts/sop-linter.py to lint SOP documents
• Added workflow .github/workflows/lint-sops.yml to automatically trigger the linting script
• Added test file(s) at tests/
• Added requirements.txt for running code

Review

Not yet

Additional Notes

Both the code and the workflow were tested in my fork of the GDI repository (see testing PR).

This is how it will look like when we add SOPs to the repo at dev or main through PRs:

As the name implies, we should have it as a requirement to have the linter pass all checks (✔️ ) for an SOP to be added to the repo.

Checklist:

General Compliance:

• [x] My changes follow the code style of this project (GDI SOP Style Guide) and the file naming conventions of the file accessioning proposal.
• [x] I have verified that all new updated content is accessible, including checking that all external references are readable (i.e., no broken links). These may include references to external resources that should be resolvable, and internal references among SOPs.
• [x] I have properly added this PR's changes to the repository CHANGELOG.md.

Only applicable if the PR includes new, or changes to, GDI SOPs (i.e., documents at sops/):

• [ ] My SOP-related changes adhere to the Generic SOP Template, including format and required fields.
• [ ] I have consulted the Charter, ISM, and ORR documents to ensure compliance.
• [ ] I am complying with the established procedure for SOP creations and modifications, including respecting review phases and notifying needed contributors for reviews.

[M-casado]

SOP Index table

I created and tested (see PR) new code in order to:

• Create the SOP index table that, in the future, will contain all SOPs present in the GH repository
• Compare the existing SOP index table with a newly created one (in order to check if it's up to date)
• Assert that this SOP index table is up-to-date in every PR to dev or main, via a workflow

Again, this code is simply to automate manual checks that in the future, when reviews are due and we're adding new SOPs, we don't want to do manually. Therefore, in this PR we have both code that lints SOPs and code that automatically creates the content table with all SOPs and their information.

Information that is present in the SOP index table (which is empty for now since we don't have any SOP public yet) can be easily modified, adding or removing columns at will. I chose the following format based on what I believe would be useful for users (i.e., GDI members) searching for GDI SOPs:	Name	Identifier	Template version	Type	GDI Node	Instance version	Nº steps	Last modified

[elisavettorstensson]

Unfortunately, I don't have so much technical background to review this PR. However, I believe that the idea behind the use of the code to make more automated checks (and reviews) in the future is very good!

[M-casado]

No worries, @elisavettorstensson - The key is also to have all of us informed about the non-technical flag that if there is a ❌ in a PR, it may need to be checked before merging.

The code itself will need to be maintained, and I can do for as long as I am part of the task. Others may want to contribute to it as well, in a technical (directly adding to it) or non-technical (letting me know of desired changes) way. If you're in the latter, and you feel like some checks/actions would be great to automate for this GH, feel free to raise them in the fortnightly meetings :)

[M-casado]

I'm hoping in the future to add more checks as well. There are many things that we could automate instead of having to check manually. Examples could be:

• Grammar checks (are there spelling/grammar mistakes in the SOPs)
• Acronyms checks (are all used acronyms in the Charter's glossary)
• Has an SOP not been reviewed/updated for a long time? ...

[M-casado]

Went over the code goals and features at today's meeting.