Feat: Add documentation site using Docusaurus #2358

CHANGELOG.md

@@ -4,6 +4,10 @@
 
 * Use ack for CREATE_NETWORK and simplify
 
+# Other
+
+* Added documentation using Docusaurus #2358
+
 [2.1.2]
 
 # Refactorings:

README.md

@@ -140,3 +140,11 @@ Even though Quiet is completely peer-to-peer, it is mostly written in TypeScript
 To get started hacking on Quiet, follow the instructions for [Quiet Desktop](https://github.com/TryQuiet/quiet/blob/develop/packages/desktop/README.md) or [Quiet Mobile](https://github.com/TryQuiet/monorepo/tree/develop/packages/mobile#readme). (If you're new to the project, start with Quiet Desktop, as it's more stable and vastly easier to start hacking on.) Here are some [good first issues](https://github.com/orgs/TryQuiet/projects/3/views/4?filterQuery=label%3A%22good+first+issue%22), and you can see upcoming priorities in our [project board](https://github.com/orgs/TryQuiet/projects/3/views/4).
 
 Most of all, if you're interested in contributing, be in touch! Drop us a line at [[email protected]](mailto:[email protected]) and we'll add you to the project's Quiet community and (if you like) plan an onboarding session.
+
+## Documentation
+
+Quiet is using Docusaurus for serving documentation and is currently local-only. To run the documentation locally you can execute the following command from the root directory:
+
+```
+npm run docs:start
+```

package.json

@@ -4,7 +4,11 @@
  "scripts": {
  "lerna": "lerna",
  "publish": "lerna version $npm_config_release --no-private",
- "postpublish": "node copy-changelog.js && git add . && git commit -m 'Update packages CHANGELOG.md' && git push"
+ "postpublish": "node copy-changelog.js && git add . && git commit -m 'Update packages CHANGELOG.md' && git push",
+ "docs:build": "npm run --prefix ./quiet-docs build",
+ "docs:start": "npm run --prefix ./quiet-docs start",
+ "docs:serve": "npm run --prefix ./quiet-docs serve",
+ "docs:deploy": "npm run --prefix ./quiet-docs deploy"
  },
  "engines": {
  "node": "18.12.1",

quiet-docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

quiet-docs/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

quiet-docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+ presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

quiet-docs/docs/contributing/_category_.json

@@ -0,0 +1,7 @@
+{
+ "label": "Contributing",
+ "position": 2,
+ "link": {
+ "type": "generated-index"
+ }
+}

quiet-docs/docs/contributing/contributing-to-quiet.md

@@ -0,0 +1,10 @@
+---
+sidebar_position: 1
+title: Contributing To Quiet
+---
+
+Even though Quiet is completely peer-to-peer, it is mostly written in TypeScript and will be familiar to anyone accustomed to Node.js web development. Desktop and mobile versions share a common Node.js [backend](https://github.com/TryQuiet/monorepo/tree/develop/packages/backend) and React [state manager](https://github.com/TryQuiet/monorepo/tree/develop/packages/state-manager), with [Tor](https://torproject.org) binaries for each platform and architecture, using Electron and React Native and for their respective frontends.
+
+To get started hacking on Quiet, follow the instructions for [Quiet Desktop](https://github.com/TryQuiet/quiet/blob/develop/packages/desktop/README.md) or [Quiet Mobile](https://github.com/TryQuiet/monorepo/tree/develop/packages/mobile#readme). (If you're new to the project, start with Quiet Desktop, as it's more stable and vastly easier to start hacking on.) Here are some [good first issues](https://github.com/orgs/TryQuiet/projects/3/views/4?filterQuery=label%3A%22good+first+issue%22), and you can see upcoming priorities in our [project board](https://github.com/orgs/TryQuiet/projects/3/views/4).
+
+Most of all, if you're interested in contributing, be in touch! Drop us a line at [[email protected]](mailto:[email protected]) and we'll add you to the project's Quiet community and (if you like) plan an onboarding session.

quiet-docs/docs/contributing/development-workflow.md

@@ -0,0 +1,55 @@
+---
+sidebar_position: 2
+title: Development Workflow
+---
+
+# Development workflow
+
+## Overview
+
+> **New to open source?** You can learn how from this _free_ series: [How to Contribute to an Open Source Project on GitHub](https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github).
+
+1. Fork the repo and create your branch from `develop` (a guide on [how to fork a repository](https://help.github.com/articles/fork-a-repo/)).
+2. Being in the root directory, run `npm i` and then `lerna bootstrap`, to setup the development environment.
+3. Check out [desktop](https://github.com/TryQuiet/quiet/blob/develop/packages/desktop/README.md) and [mobile](https://github.com/TryQuiet/quiet/blob/develop/packages/mobile/README.md) README.md for more instructions.
+
+## Commit message convention
+
+Prefix commit messages with one of the following to signify the kind of change:
+
+- `fix:` bug fixes, e.g. fix incorrect error message.
+- `feat:` new features, e.g. add useful API.
+- `refactor:` code/structure refactor, e.g. new folder structure.
+- `docs:` changes into documentation, e.g. add usage example for getByText.
+- `test:` adding or updating tests, eg unit, snapshot testing.
+- `chore:` tooling changes, e.g. change circle ci config.
+- `BREAKING:` for changes that break existing usage, e.g. change API.
+
+Commit message should be followed by the issue number, eg.
+`fix: typo #2002`
+
+### (optional) Setting up a local git hook for verifying message convention:
+
+1. Navigate to git repository in your terminal.
+2. Go to the .git/hooks directory:
+```
+cd .git/hooks
+```
+3. Create (or edit if it already exists) the commit-msg file
+4. Make the file executable:
+```
+chmod +x commit-msg
+```
+5. Edit the commit-msg file and paste the following shell script:
+```
+#!/bin/bash
+
+COMMIT_MSG_FILE=$1
+COMMIT_MSG=$(cat $COMMIT_MSG_FILE)
+
+if ! echo "$COMMIT_MSG" | grep -E '^(fix:|feat:|refactor:|docs:|test:|chore:|BREAKING:|Publish)' > /dev/null; then
+ echo "error: invalid commit message format"
+ echo "Valid formats are fix: feat: refactor: docs: test: chore: BREAKING:"
+ exit 1
+fi
+```

quiet-docs/docs/contributing/publishing.md

@@ -0,0 +1,110 @@
+---
+sidebar_position: 3
+title: Publishing Releases
+---
+
+# Publishing Instruction for the Core Team Developers.
+
+## Release Owner
+
+_Current release owner 🎉⛸️🦆 [@leblowl](https://github.com/leblowl) (February 2024)_
+
+
+## Trigger
+
+Release process begins when all issues from `Sprint` are merged and moved to `Ready for QA`. 
+
+
+## Branching strategy
+
+Each release starts with it's own branch (based on develop).
+Develop becomes a draft for the next release.
+From this moment, all the fixes (patches) for the last supported version are being merged into the release branch and cherry-picked into develop.
+
+
+### Example
+
+```
+/develop -> /2.1.0 -> #patch-commit
+ -> #feature-commit -> #patch-commit (cherry-picked) -> /2.2.0
+ -> ...
+```
+
+
+## Releasing
+
+### Release candidates (alpha releases)
+
+Pre-release builds should only be triggered from the release branch and then delivered to QA. 
+Alpha versions should be delivered to QA by updating GitHub with a link to the correct versions (for desktop) and numbers of current versions (for mobile). All GitHub issues included in the released alpha version should be moved to the Ready for QA column.
+If QA reports problems that needs to be solved, the fixes must be merged into the release and develop branches, then a patched pre-release is to be built.
+
+
+### Pre-release checklist
+
+- [ ] Build is working correctly, passes automated tests and self-QA
+- [ ] Release candidate is delivered for QA
+- [ ] Sprint column is free from QA reported blocking issues
+- [ ] QA approved the release
+- [ ] All hotfixes to previous releases have been merged into the release (and develop) branch
+- [ ] CHANGELOG.md is up to date
+- [ ] PM approved the release
+
+
+### Publishing instruction
+
+By the time release is ready, ask @holmes for <b>CHANGELOG.md</b> cosmetic review, then:
+1. Checkout to a branch named after the release version number
+2. Navigate to root project directory
+3. Update CHANGELOG.md file
+4. Use the following command (with proper release type !For alpha releases use `pre` prefix!): 
+ `npm run publish --release=[patch|minor|major|EXACT_VERSION]`
+5. Cherry-pick `Publish` and `Update packages CHANGELOG.md` commits into /develop
+6. Manually update release notes on the [Releases Page](https://github.com/TryQuiet/quiet/releases)
+
+
+### Post-Release
+
+#### Alpha Checklist
+
+- [ ] App is promoted and sent for review on a closed testing track in Google Play
+
+
+#### Production Checklist
+
+- [ ] Download links are updated on a website and in README.md
+- [ ] App is promoted and sent for review on a production track in Google Play
+- [ ] App is promoted and sent for review on an external track in App Store (Test Flight)
+
+
+### Changelog / Releases Page
+
+Root <b>CHANGELOG.md</b> file contents are being copied into each packages' ones. 
+This process is automated by `copy-changelog.js` script hooked on `postpublish` action.
+- [ ] Edit release notes to match style guide (See: [Release Notes](release-notes-guide))
+
+
+### QA
+
+QA tests for issues on all the supported platforms and moves discovered blocking issues intoto the Sprint column, then mentions them in Slack <b>#qa</b> channel, following the criteria: 
+- regression,
+- new bug that creates a general feeling of unreliability,
+- issue that is incompletely implemented according to the issue description,
+
+
+## Book of laws
+
+1. Team drops any other work to work on new issues in the Sprint column
+2. PM can asynchronously decide a bug is not a blocker
+3. Team and QA can consult PM if they suspect a bug is not really a blocker despite meeting criteria
+4. PM can approve release in advance, pending completion of issues, or wait to give approval
+
+
+## (TODO) Publishing Process Document
+
+1. Expand on post-release checklist
+
+
+
+
+

quiet-docs/docs/contributing/release-notes-guide.md

@@ -0,0 +1,49 @@
+---
+sidebar_position: 4
+title: Release Notes
+---
+
+# Release Notes Process and Style Guide
+
+## Overview
+
+We want users to know what's new in Quiet with each release, and we want people interested in using Quiet to be able to follow our progress. This document describes a process for creating release notes that are readable and informative to a wide audience. 
+
+## Model release notes
+
+* [Mobile v2.1.1](https://github.com/TryQuiet/quiet/releases/tag/%40quiet%2Fmobile%402.1.1)
+* [Mobile v2.0.1](https://github.com/TryQuiet/quiet/releases/tag/%40quiet%2Fmobile%402.0.1)
+
+## Process/Checklist
+
+Follow these steps to make sure the changelog is maximally readable and informative:
+
+### Add
+
+- [ ] All significant items since the last release, including items from the preceding alpha releases. 
+- [ ] Any big high level features that are broken into small changelog entries (e.g. "user can join community without owner being online")
+- [ ] Thank you's to external contributors (check items to see if they were contributed by somebody external, and add "Thanks @username!")
+
+### Remove
+
+- [ ] Changelog items that cannot be made understandable to the user.
+- [ ] "Refactor" items unless they bring some user benefit like performance.
+- [ ] Any items about tests because they're not always relevant to the user.
+- [ ] Any items about dependency updates.
+- [ ] Any items about minor dependency updates. We can still list major ones (like Electron, React Native, OrbitDB, IPFS, Tor, libp2p, etc.) under improvements.
+- [ ] Any fixes that relate to previously-unreleased features, since from the user's point of view these are included in the new feature.
+
+### Group and Rewrite
+
+- [ ] Group new features, improvements, fixes, breaking changes, and notes
+- [ ] Rewrite items as result-oriented complete sentences under "Fixes:" category like "peers now dial..." or "long messages are no longer truncated..." 
+- [ ] Rewrite improvements as noun phrases. e.g. "Better descriptions of the joining process"
+- [ ] Use standard capitalization and punctuation of sentences. 
+
+## Changelog best practices
+
+- [ ] fixes in the changelog should reference the issue they fix!
+- [ ] Make all changelog items understandable to a technical user whenever possible, assuming no knowledge of Quiet internals. 
+- [ ] When the fix refers to an issue, mention the problem the fix is solving in the changelog entry (e.g. "network data proceeding when using custom protocol multiple times" should be "fixes unclear UI when joining a second community by changing how we handle custom URIs" or something like that) 
+- [ ] Be consistent. Let’s use “fix:” “improvement”, “breaking change:” and not “fixed” or “fixes”.
+- [ ] When possible, keep in mind the release notes style guide when writing changelog items; this will make assembling release notes easier. 

quiet-docs/docs/documentation/_category_.json

@@ -0,0 +1,7 @@
+{
+ "label": "Documentation Guide",
+ "position": 3,
+ "link": {
+ "type": "generated-index"
+ }
+}

quiet-docs/docs/documentation/overview.md

@@ -0,0 +1,50 @@
+---
+sidebar_position: 1
+title: Overview
+---
+
+# Overview of Quiet Documentation
+
+Quiet uses [Docusaurus](https://docusaurus.io/) to organize and serve documentation. Docusaurus can use Markdown or React on its pages and has an array of plugins, official and community built, that enable new and interesting behaviors.
+
+## Running Docusaurus
+
+Docusaurus comes with a set of `npm` commands for building/running the documentation site locally or in production. Convenience methods are provided in the root `package.json` for running these commands.
+
+### Running the Site Locally
+
+```
+npm run docs:start
+```
+
+This is the easiest method for testing/viewing logs locally as it doesn't require pre-compiling and will restart automatically on code changes.
+
+### Building the Site
+
+```
+npm run docs:build
+```
+
+This command will build the documentation site for serving locally/in production. This is only necessary if you are deploying the code or want to run the site in "production" form.
+
+### Serving the Site
+
+```
+npm run docs:serve
+```
+
+This will serve the built version of the documentation site locally.
+
+### Deploying the Site (DO NOT USE)
+
+```
+npm run docs:deploy
+```
+
+This will deploy the documentation site to github pages.
+
+
+:::caution
+Deploying the documentation site is not yet implemented so leave this alone for now!
+:::
+