Skip to content

Latest commit

 

History

History
145 lines (92 loc) · 5.67 KB

contributing.md

File metadata and controls

145 lines (92 loc) · 5.67 KB
Raw

Contributing

Hermies watering

This project is open commons that anyone can improve.

We welcome all contributions, such as but not limited to:

  • code
    • bug reporting
    • features
    • tests
    • peer review
    • protocol design
  • operations
    • pub server hosting
  • design
    • project artwork
    • user testing
    • newbie first impressions
    • real-world use cases
  • storytelling
    • blogs
    • talks
    • documentation
  • facilitation
    • community organizing (meetups)
    • group collaboration
    • conflict resolution

If you contribute enough, you'll be invited to join the project members.

We aim for autonomous solving of collaborative problems with a common vision.

Hosting a Pub server

The easiest way to start hosting a Pub server is to use

Contributing Code

To understand what code is in the Scuttlebutt ecosystem and how the modules assemble together, see the "Modules" page.

To get started developing Patchwork (the primary user interface), first follow the instructions to build from source.

To get started developing ssb-server (the data server), see the "Introduction to Using Scuttlebot" guide.

Native Build Dependencies

The main build dependecies are libsodium and leveldb.

They should be automatically built using a C++ compiler on npm install as we use chloride and level, respectively.

Tests

If contributing to a low-level module, please include tests.

Code Style

The default recommended code style is standard.

If existing code is in another style, please respect the code style. :)

Licenses

Most code is licensed under a permissive license (MIT / ISC), while other code like Patchwork is licensed under a copyleft license (GPL / AGPL).

Making a Good Pull Request

Goal: be as easy (for the maintainer) to merge as possible. (This means it can get merged faster.)

Explain what you are trying to do

All pull requests should have a description explaining what their goal is. Stating a goal helps the maintainer evaluate whether the proposed change is the simplest way to achieve that goal. If the PR is just code then it is much harder to figure out the original intention of that code.

Document what sort of change it is (patch, feature, breaking change)

What type of change you are proposing affects what you need to communicate.

The main types of changes are:

  1. Patches
  2. Features
  3. Breaking changes

Patches

Bug fixing. Documenting this is easy. Explain the problem you intend to fix, and ideally also add a test case that reproduces the problem you found.

Features

Adding new features is more challenging. Now your PR needs to explain the use-case. Consider the following when writing your PR:

  • Why do you want this feature?
  • What problem are you trying to solve with it?

When you make a pull request you are not just making a change to the code, you are also making a request to the maintainer: you are asking that they acknowledge this change and give this use their blessing.

When possible, new modules are better than a PR, and then you can ask the maintainer to link to your module's README from their README.

Code style is considered but not usually a deal breaker for a PR, since code style change always change later. However, the API style is very important because breaking changes require changes throughout dependent modules.

For some really popular modules that a lot of code depends on, new features will require a very significant justification of why they are needed.

Breaking Changes

Breaking changes are rare. However, if you must make a breaking change, one that restricts the API to a more minmal set is most likely to get merged. Expect a proposed breaking change to get lots of discussion.

Contributing Documentation

While over time we have scattered documentation around:

Our intention is to combine these sources and have this handbook (ssb-handbook) be the new location for all documentation relating to Scuttlebutt.

You can clone, build, and serve this handbook with gitbook locally.

The SUMMARY.md is the manifest on which the compiled gitbook is based. Edit that if you want content in/out of the book.

Contributing With git-ssb

To use the public portal for the handbook code, browse to https://git.scuttlebot.io/%25lJsDWwnF4bDxHWYuSjw%2FbW37xg%2BsaF8WtPZYZsefKj0%3D.sha256.

To use your local scuttlebot server to clone the handbook code:

npm install git-ssb -g
git clone ssb://%lJsDWwnF4bDxHWYuSjw/bW37xg+saF8WtPZYZsefKj0=.sha256 ssb-handbook

cd ssb-handbook
npm install
npm start

To contribute to the handbook code, make a pull request with

git ssb pull-request

Contributing with GitHub

Our public GitHub repository is at ssbc/ssb-handbook

Feel free to make an issue or pull request here if you see something that needs doing.