polyproto-dot-org

Home of the polyproto protocol and its specification documents. PURRs should be submitted here!

Website

This website is built using Docusaurus, a modern static website generator.

Submitting a change request

There are two ways to submit change requests to the polyproto specifications:

polyproto Update & Revision Request (PURR)

A PURR is essentially a pull request changing the polyproto specification. Opening a pull request that changes the polyproto specification will result in a unique PURR identifier being assigned to that pull request. To avoid duplicate and pointless work, it is recommended to open an issue about the proposed change instead, where the change is outlined and can be discussed before the spec writing begins.

Numbering scheme

PURRs are labeled as follows: PURR-[YYYY]-[NNNN], where:

• PURR: The literal string "PURR"
• YYYY: The current calendar year
• NNNN: Variable-length numerical digits, starting at 4 digits and increasing in length as more capacity is needed in a calendar year. The first PURR in a given calendar year is assigned the number 0001. After 9999, the next valid set of digits is 10000, with 100000 being the next valid digit after 99999, and so on. This number increases by "1" for every PURR filed in the current calendar year. This number can only increase, never decrease.

Polyproto Amendment Workflow (PAW)

If a PURR has been accepted and merged, a polyproto Amendment Workflow (PAW) will be started to integrate that change into the rest of the software and documentation ecosystem managed by this organization.

A PAW examines if and how a PURR affects the software and documentation we manage, and acts similar to an "epic" in that it tracks the integration of the PURR's changes throughout our ecosystem.

Opening an Issue

Opening an issue about a change you'd like to see is likely the easiest way to get that change seen and discussed. If the change is considered good and fitting for the given protocol specification document, a PURR can be opened for it.

Development Setup

Install the yarn package manager, or use nix and the provided flake.nix. To install the dependencies, run:

yarn

A local live server can be started with

yarn start

Most changes are reflected live (through hot-reloading) without restarting the server.

Pre-commit Hooks

This project uses pre-commit hooks to ensure code quality and uniform formatting. To set up pre-commit hooks:

1. Install pre-commit:

   pip install pre-commit
   

   Alternatively: If you are using the nix flake and the provided development environment, you should already have pre-commit installed.

2. Install prettier and dev-dependencies:

   yarn install
   

3. Install the git hooks:

   pre-commit install
   

The pre-commit hooks will automatically:

• Format Markdown and MDX files using Prettier
• Lint Markdown files using markdownlint
• Check for common issues like trailing whitespace and file endings

You can manually run the checks on all files:

pre-commit run --all-files

Build

yarn build

This command generates static content into the build directory and can be served using any static content hosting service. Additionally, the build process runs some Docusaurus-specific lints, which will also be checked for in CI.

Logo

The polyproto logo was designed by the wonderful antidoxi. The polyproto logos provided in this document are not covered by the license covering the rest of this project.

🏳️‍⚧️ Trans rights are human rights. Be gay, do crime!