nautobot / nautobot-app-version-control

Version Control App that uses and requires a Dolt Database

Nautobot Version Control

An App for Nautobot.

Overview

The Nautobot Version Control app brings version control to the Nautobot open source Network Source of Truth and Network Automation Platform.

Nautobot provides a number of features to validate its data model and safeguard network configuration from errors. Adding database versioning provides another layer of assurance by enabling human review of proposed changes to production data, use of automated testing pipelines, and database rollback in the case of errors.

The database versioning is made possible by the use of a Dolt database. Dolt is a MySQL-compatible SQL database that you can fork, clone, branch, merge, push and pull just like a Git repository.

Dolt’s branch and merge versioning model allows operators to safely modify the data model on feature branches, merging to production only after validation is complete.

Screenshots

Developer Note: Add any representative screenshots of the App in action. These images should also be added to the docs/user/app_use_cases.md section.

Developer Note: Place the files in the docs/images/ folder and link them using only full URLs from GitHub, for example: ![Overview](https://raw.githubusercontent.com/nautobot/nautobot-plugin-version-control/develop/docs/images/plugin-overview.png). This absolute static linking is required to ensure the README renders properly in GitHub, the docs site, and any other external sites like PyPI.

More screenshots can be found in the Using the App page in the documentation. Here's a quick overview of some of the plugin's added functionality:

Try it out!

Developer Note: Only keep this section if appropriate. Update link to correct sandbox.

This App is installed in the Nautobot Community Sandbox found over at demo.nautobot.com!

For a full list of all the available always-on sandbox environments, head over to the main page on networktocode.com.

Documentation

Full documentation for this App can be found over on the Nautobot Docs website:

• User Guide - Overview, Using the App, Getting Started.
• Administrator Guide - How to Install, Configure, Upgrade, or Uninstall the App.
• Developer Guide - Extending the App, Code Reference, Contribution Guide.
• Release Notes / Changelog.
• Frequently Asked Questions.

Contributing to the Documentation

You can find all the Markdown source for the App documentation under the docs folder in this repository. For simple edits, a Markdown capable editor is sufficient: clone the repository and edit away.

If you need to view the fully-generated documentation site, you can build it with MkDocs. A container hosting the documentation can be started using the invoke commands (details in the Development Environment Guide) on http://localhost:8001. Using this container, as your changes to the documentation are saved, they will be automatically rebuilt and any pages currently being viewed will be reloaded in your browser.

Any PRs with fixes or improvements are very welcome!

Questions

For any questions or comments, please check the FAQ first. Feel free to also swing by the Network to Code Slack (channel #nautobot), sign up here if you don't have an account.

nautobot-app-version-control's Issues

Add Edit view for PR

Device's 'Status' change shows some kind of hash in Diffs view

Reviewing Diffs for a recent PR. One of the changes was changing a Device's status from Active to Decommissioning.

On the Pull Requests screen, the Status change shows some kind of hash or UUID. I'd expect to see the text value of the status: Before status as Active and the After status as Decommissioning.

Unable to access Jobs

Navigate in the UI to Extensibility -> Jobs

Center text in "Active Branch" banner

replace Merge button with PR button in branch table

add branch column to commits table

Commit messages with many changes should be summarized

The "short_message() computed field for the Commit model currently shortens long commit messages to only show the first change in the message. This should be altered to also summarize the number of total changes in the commit

hook into CI (Travis or GHA when we do)

Specify Active Branch via session cookie and API request header

Remove query string parameter

define configurable options within plugin config

1. default branch name (possibly as an alias to main within Dolt)

Remove branch banner for unauthenticated users

This is pre-login. Can we ensure the banner isn't displayed without auth?

documentation

discussion on diffs

After deleting a device, there is a large set of diffs.

Is there a reason why the device name is not shown in the interfaces diff? This would become difficult to digest if there were multiple devices deleted with the same interfaces.

Few things with a focus on understanding and readability:

For the change types, there is currently added, removed, before, and after. It would be nice to have "changed" in addition to before or after for the only value is displayed in that column. Here is an example of what it could be:

Open to ideas for the visual, but I'd rather be explicit in stating it was a change.

I'd also like to explore adding a thin empty row (or anything else) to differentiate between "changes" since it's two rows per change and it's harder to read when there are many of them. Another idea is numbering them - add an "ID" column? Again the goal is to make the visual clean and understandable especially when the diff set is more than a few lines.

It would still be great to highlight the exact column of changed data when it is of type "change".

replace "checkout" with "Activate" button in branch table

Add inline merge button to branch list view

Jason Edelman:
I'd also like to see if we can add a "Merge" button to the left of the checkout button instead of the single Merge button. When you click the button, it'll just redirect to the page that shows the source as the branch that you clicked the button on. You would then use the drop down to choose the Destination Branch. For now, put the Source on top.

Squash Merge for Pull Requests

Add support for optionally squashing commits while merging pull requests

Right justify Diff Summary Table

Referencing the following table, let's right justify the counters and try and enter them vertically inline with the text to the left.

Add API endpoints

• PRs
• PR Comments
• Branches
• Commits (includes revert)

change default ordering of commits table

Change to:
Message | Date | Committer | Email | Commit Hash

It is currently:
Commit Hash | Committer | Email | Date | Message

update author email in reverts in branch page (currently it's static)

On main page for a branch, have a button available to checkout the branch

The main page for a given branch should have the option to checkout the branch (if checkout is still possible)

Pull Request Reviews should show Reviewer Names as a `<label>`

"ntc" should be styled as a <label> tag

ensure invoke tasks exist for "easy" build/deploy of local environment w dolt db

use capital letters in buttons

Let's convert the buttons to use Capital Letters.

add column in branch table to show "active" status

keep green "Active" but make label and should be in column 2

Update commit "name"

After doing #13 the name will be different. Would like to change the "name" and what's in the breadcrumb - from hash to the commit message.

AutoDoltCommit for `manage.py` commands

When the Nautobot Dolt plugin is installed, middleware automatically triggers a Dolt commit for each write request. We need to mirror this behavior for manage.py commands that make database writes.

"Ahead/Behind" computed column in Branch list view

From the branch list view, the user should be able to see the number of commits "ahead" and "behind" that each branch is from the primary branch. This mirrors the same functionality on Github.

unit tests

Web Hooks for Pull Requests

Create/Broadcast web hook events for Pull Request life-cycle events:

• PR creation
• PR approval
• PR merge

Share Button to create versioned links

When using Nautobot with the Dolt plugin, Branch state information is stored in the session cookie. This state is not encoded in the URL and sharing links will therefor lack the necessary branch context.

In order to share "versioned links" users will use a "share" button that will created a version of the current URL with the branch-state encoded

Show author and source branch in the branch list view

Pull Request Home Screen Needs `Add` button

The Pull Request Home Screen does not have a button to Add/Create a pull request, forcing the user to go to Dolt-->Pull Requests-->+ button to create one

Commit with Nautobot user identity

Use the current users identity when added meta-data to a Commit. This should be reflected in the Commit list and detail views.

Filter Pull Request list view by Creator, Reviewer, and Status

Drop-down selects for Creator and Reviewer. Multi-select for status

Change underscore to hyphen in Dolt URLs and APIs

For now, let's nautobot_dolt to nautobot-url in URLs and APIs

I don't know if we end up keeping this as the final name, but will be thinking about it, and open to feedback. Right now, still thinking something more like "Workflow Management" or "Change Management."

update breadcrumbs

Similar to the URL, we may end up changing it from being dolt but for now I'd like to add to the breadcrumbs in Commits.

On the commits page, it's currently:
Commits / qgea09r8knk5qjvqal1l11c0cp58cqnj

Let's add to it so it is Dolt / Commits / $commit-message (this is adding "Dolt" and swapping out hash for message per #14

Same would be true for a branch page. Add "Dolt" to the breadcrumb.

Also for the commits page, instead of just having the page title being "Commits in Active Branch," let's add breadcrumbs:
Dolt / Branches / $branch-name with the page name being $branch-name

add "Catch up" button to branch table redirecting to PR page

improve merge conflict UI

example from @glennmatthews

Need to decide if we would shade the conflicting values' backgrounds different colors for more contrast? AND/OR slightly more padding between the lines in a single row...

New PRs from a branch should populate that branch as 'Source Branch'

When user is working on a branch that has diffs, the 'Add a new pull request' screen should default to using that branch as the 'Source Branch'.

In the example below, I'm on the atl-augment branch. When I create a PR, the Source Branch should auto-populate with atl-augment.

Protect Branches referenced by Pull Requests

PullRequests are modeled as Django models in the following way:

class PullRequest(BaseModel):
    ...

    title = models.CharField(max_length=240)
    state = models.IntegerField(choices=PR_STATE_CHOICES, default=OPEN)
    source_branch = models.TextField()
    destination_branch = models.TextField()
    description = models.TextField(blank=True, null=True)
    creator = models.ForeignKey(User, on_delete=CASCADE)
    created_at = models.DateTimeField(auto_now_add=True, blank=True, null=True)

The source_branch and destination_branch fields reference Branch models (stored in the dolt_branches table), but to not use the typical method of creating a Foreign Key reference to this model. Due to technical restrictions in the Dolt model, Foreign Keys cannot but created against the dolt_branches table.

Currently, referential integrity between PullRequests and Branches can be broken by deleting a Branch that is referenced by a PullRequest. Two steps to fixing this:

1. Prevent deleting Branches that are referenced by PullRequests
2. Allow PullRequests to be deleted

update auto commit message

Can you change from auto dolt commit to auto commit - $model - datetime ?

Add bulk delete for PRs

Blocked by #48

`Revert()` needs to use the correct author

add ability to search by committer in commits list view page

Pull Request Screen 'State' and 'Status' Appear To Be Same Thing

The Pull Requests page has a column header of Status; the Search box to the right has a State field. These appear to reference the same thing

Enable GHA on the repo

Enable CI with Github Actions on this repo to execute all linters and unit tests automatically.

There is a good change that currently most linters are failing, we''ll need to track them individually and test them one by one.

question: should we support deleting PRs?

Add 'Branch Name' column to Branch Commits view

The Commits in <branch name> page should have a column that contains the name of the branch that each commit was a part of. That is not evident from the current data displayed.

new branch not being displayed branch list

it did eventually show, but wasn't there after a few minutes. see the branch in banner is not in the list.