doc: add patching script documentation (#1051)

Co-authored-by: Joe Sepi <[email protected]>

Author: anonrig

conduct/COC_PATCHING_SCRIPT.md

@@ -0,0 +1,102 @@
+# Code of Conduct Patching Script
+
+This document explains the knowledge behind the patching script used
+to make any changes on the `CODE_OF_CONDUCT.md` file.
+
+The patching script lives under
+[pkgjs/patch-my-code-of-conduct][project-link] repository.
+It is developed as a GitHub workflow to make it easier for projects
+to adopt into their existing repositories.
+
+## Goal
+
+The goal of the patching script is to make Code of Conduct upgrade
+and review process easier to maintain for open-source projects.
+It removes any direct changes done to the original document, and
+provides an easier to review and accept changes to the document
+provided by the Contributor Covenant.
+
+## GitHub Workflow configuration
+
+The configuration file for the patching script lives inside
+`.github/workflows/patch-code-of-conduct.yml` file. The configuration
+file also includes an additional GitHub workflow to automatically
+open a pull request in the event of a changed file after the
+work of the patching scripts job is complete.
+
+### Settings
+
+- `base_url`: Base URL is the path to the preamble file (the file
+  that is prepended to the Code of Conduct document).
+- `template_url`: It is the URL to the Contributor Covenant website
+  that includes the original unchanged document.
+- `patch_file_path`: It is the path to the patching file.
+- `output_file_path`: It is the path to the file where the changes
+  should apply to. 
+
+### Files
+
+- `workflows/patch-code-of-conduct.yml`: This file contains
+  the necessary configuration to setup the patching script.
+- `CODE_OF_CONDUCT_PREAMBLE.md`: This file contains the text
+  prepended to the original Code of Conduct file. It may contain
+  project/organization specific information that may live outside
+  of the definition of the original Code of Conduct versions.
+- `CODE_OF_CONDUCT_PATCH.patch`: This file contains a patch
+  generated by the contributors of the project to update **only**
+  the texts defined in the Code of Conduct URL defined by the
+  patching script.
+
+## Workflows
+
+### Make a change to `PREAMBLE.md` file
+
+1. Open a pull-request updating either `CODE_OF_CONDUCT_PATCH.patch`
+   or `CODE_OF_CONDUCT_PREAMBLE.md` file. The default procedures of
+   merging a pull request will be followed as usual.
+2. Upon successful merging the proposed changes to the main branch
+   patching script will open a pull request with a target of `main`
+   branch updating `CODE_OF_CONDUCT.md` file with the proposed changes.
+3. Since the approval for the original change is done in step 1, unless
+   there is a bug with the CoC patching script this pull request opened
+   by the bot from the workflow should land without issue.
+
+### Make a change to `PATCH.patch` file
+
+1. Copy the original file and rename it as `PREVIOUS_COC.md`
+2. Update `PREVIOUS_COC.md` according to your needs.
+3. Run the following command to generate the patching file:
+   `diff -Naur PREVIOUS_COC.md CODE_OF_CONDUCT.md > conduct/artifacts/CODE_OF_CONDUCT_PATCH.patch`
+4. Delete the temporary `PREVIOUS_COC.md` file.
+5. Push your changes to a new branch and open a pull-request with a target
+   of `main` branch.
+
+**Testing**: You can run the following command to apply the changes of
+your patching script to validate the output:
+
+```
+patch -i conduct/artifacts/CODE_OF_CONDUCT_PATCH.patch CODE_OF_CONDUCT.md --no-backup-if-mismatch
+```
+
+### Update Code of Conduct version
+
+1. Update Github Workflow `template_url` attribute.
+2. Regenerate your patching file by following the patch file workflow.
+
+## Recommendations
+
+1. In order to decrease the maintenance cost of the updating
+   Code of Conduct, it is recommended to use the correct CoC version
+   in the GitHub workflow configuration.
+2. It is recommended to create a pull request for the changes made
+   by the patching script to avoid committing changes. Remember that,
+   this should be dealt with an extremely delecate process due to the
+   probability of the concerns mentioned in recommendation 3.
+3. The pull requests opened by the patching script bot should be approved
+   without issue. Modifying the PR created from the workflow would put
+   our code in an ambiguous state where the `CODE_OF_CONDUCT.md` file and
+   the files that the script depend on do not match with each other.
+   All changes should happen in the files outlined above and resulting PRs
+   should remain unmodified.
+
+[project-link]: https://github.com/pkgjs/patch-my-code-of-conduct