Document "library" project workflows for releases and reviews (#41)

* Document "library" project workflows for releases and reviews
Add definitions for devops workflow docs

* Fix punctuation

Co-authored-by: Mike <mike@graywind.org>

* More complete list of Skill base classes

Co-authored-by: Mike <mike@graywind.org>

* Address review feedback

* Update alpha release process to address permissions to request a review

* Add note to `service` definition with an example

---------

Co-authored-by: Daniel McKnight <daniel@neon.ai>
Co-authored-by: Mike <mike@graywind.org>

docs/operations/git/undo_stable_pr.md

@@ -0,0 +1,21 @@
+## Undo a Stable PR Workflow
+This describes the process for undoing stable release automation on the `dev`
+branch of a repository.
+
+### Application
+This process applies in the following situations:
+- It is dictated by a review workflow to make changes to a proposed stable release.
+- A release workflow is run in error.
+> This process must be completed by a repository administrator.
+
+### Process
+- Checkout the `dev` branch of the affected repository.
+- Find the commit prior to the stable release automation.
+  > This is usually an automatic commit `Update Changelog` or `Increment Version to <version>`.
+- Force reset your local `dev` branch to the identified commit.
+- Force push your local `dev` branch to the remote.
+  > This will require administrator permissions
+- Validate the remote repository is at the expected commit.
+
+### Exceptions
+- There should be no exceptions to this process.

docs/operations/libraries/workflow_alpha_release.md

@@ -0,0 +1,28 @@
+## Alpha Release Workflow
+This describes the process for pushing an alpha release for a `library` module.
+A `library` module is a module or repository that is a dependency of one or more
+Neon `services` or `plugins`.
+
+### Application
+This process applies when making any change to a `library` module.
+
+### Process
+- Create a branch from the `dev` branch of the module.
+- Complete any changes, including test coverage, documentation updates, and
+  dependency changes.
+- Create a Pull Request to the `dev` branch.
+  > Ensure the PR title is descriptive and the template is completed. A description
+    is required and relevant issues must be noted as either related to the PR or
+    closed by the PR.
+- If any tests fail, mark the Pull Request as a Draft and make necessary changes. 
+  > After tests are passing, mark it ready for review here.
+- If permissions allow, request a review from a maintainer. If you are unable to
+  request a review and have discussed changes with a maintainer, tag them in a
+  comment.
+- Upon approving review, `Squash and Merge` changes to the `dev` branch
+
+### Exceptions
+- A maintaining developer may choose at their discretion to skip the review process if
+  tests are passing and there is not another developer qualified and available to review.
+  > If there is no code coverage automation, the maintaining developer is responsible
+    for ensuring coverage for any changes.

docs/operations/libraries/workflow_review_alpha.md

@@ -0,0 +1,30 @@
+## Library Module Alpha PR Review Workflow
+This describes the process for reviewing a PR to a `library` module `dev` branch.
+
+### Application
+This process applies when reviewing a PR to the `dev` branch of a `library` module.
+
+### Process
+- Complete the following. Note any issues in Review Comments before leaving a 
+  review to `Request Changes`. If there are no comments or the comments do not
+  require code changes, then you *may* `Approve` the PR.
+  - Review changes to imports and verify dependency minimum versions are accurate.
+  - Ensure code changes have adequate unit test coverage.
+  - Ensure there are no breaking changes.
+  - If changes replace or could replace an existing method, ensure a deprecation 
+    warning is logged in the replaced method (either `deprecated` decorator or
+    `log_deprecation` call).
+  - If tests are modified, make sure newly deprecated methods are still tested and
+    that changes do not remove any test cases.
+  - Highlight any added `TODO` or existing `TODO` comments related to the changes.
+    >   It is up to the PR author and reviewer to decide if a `TODO` must be completed
+      before merging OR if an issue can be created to address it in a later PR.
+
+- Ensure the PR title and body are completed. Make any revisions necessary or
+  work with the PR author to make those changes.
+- Leave a review to `Approve` or `Request Changes`. If reviewing a draft or if 
+  unable to test changes, leave a `Comment` review indicating why it isn't an 
+  Approval, i.e. "Unable to test." or "Noted pending TODO"
+
+### Exceptions
+- There should be no exceptions to this review process.

docs/operations/libraries/workflow_review_stable.md

@@ -0,0 +1,28 @@
+## Library Module PR Review Workflow
+This describes the process for reviewing a PR to a `library` module.
+
+### Application
+This process applies when reviewing a PR to the `dev` branch of a `library` module.
+
+### Process
+- Review changes to imports and verify dependency minimum versions are accurate.
+- Ensure there are no alpha dependencies
+- Ensure code changes have adequate unit test coverage.
+- Ensure any deprecated methods have adequate logs.
+- Ensure there are no breaking changes.
+  > If this is a major release, then there may be breaking changes. If there are,
+    then ensure the previous releases had a deprecation warning with this
+    proposed release version listed.
+- If tests are modified, make sure newly deprecated methods are still tested and
+  that changes do not remove any test cases/
+- Ensure any added `TODO` items have not been completed and are related to an 
+  open issue.
+- Leave a review to `Approve` or `Request Changes`. If reviewing a draft or if 
+  unable to test changes, leave a `Comment` review indicating why it isn't an 
+  Approval, i.e. "Unable to test." or "Noted pending TODO"
+
+### Exceptions
+- A maintaining developer may choose at their discretion to allow a pinned alpha
+  dependency for a stable release if the pinned version has been adequately 
+  tested, and it is unreasonable or impossible to use a stable release for the
+  dependency.

docs/operations/libraries/workflow_stable_release.md

@@ -0,0 +1,43 @@
+## Library Release Workflow
+This describes the process for pushing a `library` module release.
+
+### Application
+This process applies when pushing a stable release for a `library`.
+
+### Process
+- Verify the current alpha version is used in any projects that depend on the
+  proposed changes.
+- Compare the latest alpha release to the latest stable release to determine the `release type`:
+  - If any breaking changes are present, the next version will be a `major` release.
+  - If any non-breaking functional changes are present, the next version will be a `minor` release.
+  - If no functional changes are present (i.e. only bugfixes or optimizations), the next version
+    will be a `patch` release.
+- If this is a `major` release:
+  - Ensure that any deprecated methods had deprecation warnings in the previous 
+    stable release.
+    > If they did not, create a PR to replace the removed methods and add a 
+      deprecation warning and start this process over.
+  - Ensure that anything marked for deprecation in this release has been removed.
+    > If there is code marked for deprecation in this release, create a PR to 
+      remove the relevant code and unit tests and start this process over.
+- Look at package requirements to verify there are no alpha dependencies.
+  > If there are any alpha dependencies, create an alpha release with no alpha dependencies and
+    start this process over.
+- Run the `Propose Stable Release` workflow with the determined `release type`.
+- Upon workflow completion, review the generated PR.
+  > The PR may need to be closed and re-opened to trigger automation.
+- Review the PR as normal and request a review from another developer.
+- Upon approval, `Create a Merge Commit` to create the stable release.
+  > If changes are required, a maintaining developer is responsible for closing the PR
+    and [reverting changes on the `dev` branch](https://neongeckocom.github.io/neon-docs/operations/git/undo_stable_pr/).
+    After this is completed, a PR to `dev` should be created, referencing the PR where
+    changes were requested.
+### Exceptions
+- A maintaining developer may choose at their discretion to allow alpha dependencies in 
+  optional extras, i.e. test dependencies.
+- A maintaining developer may choose at their discretion to allow a pinned alpha
+  dependency for a stable release if the pinned version has been adequately 
+  tested, and it is unreasonable or impossible to use a stable release for the
+  dependency.
+- A maintaining developer may choose at their discretion to not request another review if
+  tests are passing and there is not another developer qualified and available to review.

docs/overview/definitions.md

@@ -35,6 +35,31 @@ Commandline Application for interacting with services on the MQ Bus.
 More information is available 
 [on Github](https://neongeckocom.github.io/neon-docs/neon_core/index).
 
+## Operations Documentation
+The Operations Documentation and other documents discussing code organization or
+processes use some specific terms to refer to different kinds of modules.
+
+### Plugin
+Refers to a module that may be replaced by an equivalent module. These will usually 
+extend a class from [ovos-plugin-manager](https://github.com/openvoiceos/ovos-plugin-manager).
+
+### Skill
+Refers to a class that extends `MycroftSkill`, `OVOSSkill`, or `NeonSkill`. A `skill` is a subset of a `plugin`.
+For the purposes of the operations documentation, a skill is distinctly different
+from a plugin.
+
+### Service
+Refers to a module that runs as a standalone service. This often includes a Docker
+container that runs the service. Many plugins may be run as a standalone service,
+but for the purposes of the operations documentation those are considered plugins
+and not services.
+> For example, `neon-audio` is a service but `neon-tts-plugin-coqui` is not. Even
+  though the plugin has a container with a web UI, it is a TTS plugin first.
+
+### Library
+Refers to Python packages that do not expose any services or implement a specific
+plugin. These are often dependencies of many plugins and services.
+
 ## Neon (and OVOS and Mycroft) Core
 Some commonly used terms in the context of Neon (and other) Cores. See also
 the [OVOS Docs](https://openvoiceos.github.io/community-docs/glossary/) and

mkdocs.yml

@@ -95,4 +95,11 @@ nav:
       - Neon OS:
           - Stable Release Workflow: operations/neon_os/workflow_stable_release.md
           - Beta Release Workflow: operations/neon_os/workflow_beta_release.md
-          - Remove a Release Workflow: operations/neon_os/workflow_remove_release.md
+          - Remove a Release Workflow: operations/neon_os/workflow_remove_release.md
+      - Library Modules:
+          - Stable Release Workflow: operations/libraries/workflow_stable_release.md
+          - Alpha Release Workflow: operations/libraries/workflow_alpha_release.md
+          - Stable Release Review Workflow: operations/libraries/workflow_review_stable.md
+          - Alpha Release Review Workflow: operations/libraries/workflow_review_alpha.md
+      - Git:
+          - Undo a Stable PR Workflow: operations/git/undo_stable_pr.md