Contributing Documentation
The Resoto website and documentation are built with Docusaurus, a static-site generator. The source code lives in the someengineering/resoto.com repository on GitHub.
Authoring Changes​
Contributions are made via pull requests to the GitHub repository. Changes can be authored via the GitHub web interface (easy) or in a local repository using your favorite git client (recommended).
If your changes modify non-Markdown files, it is strongly recommended to work on a local clone of the repository rather than within the GitHub web interface.
GitHub Web Interface​
On the bottom of all documentation pages, there is an "Edit this page" link.
Simply click the link, make your changes, and select the "Create a new branch for this commit and start a pull request." option at the bottom of the page.
For supported Markdown features, please refer to the Docusaurus documentation.
Local Git Repository​
Prerequisites​
- Git (the below instructions assume you are using the CLI, though GUI clients will also work!)
- Code editor (Visual Studio Code is recommended)
- Node.js
- Yarn
Cloning the Repository​
You will first need to fork the repository.
Then, creating a local clone of the repository is as simple as:
git clone https://github.com/<your_github_username>/resoto.com.git
This will create a directory named resoto.com in your current working directory.
Next, add a remote pointing to the upstream repository (as opposed to your fork) named upstream:
git remote add upstream https://github.com/someengineering/resoto.com.git
We will now create a new branch from main (it is recommended to give your branch a meaningful, descriptive name):
git checkout -b <branch_name> main
Starting the Development Server​
We are finally able to get to the fun stuff! 🥳 Install dependencies and start a local development server:
yarn
yarn start
You will notice that http://localhost:3000 has been opened in your browser, where you can see your changes reflected live.
Testing Your Changes​
After you are done authoring your changes, be sure to format them with Prettier and verify they will pass our lint and build continuous integration checks:
yarn format
yarn lint
yarn build
Pushing Your Changes​
When you are ready to submit your changes for review, commit them to your local repository:
git commit
Then, push them to your fork:
git push --set-upstream origin <branch_name>
You can now submit your pull request on GitHub! You are welcome to open your pull request as a draft for early feedback and review. Be sure to follow the pull request template!
Pull request titles should follow the Conventional Commits specification.
However, do not worry too much about getting this right, as we will make any necessary adjustments prior to merging your changes.
Keeping Your Branch Up-to-Date​
If there are new commits to the main branch of the repository, you can update your branch by rebasing from your upstream remote:
git fetch upstream
git rebase upstream/main
To update the branch in your fork, you will then need to force push:
git push -f origin <branch_name>