diff --git a/docs/operations/git/undo_stable_pr.md b/docs/operations/git/undo_stable_pr.md new file mode 100644 index 00000000..d0b42f28 --- /dev/null +++ b/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 `. +- 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. diff --git a/docs/operations/libraries/workflow_alpha_release.md b/docs/operations/libraries/workflow_alpha_release.md new file mode 100644 index 00000000..37405524 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/operations/libraries/workflow_review_alpha.md b/docs/operations/libraries/workflow_review_alpha.md new file mode 100644 index 00000000..5a5457a5 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/operations/libraries/workflow_review_stable.md b/docs/operations/libraries/workflow_review_stable.md new file mode 100644 index 00000000..23bff911 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/operations/libraries/workflow_stable_release.md b/docs/operations/libraries/workflow_stable_release.md new file mode 100644 index 00000000..fb427589 --- /dev/null +++ b/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. diff --git a/docs/overview/definitions.md b/docs/overview/definitions.md index 8fdf87dd..3fb82812 100644 --- a/docs/overview/definitions.md +++ b/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 diff --git a/mkdocs.yml b/mkdocs.yml index 8e4d35ea..641b2d64 100644 --- a/mkdocs.yml +++ b/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 \ No newline at end of file + - 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 \ No newline at end of file