Welcome to Radworks' docs! 👋

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.

• for typos, broken links, and other quick fixes
• for additions to the FAQ and Troubleshooting sections
• for revisions, rewrites, and larger improvements
• for feedback on structure & content
• for questions that can't be answered via documentation
• for improvements and fixups related to the look and feel of the docs site

Best practices for managing contributions

• If a question is asked more than twice in a support channel, a Radworks contributor should add as an outstanding issue. If a resolution is found, it should be captured in the issue before it's closed or in a following pull request. Those involved in the support process should contribute to the documentation (i.e. if you answered the question, be sure to capture the outcome in the relevant documentation).
• If a piece of unaddressed feedback is given more than three times, an issue should be created.
• issues should be created to capture upcoming documentation work related to new features or releases.

How to contribute

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

Run the website locally

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

Add a new doc

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.

Governance 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.

Commit signing

We require all commits to be signed for a branch to be merged into main. Learn more on setting up commit signing here.

Tips for managing your fork of 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