Merge pull request #64 from netboxlabs/changes-plugin

Adding changes plugins docs

docs/netbox-extensions/changes/changelog.md

@@ -0,0 +1,5 @@
+# Change Log
+
+## v0.2.0
+
+* Initial release

docs/netbox-extensions/changes/configuration.md

@@ -0,0 +1,9 @@
+# Configuration Parameters
+
+The following plugin configuration parameters are available.
+
+## `protect_main`
+
+Default: False
+
+When enabled, all object creations, changes, and deletions must be made within a branch. Changes to objects in main will not be permitted, except for those object types which do not support branching.

docs/netbox-extensions/changes/index.md

@@ -0,0 +1,38 @@
+# NetBox Change Management
+
+This plugin adds change management support to [NetBox](http://netboxlabs.com/oss/netbox/). Leveraging the [netbox-branching](https://github.com/netboxlabs/netbox-branching) plugin, it implements policy and workflow controls to ensure proposed changes undergo formal review prior to being merged. It also retains a written record of all approved changes.
+
+## Getting Started
+
+### Defining a Policy
+
+Change policies determine who is eligible to approve a change request and how many approvals a change request requires. Each policy contains one or more rules which define these parameters.
+
+Begin by creating a new policy with a name of your choosing, then add however many rules are necessary to enforce your organization's change policy.
+
+For example, suppose your team requires that every change be approved by two engineers (members of the Engineering group in NetBox) and one of the two lead engineers (Alice and Bob). This can be achieved by adding two rules to the policy.
+
+| Rule | Minimum reviews | Reviewer groups | Reviewers  |
+|------|-----------------|-----------------|------------|
+| #1   | 2               | Engineering     | -          |
+| #2   | 1               | -               | Alice, Bob |
+
+This policy will be met only when at least two members of the Engineering group _and_ Alice or Bob submit approvals.
+
+### Create a Change Request
+
+When you've finished staging your changes in a branch, click the "request review" button at the top of the branch view. This will take you to the change request creation form.
+
+Enter a name for your change request (or keep the default value, taken from the branch's name) and select the change policy which applies to your request. Each change request will be opened in "draft" status with medium priority by default, but these can be changed. Go ahead and change the status to "needs review" if it's ready for review now. Finally, provide a brief summary of your changes for reviewers.
+
+### Reviewing a Change Request
+
+Once a change request has been submitted, it can be reviewed by other users. To review a change request, click the "add a review" link above the list of reviews (if any). Select the status of your review and provide any comments you have. Your review will now show up under the change request.
+
+Alternatively, if you'd like to provide more detailed feedback, select the "changes" tab. Here, you can comment on specific changes within the branch and cite any concerns or suggestions you have. Other users can then reply to your comments.
+
+### Applying a Change Request
+
+Once a change request has been approved, the "merge" button will appear. Clicking it will take you to the form to merge the corresponding branch.
+
+Once the branch has been merged successfully, the change request's status will be automatically updated to "completed."

docs/netbox-extensions/changes/models/changerequest.md

@@ -0,0 +1,50 @@
+# Change Requests
+
+A change request is submitted to request approval of proposed changes in a branch before it can be merged. All rules of the assigned [change policy](./policy.md) must be met for the request to be approved. When submitting a change request for a branch, the owner selects the governing policy and designates a priority.
+
+## Fields
+
+### Name
+
+The user-defined name of the change request.
+
+### Owner
+
+The user who submitted the change request.
+
+### Policy
+
+The [policy](./policy.md) which must be met for the change request to be approved.
+
+!!! note
+    The policy is selected by the change request owner.
+
+### Branch
+
+The branch which will be merged when the change request has been approved.
+
+### Status
+
+The current status of the change request. Valid statuses are listed below.
+
+| Status       | Description                                        |
+|--------------|----------------------------------------------------|
+| Draft        | Not yet ready for review                           |
+| Needs review | Waiting for reviews to satisfy the assigned policy |
+| Approved     | The assigned policy has been met                   |
+| Completed    | The assigned branch has been merged                |
+| Rejected     | The proposed changes have been rejected            |
+
+### Priority
+
+The priority of the change request relative to other open requests. Valid priorities are listed below.
+
+* High (5)
+* Medium/high (4)
+* Medium (3)
+* Medium/low (2)
+* Low (1)
+
+### Summary
+
+A short summary of the proposed changes, reasoning for why they are being made, and any other relevant notes for reviewers.

docs/netbox-extensions/changes/models/comment.md

@@ -0,0 +1,25 @@
+# Comments
+
+As part of the review process, users can leave comments on [change requests](./changerequest.md) to ask question or suggest changes. Each comment may start a thread of [replies](./commentreply.md) and can be marked resolved, which will hide the reply thread.
+
+## Fields
+
+### Author
+
+The user who created the comment.
+
+### Change Request
+
+The [change request](./changerequest.md) to which the comment applies.
+
+### Change Diff
+
+The specific change within the change request the comment applies (optional).
+
+### Content
+
+The comment body.
+
+### Resolved
+
+A boolean attribute indicating whether the comment has been addressed by the change request owner.

docs/netbox-extensions/changes/models/commentreply.md

@@ -0,0 +1,17 @@
+# Comment Replies
+
+Each [comment](./comment.md) on a [change request](./changerequest.md) starts a new discussion thread to which users can reply. This helps keep the discussion around a change request organized.
+
+## Fields
+
+### Author
+
+The user who created the reply.
+
+### Comment
+
+The comment to which the reply thread belongs.
+
+### Content
+
+The reply body.

docs/netbox-extensions/changes/models/policy.md

@@ -0,0 +1,12 @@
+# Policies
+
+A policy defines the conditions that must be met for a [change request](./changerequest.md) to be merged. Each policy defines one or more [rules](./policyrule.md) which assert these conditions. All rules must be met for the policy to be satisfied.
+
+!!! note
+    A policy with no rules defined will always fail.
+
+## Fields
+
+### Name
+
+The name by which the policy is referenced.

docs/netbox-extensions/changes/models/policyrule.md

@@ -0,0 +1,30 @@
+# Policy Rules
+
+Each [policy](./policy.md) contains one or more rules which assert certain conditions that must be met for the policy to be met. For example, you might define a policy that requires the approval of two engineers and one manager.
+
+Users whose reviews will satisfy the rule are identified by assigning individual users and/or groups of users for each rule. The minimum reviews parameter defines how many approved must be submitted for the rule to be met.
+
+## Fields
+
+### Name
+
+The short name by which the rule is identified.
+
+### Enabled
+
+A boolean indicating whether the rule is enabled. Rules are enabled by default.
+
+### Minimum Reviews
+
+The minimum number of eligible reviewers which must approve the change in order for the rule to pass.
+
+!!! note
+    A value of zero may be set to assert that a rule shall always pass, although this is generally not recommended.
+
+### Reviewer Groups
+
+Groups of users whose approval will satisfy this rule.
+
+### Reviewers
+
+Individual users whose approval will satisfy this rule.

docs/netbox-extensions/changes/models/review.md

@@ -0,0 +1,25 @@
+# Reviews
+
+Reviews are submitted to approve, reject, or comment on a [change request](./changerequest.md). The users eligible to review a particular change request are determined by its assigned [change policy](./policy.md).
+
+## Fields
+
+### Change Request
+
+The [change request](./changerequest.md) being reviewed.
+
+### User
+
+The author of the review.
+
+### Status
+
+The current status of the review. Valid statuses are listed below.
+
+| Status            | Description                                                      |
+|-------------------|------------------------------------------------------------------|
+| Pending           | The review is in progress                                        |
+| Comment           | The reviewer has questions or feedback                           |
+| Changes Requested | The reviewer has requested modifications to the proposed changes |
+| Approved          | The proposed changes are accepted                                |
+| Rejected          | The proposed changes are rejected                                |

mkdocs.yml

@@ -109,6 +109,7 @@ nav:
     - Branching:
       - Overview: "netbox-extensions/branching/index.md"
       - Configuration: "netbox-extensions/branching/configuration.md"
+      - Changelog: "netbox-extensions/branching/changelog.md"
       - Using Branches:
         - Creating a Branch: "netbox-extensions/branching/using-branches/creating-a-branch.md"
         - Syncing & Merging Changes: "netbox-extensions/branching/using-branches/syncing-merging.md"
@@ -118,6 +119,17 @@ nav:
         - Branch Events: "netbox-extensions/branching/models/branchevent.md"
         - Change Diffs: "netbox-extensions/branching/models/changediff.md"
         - Object Changes: "netbox-extensions/branching/models/objectchange.md"
+    - Change Management:
+      - Overview: "netbox-extensions/changes/index.md"
+      - Configuration: "netbox-extensions/changes/configuration.md"
+      - Changelog: "netbox-extensions/changes/changelog.md"
+      - Models:
+        - Change Request: "netbox-extensions/changes/models/changerequest.md"
+        - Comment: "netbox-extensions/changes/models/comment.md"
+        - Comment Reply: "netbox-extensions/changes/models/commentreply.md"
+        - Policy: "netbox-extensions/changes/models/policy.md"
+        - Policy Rule: "netbox-extensions/changes/models/policyrule.md"
+        - Review: "netbox-extensions/changes/models/review.md"
     - Diode:
       - Overview: "netbox-extensions/diode/index.md"
       - Get started: