Skip to content

Latest commit

 

History

History
146 lines (95 loc) · 5.96 KB

CONTRIBUTING.md

File metadata and controls

146 lines (95 loc) · 5.96 KB
Raw

Contributing

We would love for you to contribute to the Aerie documentation and help make it even better than it is today!

Prerequisite Knowledge

The Aerie documentation is built with Docusaurus. Documents can be written in either vanilla Markdown (.md files), or MDX (.mdx files). Most of the time you will want to use .mdx to add assets, or things like admonitions. Please see the Docusaurus documentation for the complete set of available markdown features.

Prerequisite Software

Before you can run the Aerie documentation locally you must install and configure the following products on your development machine:

  • Git and/or the GitHub app; GitHub's Guide to Installing Git is a good source of information.

  • Git LFS which is used to store images and video. Make sure after installing you also run git lfs install to initialize Git LFS.

  • Node.js LTS which is used to run a development web server, and generate distributable files. We recommend using the Node Version Manager (NVM) to install Node.js and NPM on your machine. Once you have NVM installed you can use the required Node.js/NPM versions via:

    cd aerie-docs
nvm use

Editor

The recommended editor for writing Aerie documentation is VS Code with the following settings and extensions. You can easily use another editor of your choice as long as you can replicate the formatting and spell-check settings.

Settings.json

Your editor should follow the same settings found in .vscode/settings.json.

Extensions

  1. Prettier - Code formatter
  2. Code Spell Checker
  3. MDX

Clone the Repository

Clone the aerie-docs repository:

git clone https://github.com/NASA-AMMOS/aerie-docs.git
cd aerie-docs

Install Dependencies

cd aerie-docs
npm install

Start Documentation Server

cd aerie-docs
npm start

Visit http://localhost:3000/aerie-docs/ to view the documentation in your local browser. Any changes you make to the documentation will auto-reload the page with your changes.

Adding a New Document

If you need to add a new document you need to update the sidebar.js file with the name of your new document. Please see the Docusaurus documentation on the sidebar for more detailed instructions.

Adding Images or Videos

Images should be added to the repository using the .png format. Videos should be added to the repository using the .webm or .mov format.

Typically images and videos should be placed in an assets directory in the section of documentation they correspond to. For example see the command-expansion documentation and planning documentation.

In rare cases you may need to add static assets to the static directory if they do not easily correspond to a documentation section.

Submitting a Pull Request

Please follow these instructions when submitting a Pull Request:

  1. Search GitHub for an open or closed PR that relates to your submission. You don't want to duplicate effort.

  2. Make your changes in a new git branch:

    git checkout develop
git pull origin develop
git checkout -b my-fix-branch develop

  3. Commit your changes using a descriptive commit message.

    git commit -a

    Note: the optional commit -a command line option will automatically "add" and "rm" edited files.

  4. Push your branch to GitHub:

    git push origin my-fix-branch

  5. In GitHub, send a pull request to aerie-docs:develop.

  6. If we suggest changes then:

  • Make the required updates.

  • Rebase your branch and force push to your branch to GitHub (this will update your Pull Request):

    git rebase develop -i
git push -f

After your pull request is merged, you can safely delete your branch and pull the changes from the repository:

  • Check out the develop branch:

    git checkout develop

  • Update your develop with the latest version:

    git pull origin develop

  • Delete the local branch:

    git branch -D my-fix-branch

Got a Question or Problem?

If you would like to chat about the question in real-time, you can reach out via our Slack channel.