Merge pull request #43 from edx/robrap/ARCHBOM-1387-ADR-config-and-tools

ARCHBOM-1387: ADR for config-and-tools

CHANGELOG.rst

@@ -14,7 +14,7 @@ Change Log
 Unreleased
 ~~~~~~~~~~
 
-*
+* Add ADR 0001-config-and-tools.rst for adding a placing in this repository for shared annotation configs and supporting tools.
 
 [0.4.0] - 2020-07-22
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

README.rst

@@ -15,6 +15,8 @@ annotating code which stores personally identifiable information (PII), these
 tools are optimized for that use case but can be generalized for other types of
 annotations.
 
+Additionally, a logically separate part of this repository will contain specific annotation configurations and supporting tools, such as Sphinx extensions for documenting specific annotation types. See ``config_and_tools``.
+
 Documentation
 -------------
 

config_and_tools/README.rst

@@ -0,0 +1,8 @@
+config and tools
+================
+
+This directory will contain annotation configurations that can be shared across repositories, as well as shared tools based on these configurations, such as Sphinx extensions that can be used to document certain types of annotations.
+
+These custom configurations should be kept separate from the general annotations tool in /code_annotations.
+
+For more details, see the ADR in docs/decisions/0001-config-and-tools.rst.

docs/decisions/0001-config-and-tools.rst

@@ -0,0 +1,33 @@
+Annotations Config and Tools
+****************************
+
+Status
+======
+
+Accepted
+
+Context
+=======
+
+While working on a particular usage of this general code annotations tool, we found we did not have a good home for some shared configs and tools.
+
+The original usage of this generic tool was for annotating PII in the Open edX platform. The config for `PII annotations`_ is currently duplicated in each repository.
+
+The new instances of annotation configs arose to support documenting Open edX feature toggles and non-toggle settings. Each of these will also have Sphinx extensions to support documentation. To start, the `feature toggles annotation config`_ was added to the ``edx-toggles`` repository, but there was no good home for the non-toggle settings annotation config, nor the documentation tools.
+
+.. _PII annotations: https://github.com/edx/edx-cookiecutters/blob/7cf718093e7cca5c701a29fcbaa84660326b09ed/cookiecutter-django-app/%7B%7Bcookiecutter.repo_name%7D%7D/.pii_annotations.yml
+.. _feature toggles annotation config: https://github.com/edx/edx-toggles/blob/0986b10a806944fd4d00847501ff4f7e3904a2cb/feature_toggle_annotations.yaml
+
+Decision
+========
+
+The code annotation tool is generic and specific annotation configs are logically separate. At the same time, it was decided that having a single place for annotation configs and there supporting tools would be efficient for our engineers, as well as potentially beneficial for sharing outside of Open edX. Additionally, we decided not to add the overhead of managing a separate repository at this time. Instead, we will add a ``config_and_tools`` directory in this repository to contain any shared annotation config files and supporting tools.
+
+It is acknowledged that this need not be a permanent solution, but is a useful place to begin.
+
+Any affect on how the PII annotations are implemented, or where they are stored, is outside the scope of this decision.
+
+Consequences
+============
+
+We will move the new toggles annotations and its supporting tools to the new ``config_and_tools`` directory.

tox.ini

@@ -2,7 +2,8 @@
 envlist = py35-django22, py38-django{22,30}
 
 [doc8]
-max-line-length = 120
+; D001 = Line too long
+ignore=D001
 
 [pycodestyle]
 exclude = .git,.tox