Merge pull request #537 from openedx/feanil/improve_docs

Add exceptions to the EnsureWorkflows check + Docs Update

edx_repo_tools/repo_checks/README.rst

@@ -1,7 +1,7 @@
 Repo Checks
 ###########
 
-This is a tool & a lightweight framework for automating administrative tasks through GitHub's API. 
+This is a tool & a lightweight framework for automating administrative tasks through GitHub's API.
 
 These checks are generally written by Axim engineers to help us to help us establish some consistency across the plethora of repositories under the `openedx GitHub organization <https://github.com/openedx>`_, although they theoretically could be applied to any GitHub organization.
 
@@ -49,14 +49,24 @@ Finally, when you're ready, you can actually apply the fixes to GitHub::
 
 Note this will open pull requests in the relevant repos. Some repos intentionally don't have certain workflows (for example, ``docs.openedx.org`` does not use ``commitlint``), so please tag maintainers on the pull requests so they can decide whether or not to use the added or changed workflows.
 
+When running over all repos in an organization, the script runs on the newest repos first as those are the most likely
+to be out of compliance.
+
+A note about rate-limiting, if your run is halted due to rate-limiting, note the last repo that the check was running on
+in the output and restart the job from there once your rate limit has been reset::
+
+    repo_checks ...                                      # original run
+    ...                                                  # rate limiting or other error halts the run
+    repo_checks ... --start-at "<last_repo_in_output>"   # Re run starting from where we halted.
+
 Contributing
 ************
 
 * Make changes on your branch.
 
 * Consider adding `to the test suite <../../tests/test_repo_checks.py>`_ even though it is currently sparse.
 
-* CI will run tests for you, but not linting, so ensure your changes don't break repo_checks' pylint: ``pylint edx_repo_tools/repo_checks``. 
+* CI will run tests for you, but not linting, so ensure your changes don't break repo_checks' pylint: ``pylint edx_repo_tools/repo_checks``.
 
 * Dry-run the script and save the output (non-Axim engineers: you should be able to do this with a read-only GH access token).
 

edx_repo_tools/repo_checks/repo_checks.py

@@ -336,6 +336,13 @@ def __init__(self, api: GhApi, org: str, repo: str):
             "add-remove-label-on-comment.yml",
         ]
 
+        # A lost of repos and workflows that should not be added to them.
+        self.exceptions = {
+            # We don't want commitlint on the docs.openedx.org repo because we want to encourage
+            # contributions from non-technical contributors and reduce their barriar to entry.
+            "docs.openedx.org": ["commitlint.yml"],
+        }
+
         self.branch_name = "repo_checks/ensure_workflows"
 
         self.files_to_create = []
@@ -359,19 +366,37 @@ def check(self):
         default_branch = repo.default_branch
 
         files_that_differ, files_that_are_missing = self._check_branch(default_branch)
+
+        extra_message = "No repo specific workflows to ignore."
+        # Update based on repo specific exceptions
+        if self.repo_name in self.exceptions:
+            extra_message = (
+                "Ignoring repo specific exceptions: {!r}".format(
+                    self.exceptions[self.repo_name]
+                )
+            )
+            # We have exceptions for this repo, remove them from the two lists above.
+            for item in self.exceptions[self.repo_name]:
+                if item in files_that_differ:
+                    files_that_differ.remove(item)
+                if item in files_that_are_missing:
+                    files_that_are_missing.remove(item)
+
         # Return False and save the list of files that need to be updated.
         if files_that_differ or files_that_are_missing:
             self.files_to_create = files_that_are_missing
             self.files_to_update = files_that_differ
             return (
                 False,
                 f"Some workflows in this repo don't match the template.\n"
-                f"\t\t{files_that_differ=}\n\t\t{files_that_are_missing=}",
+                f"\t\t{files_that_differ=}\n\t\t{files_that_are_missing=}\n"
+                f"\t\t{extra_message}",
             )
 
         return (
             True,
-            "All desired workflows are in sync with what's in the .github repo.",
+            "All desired workflows are in sync with what's in the .github repo.\n"
+            f"\t\t{extra_message}",
         )
 
     def _check_branch(self, branch_name) -> tuple[list[str], list[str]]: