⚠️ This document is a work in progress and might not contain everything that you expect in aCONTRIBUTING.md
file. If you already have some questions, comments or need help you can message us directly via https://wald.liebechaos.org.
Note: p2panda is a project maintained both by volunteers and people dedicated to it in various organisational forms. While we are working hard to improve the infrastructure, stability and code, please be respectful with the current contributors around this project which dedicate their limited time to make all of this work. ❤️
To create a safe environment for all contributors and members, p2panda is governed by our Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to contributors@p2panda.org.
The p2panda Handbook has a /specification
folder containing the official protocol specification formatted as Markdown files. To contribute to the specification for any part of the protocol, the following process takes place:
1. Jam Phase
- Post your idea for the protocol as a GitHub issue in this repository.
- We use issues to collect uncomplete ideas that still need time, discussion and feedback. Some of them might never be part of the official specification but it can be nice to keep an idea somewhere for someone or something else. Issues can be discarded and don’t need to follow a strict form.
- Each issue is assigned to an user which then serves as the facilitator of the idea, this person edits the issue description, others can comment below the issue to discuss it and give feedback at any time.
- Issues may be tagged with labels. They help to get an overview of which ideas are out there for a given area of the p2panda project.
2. Specification Phase
- Once the facilitator feels that the idea has reached some maturity, they can write it down more formally by adding a Markdown file inside the
./website/docs/specification
folder. - Create a GitHub Pull Request (PR) with your contribution. PRs serve writing and reviewing the final specification.
- Similar to issues the person assigned to the PR is the facilitator, they edit the proposed specification and guide the process of developing the idea. Everyone may discuss the PR in the comments section.
- Move your PR from Draft into Ready to be merged status as soon as you're ready to move to the review and merge phase described below.
3. Review and Merge Phase
- The PR can be reviewed by anyone.
- The p2panda project maintainers approve the PR and merge it.
- The specification is now part of the handbook!
4. Happy Phase! 🎆
- The newly released specification is announced by the facilitator in the #p2panda channel in rocket.chat.
Requirements
- NodeJS v18 and npm v8 (recommended install via a Node version mananger like
n
ornvm
) - Rust 1.63 (stable) (install via
rustup
) - wasm-bindgen
- wasm-opt
1. Build p2panda-js
- Clone the
p2panda
repository viagit clone https://github.com/p2panda/p2panda.git
and move into thep2panda-js
folder inside of it - Run
npm install
to install all dependencies - Run
npm run build
to compile WebAssembly and bundle the JavaScript package - Run
npm link
to locally link to thep2panda-js
package. Now you can use it somewhere else!
2. Run aquadoggo
node
- Clone the
aquadoggo
repository viagit clone https://github.com/p2panda/aquadoggo
- Run
cargo run
inside of it. This will start a locally running node on your machine under http://localhost:2020
3. Build your p2panda project
- You can refer to the latest
p2panda-js
version by linking to the package you've compiled in the steps above. Runnpm link p2panda-js
to use it inside of the project you're working on
-
Imports are grouped by: 1.
std
, 2. external crates, 3.crate
4.super
.use std::collections::BTreeMap; use rstest::rstest; use crate::hash::Hash; use crate::operation::OperationId; use crate::test_utils::fixtures::random_hash; use super::DocumentId;
-
Prefer using
crate
imports oversuper
, except intests
modules where you import something from the same file.This helps reducing mental overhead when switching a lot between files plus you can copy & paste import lines easier between files without changing the paths.use crate::hash::Hash; use crate::document::DocumentViewId; struct TheThingImTesting; #[cfg(test)] mod tests { use super::TheThingImTesting; }
-
Newlines are useful to structure your code into logical blocks and make it easier to follow it.
let some_thing = im_initialising_it(); let some_other_thing = more_initialisation(); let result = do_request(&some_thing, &some_other_thing).await?; assert_eq!(result, 42);
-
Code does not explain itself sometimes, give it a comment!
// The queue is empty, but this node has dependencies missing then there // is either a cycle or missing nodes. return Err(GraphError::BadlyFormedGraph);
-
Whenever you
unwrap
, explain why in a comment.// We unwrap here because it would be bad manners to inspect a present. trojan_horse.unwrap();
-
If you selectively disable clippy rules for your code add a comment to explain why.
// The consumer for this method will be implemented as part of [link to issue] #[allow(dead_code)] pub fn future_functionality() {
-
We write documentation for everything, struct members, methods, modules, etc.
-
Doc-Strings appear before attributes.
/// Valid field types for publishing an application schema. #[derive(Clone, Debug, PartialEq)] pub enum FieldType { // ... }
-
Avoid nesting imports.
// Wrong use thing::from::{ here::{ but::actually { ThisThing, AndThatThing, } }, and_here::{ HereAsWell, } }; // Correct use thing::from::here::but::actually::{ThisThing, AndThatThing}; use thing::from::and_here::HereAsWell;
-
We try to write in British English, but don't worry if you're not a native speaker.
- "Materialisation" instead of "Materialization" - "Decentralisation" instead of "Decentralization" - ...
-
Module-level docstrings are not followed by a newline.
//! Create, sign, encode and decode [`Bamboo`] entries. //! //! Bamboo entries are the main data type of p2panda. Entries are organised in a distributed, //! single-writer append-only log structure, created and signed by holders of private keys and //! stored inside the node database. //! //! [`Bamboo`]: https://github.com/AljoschaMeyer/bamboo mod decode;
-
Every file needs a license header:
// SPDX-License-Identifier: AGPL-3.0-or-later
. -
Make
cargo clippy
andcargo fmt
happy.