Merge branch 'main' of github.com:wayfair-incubator/gator

README.md

@@ -1,2 +1,45 @@
-# gator
-Propagator CLI + Package
+# About Gator
+
+Gator is short for "change propagator", and can be used to make changes across multiple Github repositories at once.
+
+The entrypoint will be a dockerized CLI and a python package.
+
+You will give Gator an imperative yaml spec file, and some repos to process. Gator will create PRs or Issues in Github according to the spec. The CLI will allow you to test your specs locally, making sure that the code changes look as you expect before PRs are created.
+
+If the reusable code modifications do not suffice, you will be able to make changes to code programatically, and use Gator to automate the git aspects, and assist you with testing. An example `Changeset` specification will look like this:
+
+```yaml
+kind: Changeset
+version: v1alpha
+spec:
+  name: Docker image registry migration
+  issue_title: Replace all usages of outdated Docker image registry URL with new URL
+  issue_body: |
+      # Artifactory Has Moved
+      
+      ... Some text to be included in the PR or issue body.
+  filters:
+      - kind: RegexFilter
+        version: v1alpha
+        spec:
+          regex: 'registry.company.com'
+          paths:
+            - definitions/application_spec.yml
+  code_changes:
+      - kind: RegexReplaceCodeChange
+        version: v1alpha
+        spec:
+          replacement_details:
+            - regex: 'registry.company.com'
+              replace_term: "registry.parent-company.com"
+              paths:
+                - definitions/application_spec.yml
+```
+
+# Development Status
+
+Gator has not reached Minimum Viable Product status yet, but is actively in development as of early 2022.
+
+# Contributing
+
+If you're interested in contributing, please check out the CONTRIBUTING.md file at repo root.

gator/constants.py

@@ -1,12 +1,5 @@
 import re
 
-# Resource Values
-RESOURCE_KIND_GENERIC = "GenericResource"
-RESOURCE_VERSION_UNUSABLE = "Unusable"
-
-
 DEFAULT_REGEX_MODES = re.MULTILINE
-
 GIT_INTERNALS_DIRECTORY = ".git"
-
 VERSION_V1_ALPHA = "v1alpha"

gator/resources/build.py

@@ -26,7 +26,13 @@
 
 
 class _ResourceWithValidation(GatorResource):
-    """Define a subclass of Gator Resource that tricks"""
+    """
+    Define a subclass of Gator Resource for Pydantic deserialization purposes.
+
+    This subclass uses Pydantic validators to look up the classes associated
+    with given resource names in a registry, allowing deserialization of
+    resources not present in the registry at import time (Custom Resources).
+    """
 
     @classmethod
     def __get_validators__(cls):
@@ -45,6 +51,7 @@ def return_kind(cls, values):
 
 
 class ChangesetSpecV1AlphaSpec(BaseModelForbidExtra):
+    """Changeset Specification."""
     name: str
     issue_title: Optional[str]
     issue_body: Optional[str]
@@ -53,6 +60,7 @@ class ChangesetSpecV1AlphaSpec(BaseModelForbidExtra):
 
 
 class Changeset(BaseModelForbidExtra):
+    """Define Changeset."""
     kind = "Changeset"
     version = "v1alpha"
     spec: ChangesetSpecV1AlphaSpec
@@ -107,7 +115,7 @@ def register_custom_resource(resource_class: Type) -> None:
     """
     Register a custom Gator resource.
 
-    Use this function to register a custom resource with Gator. This
+    Use this function to register a custom resource with Gator.
     :param resource_class: Pydantic class, extending CodeChangeResource or FilterResource,
         that contains the business logic for executing the resource
     """