This is the repository for the Radworks documentation site at docs.radworks.org
, which
includes community-, and governance-focused documentation.
This document outlines some contributing guidelines, contact points, and other resources to make it easier to contribute to Radworks' documentation.
docs.radworks.org
was created with Docusaurus.
If you run into a problem or have a suggestion, browse the open issues before opening a new one. We use the following label system to organize our issues.
First, create a fork of the radworks-docs
repository
and clone that to your local system, where you'll make your edits and create Git commits.
git clone git@github.com:<YOUR-GITHUB-USERNAME>/radworks-docs.git
First, install NodeJS and Yarn on your system.
Navigate into the radworks-docs
folder on your local system and install dependencies:
cd radworks-docs/
yarn install
You can then run the dev server and access it at http://localhost:3000
from your browser of choice.
yarn start
When you create a new Markdown document in the docs/
folder — we very prefer .mdx
files, by the way! —
make sure your frontmatter section includes an id
that matches the filename and a title
field, which Docusaurus uses
on the website directly.
You must add your new doc to the sidebar, specified in sidebars.js
. Find the appropriate place in the sidebar for
your doc, create a newline, and add the id
of your doc.
const sidebars = {
docsSidebar: [
...
{
type: 'category',
label: 'Example',
collapsed: false,
items: [
...
'your-new-doc', // A new document with the `id` of `your-new-doc`.
]
},
...
]
...
}
For more information about adding new docs to the sidebar, or configuring the sidebar itself, see the Docusaurus docs.
We house many explanatory docs for how governance works in this repository, with a few exceptions — notably the Governance Manual, which which describes the current governance processes of the Radworks and can only be updated via off-chain approval.
Changes to the Manual follow a separate contribution process.
We require all commits to be signed for a branch to be merged into main
. Learn more on setting up commit signing
here.
radworks-docs
When you clone your fork of radworks-docs
, the repository at YOUR-GITHUB-USERNAME>/radworks-docs
is set as the
default origin
remote. If you want to keep your fork up-to-date with the state of the
radicle-foundation/radworks-docs
repository, you need to occasionally pull new commits into your fork. The best way to
do that is to add a new upstream
remote to your fork on your local system:
cd radworks-docs/
git remote add upstream https://github.com/radicle-foundation/radworks-docs.git
You can now pull changes from upstream
to synchronize main
branches across repositories:
git pull upstream main
If you need to combine the latest changes from upstream/main
to a branch you're currently working on in your fork,
you should perform a rebase.
git pull --rebase upstream main
If your branch and upstream/main
have diverged, you'll need to resolve them using a text editor, add the file with
git add <FILENAME>
, and run git rebase --continue
.
When the rebase completes, you can push the updated state to origin/main
:
git push --force origin main