Contributions to the SeaLion Mission ConOps can come in a variety of roles. This document is intendend to provide guidelines for 2 types of contributors: subject-matter experts and technical writers.
A subject-matter expert (SME) or domain expert is a person who is an authority in a particular area or topic. SMEs work with technical writers to validate the content of the documentation.
SMEs can primarily contribute by Contributing to discussions.
A technical writer is a person who maintains the state of the documentation. Technical writers work with users, developers, and/or SMEs in order to document the intended design and behavior of the codebase, to maintain a consistent format, style, and tone, as well as to verify the contents readability and usability.
Technical writers can primarily contribute by Contributing to documentation.
The Discussions and Issues sections help facilitate invaluable feedback and discourse in the development and maintainability of the SeaLion Mission ConOps
Discussions can include general topics, ideas, and Q&A.
To open a new discussion,
-
On GitHub, navigate to the SeaLion Mission ConOps repository and click Discussions.
-
Click New discussion.
-
Select a discussion category from the drop-down menu.
-
Specify a title for the discussion topic, e.g., Alternative Mission ConOps.
-
Write a brief description of the scope of the discussion, e.g., This discussion is for brainstorming alternative mission concept of operations.
-
Click Start discussion.
Contributions to documentation can include, but not limited to, creating, updating, and/or reviewing content for the SeaLion Mission ConOps. We use a docs-as-code approach and the GitHub flow workflow to fascilitate these contributions. To decide what you can contribute, read through the list of Issues and comment on the issue if you’d either like to work on the particular issue or require additional clarity on the issue. Once you decide which issue you’d like to work on, you can submit a pull request. Contributors are also welcome to open an issue as well as help with reviewing a pull request.
Issues specify tasks that allow maintainers to capture & resolve missing or incorrect content, as well as implement new features or bug fixes in the documentation build tools. Some issues are grouped by Milestones - a collection of issues that relate to a specific deliverable. Completed milestones are tagged as a Release.
To open an issue,
-
On GitHub, navigate to the SeaLion Mission ConOps repository and click Issues
-
Click New issue.
-
Specify a title for the issue topic. A good issue title should start with a verb, e.g., add CubeSat Design Specification as a reference in architecture.
-
Write a brief description of the scope of the issue, e.g., architecture/0-References directory should include a reference for the latest CubeSat Design Specification document.
-
Click Submit new issue.
See Creating an issue.
A pull request is a proposal for changes to a branch.
To submit a pull request,
|
❗
|
If you haven’t been added as a collaborator to the SeaLion Mission ConOps repo, you will need to either fork the repo or contact the repo admin to request write access. If you’ve forked the repo, be sure to sync your forked repo in order to avoid potential merge conflicts. |
-
Create a new branch in the SeaLion Mission ConOps repo. Make sure the branch name follows the content style guide for naming a branch.
-
As you edit your content, ensure that it conforms to the content style guide.
-
Commit your changes and create a pull request. Be sure to include a closing keyword followed by the associated issue number in the pull request description, e.g.,
closes #1701. If the pull request closes multiple issues, add a closing keyword for each issue.
|
❗
|
If you are creating a pull request from a forked repo, be sure that the base branch of the pull request is set the main branch of the SeaLion Mission ConOps repo, not your forked repo.
|
-
If you’re not yet ready for a review, mark the pull request as Draft to indicate it’s a work in progress. Continue updating your doc and pushing your changes until you’re happy with the content.
-
When you’re ready for a review, mark the pull request as Ready for review.
-
Once your pull request has been merged, you can safely delete your branch.
Content in architecture/ should be consistent with the Mach30 modeling language (m30ml). YAML files specified in m30ml should subside in the 0-References/, 1-StakeholderNeeds, 2-UserStories, or 3-Datastructures directory, and be prependend with a number, followed by a dash, the content name in Pascal Case, and a .yaml . e.g., 2-CubeSatDesignSpecificationRev13.yaml.
package.json files for components in the components directory (and subdirectories) should conform to the specification for a DOF-Component.
Branch names should be all lowercase, prepended with its associated issue label, followed by a dash-separated description of the changes to be made, followed by its associated issue number, and delimited by a forward slash, /.
e.g., feature/add-tricoder-with-touchscreen-docs/1701.
If no such issue exists, open an issue.
We use semantic versioning (semver) for denoting changes/updates to the SeaLion Mission ConOps under version in the package.json. Given the version number MAJOR.MINOR.PATCH, increment the:
-
MAJOR version when you make incompatible API changes. e.g., removing or renaming a file or folder in the
architecture/orcomponents/directory -
MINOR version when you add functionality in a backwards compatible manner. e.g., adding a file or folder in the
architecture/orcomponents/directory, and -
PATCH version when you make backwards compatible bug fixes. e.g., updating the contents of a file in the
architecture/orcomponents/directory