Submitting Changes

Overview

Superna's documentation and uses a docs-as-code strategy with a trunk-based branching model.

To contribute to the documentation, edit the Markdown files, and create a pull request to the trunk branch. The pull request is run through some style and spelling checks, and published to a temporary site once the checks have passed. When the pull request is accepted and merged, the staging site is updated with your documentation.

Creating and Submitting a Pull Request

You can use the Git tool of your choice. Using the Bitbucket Web interface is the easiest option for contributors from the field, but images and diagrams will be harder to manage. It's good for small fixes and updates.

To get the full functionality, the VS Code workflow used by the tech writer team is also documented below. See the Tools and Setup guide for installation and configuration instructions.

Bitbucket Web

All pages in the documentation have an Edit this page link at the bottom:

The link brings you to the source documentation in Bitbucket, and there is an edit button at the top right:

Changes can be previewed to a limited degree, and when the text is updated, click on Commit:

Enter a brief commit message (target 5 words) and click Create a pull request for this change. The default branch name is ok, and leave the reviewers blank. The docs team will be added as reviewers automatically.

Visual Studio Code

Make sure the Atlassian tool suite is setup as shown in the Tools and Setup guide.

To start working on a feature, browse to the Jira task that is assigned to you on this feature and click Start Work.

Leave the default settings on the next page, and click on Start

This will start a new branch in git. Close the Start Work tab after the success message appears.

Write the updates to the documentation. To create a commit, you can use the Source Control tab on the left, and view the list of changes. Clicking on a file will bring up the differences that this particular file contains. Enter a 5 word message into the Message Box, and click on Commit

It's usually good to Sync Changes after, this will create a copy of the current work on bitbucket that is recoverable if the local file is deleted or lost.

When ready to create a pull request, open the Atlassian extension from the toolbar on the left, and click on Create pull request...

This will bring up a new tab. Leave the settings as default, and click on Create Pull Request to submit.

Once the pull request is submitted, it will go through a series of automated checks. Please review the pipeline output, and make sure that the pipeline passes.

To make updates to a pull request, directly commit changes to the branch, and the PR will be updated automatically.