This guide explains how the SwimOS docs site is set up and how contributions get merged.
Contribute to Documentation
Most documents on this site are located in the
src folder of the
swimos-docs repository and are organized using the Diátaxis Framework. You can add new content or update existing content in this folder.
Contribute to Documentation Website
Changes to templates or fixes to the docs site are also welcome! Please see the Styles guide to learn how website assets are structured and managed.
- Clone your fork of the repository.
- Change into the
git clone email@example.com:yourname/swimos-docs.git
rbenv, add it to $PATH, and install the latest version of Ruby:
brew install rbenv
echo 'eval "$(rbenv init -)"' >> ~/.zshrc
rbenv install 3.2.2
rbenv local 3.2.2
You may need to run this command to see newer versions of Ruby:
brew update && brew upgrade ruby-build
Install Jekyll & Dependencies
gem install jekyll bundler
Install JS dependencies
bundle exec jekyll serve --livereload
Note: On some Ruby versions this command may fail. Add
webrick to your dependencies and try again:
bundle add webrick
View the site at http://localhost:4000/
We haven’t set this up on Windows yet! If you run into issues getting this site up and running on Windows, please open an issue so we can look into it. If you manage to get it working, we’d welcome a PR to this doc with installation steps. :)
Open a Pull Request
Once you’ve made changes to content or the site, open a Pull Request to get your changes reviewed and merged.
PR Naming Conventions
We recommend, but do not require, that PR titles follow a
type: descriptionformat .
typerefers to the part of the code base that the PR is touching
docs: Updates to documentation. Most PRs will probably fall under this type.
chore: Updates to build scripts/tasks, no user-facing code changes.
feat: Used for new user-facing features.
revert: Used when reverting a previous commit.
fix: Used for bug fixes.
style: Updates to the look and feel of the site.
descriptiongives a short overview of what the PR is changing. Keep these short and simple.
An example PR title might look like:
docs: Add new tutorial that covers real time dashboard widgets. A PR that follows these conventions can be found here..
Pull Request Drafts
If you’d like to get early feedback on your pull request, you can open it and mark it as a draft.
Drafts are useful for when you want to propose a change but need feedback in order to complete the change set.
Pull Request Reviews
If your draft is ready for review, you can mark it as ready for review to get feedback from the SwimOS team.
@afolsonas a reviewer or tag
@afolsonin the comments to start the review process.
That’s it! Thank you for your interest in contributing to the SwimOS docs.