GitHub Workflow - Two Ways

Route A - GitHub via web interface

First, either open a new Issue in the Archipelago Documentation Github Repo describing the new documentation you would like to contribute, or reply to an existing Issue that you would like to address. Tag @alliomeria to request feedback. Since our team is consistently working on new and updating existing documentation, please wait for review and guidance before proceeding with creating the new documentation you described in your new Issue or comments on an existing documentation Issue.
Fork the documentation repo. If you're not familiar with forking see this guide.
In your local fork of Archipelago's documentation, before proceeding with making changes to existing or adding new documentations guides, make sure you first select 'Sync Fork' and that the local fork branch you are working on is up-to-date with the same branch in the main documentation repo.
Working in your synced, up-to-date local fork, proceed with navigating to the existing documentation guides you would like to edit, or proceed with creating a new guide as related to the Issue you followed up on in Step 1.
Commit your changes (whether edits or new additions) and add notes describing what is part of the committed changes.

If this is new documentation add it to the nav section of the mkdocs.yml configuration file at the root of the repo. For example:

nav:
  - Home: index.md
  - About Archipelago:
    - Archipelago's Philosophy & Guiding Principles: ourtake.md
    - Strawberryfields Forever: strawberryfields.md
    - Software Services: devops.md
    - New Documentation: new_documentation.md
  - Code of Conduct: CODE_OF_CONDUCT.md
  - Instructions and Guides:
    - Archipelago-Deployment:
      - Start: archipelago-deployment-readme.md
      - Installing Archipelago Drupal 9 on OSX (macOS): archipelago-deployment-osx.md
      - Installing Archipelago Drupal 9 on Ubuntu 18.04 or 20.04: archipelago-deployment-ubuntu.md
      - Installing Archipelago Drupal 9 on Windows 10/11: archipelago-deployment-windows.md
      - Adding Demo Archipelago Digital Objects (ADOs) to your Repository: archipelago-deployment-democontent.md
...

Create a pull request and link to the Issue by tagging it, e.g. Resolves #100.
Please tag @alliomeria when you are ready for your contributed documentation to be reviewed. Our team will review and provide feedback, and let you know when your contributed documentation is merged. Thank you in advance for your time and efforts to create documentation for Archipelago's community!

Route B - GitHub via local desktop client with optional local build and preview

This pathway is not necessary for most documentation contributions.

First, either open a new Issue in the Archipelago Documentation Github Repo describing the new documentation you would like to contribute, or reply to an existing Issue that you would like to address. Tag @alliomeria to request feedback. Since our team is consistently working on new and updating existing documentation, please wait for review and guidance before proceeding with creating the new documentation you described in your new Issue or comments on an existing documentation Issue.
Fork the documentation repo. If you're not familiar with forking see this guide.
Create an issue branch in your forked repo. For example, if the issue you're resolving is ISSUE-100:
```
git checkout -b ISSUE-100
```

Copy this template to create a new piece of documentation:

cp docs/documentation_template.md docs/new_documentation.md

Make your changes to the copied markdown file.

If this is new documentation add it to the nav section of the mkdocs.yml configuration file at the root of the repo. For example:

nav:
  - Home: index.md
  - About Archipelago:
    - Archipelago's Philosophy & Guiding Principles: ourtake.md
    - Strawberryfields Forever: strawberryfields.md
    - Software Services: devops.md
    - New Documentation: new_documentation.md
  - Code of Conduct: CODE_OF_CONDUCT.md
  - Instructions and Guides:
    - Archipelago-Deployment:
      - Start: archipelago-deployment-readme.md
      - Installing Archipelago Drupal 9 on OSX (macOS): archipelago-deployment-osx.md
      - Installing Archipelago Drupal 9 on Ubuntu 18.04 or 20.04: archipelago-deployment-ubuntu.md
      - Installing Archipelago Drupal 9 on Windows 10/11: archipelago-deployment-windows.md
      - Adding Demo Archipelago Digital Objects (ADOs) to your Repository: archipelago-deployment-democontent.md
...

To view the changes locally, first install the Python libraries using the Python package manager pip:
```
pip install mkdocs-material mike git+https://github.com/jldiaz/mkdocs-plugin-tags.git mkdocs-git-revision-date-localized-plugin mkdocs-glightbox
```
You may need to install Python on your machine. Download Python or use your favorite operating system package manager such as Homebrew.
Now you can build the site locally, e.g. for the documentation using the 1.5.0 branch:
```
mike deploy 1.5.0
mike set-default 1.5.0
```
If you create a new branch to match the issue number as in step 3, you would use your branch instead of 1.5.0. For example, a branch of ISSUE-129.
```
mike deploy ISSUE-129
mike set-default ISSUE-129
```
Start the web server:
```
mike serve
```
Check the results in your browser by going to: http://localhost:8000

If everything looks good, you can push to your forked repo issue branch:

git add .
git commit -m "Create new docs with useful information."
git push origin ISSUE-100

Create a pull request and link to the Issue by tagging it, e.g. Resolves #100.
Please tag @alliomeria when you are ready for your contributed documentation to be reviewed. Our team will review and provide feedback, and let you know when your contributed documentation is merged. Thank you in advance for your time and efforts to create documentation for Archipelago's community!

Thank you for reading! Please contact us on our Archipelago Commons Google Group with any questions or feedback.

Return to the Archipelago Documentation main page.