ssb-js/ssb-js

Governance repository for the SSB-JS organization.

SSB-JS

⚠️ On May 2022, staltz, arj03 and mixmix (the only active members of ssb-js) decided to disband SSB-JS and move the repos back to SSBC. See a thread on SSB about the decision: %1NtrLWhxeuHr03NRoyriInzLSvPVn7fkiZ6C61PPhVo=.sha256.

The following text reflects the old rules for this GitHub org.

---

History

The SSBC is a structureless organization that doesn't adaquately serve the needs of participants in the Scuttlebutt ecosystem. The SSB-JS namespace is an attempt to build a healthy organization with reliably maintained software.

Healthy organizations have healthy governance, which requires decision-making and conflict-resolution practices available to all members. Most decisions should be made organically from the bottom up, but decisions that change the SSB-JS organization require discussion and consent.

Projects

• Chloride
• Multiserver
• MuxRPC
• SSB-Keys
• SSB-Ref
• SSB-Validate
• Secret-Stack

Maintainers

2020

• @arj03 -- Multiserver, SSB-Ref, and SSB-Validate
• @christianbundy -- Multiserver, MuxRPC, and SSB-Validate
• @mixmix -- Chloride, SSB-Ref, and Secret-Stack
• @soapdog -- MuxRPC and SSB-Keys
• @staltz -- Chloride, SSB-Keys, and Secret-Stack

Process

• The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Repositories

• There MUST be one Git repository for governance and one for each project.
• The 'SSB-JS namespace' refers to the SSB-JS organizations on GitHub and npm.
• The SSB-JS namespace MUST be read-only unless specified otherwise.
• Repositories and build artifacts must be hosted in the SSB-JS namespace.
• Repositories MUST have a 'main' branch.
• Repositories SHOULD NOT have any other branches.
• Repositories MUST allow project discussions via issues.
• Repositories MUST allow patch proposals via pull requests.
• The latest commit on the 'main' branch SHOULD always be versioned and released on npm.

Projects

• Projects SHOULD be written in JavaScript or TypeScript.
• Projects SHOULD have internally consistent code style.
  • Projects SHOULD follow the default Prettier rules.
  • Projects SHOULD follow the recommended ESLint rules.
• Projects SHOULD have documentation of all public APIs.
• Projects SHOULD have automated tests for all target platforms.
• Projects SHOULD have internally consistent contribution guidelines.

Contributors

• 'Contributors' are anyone who participates in a project.
• Contributors MUST read a project's CONTRIBUTING.md before submitting a pull request.
• Contributors interested in seeing their pull requests merged SHOULD update their pull requests when maintainers identify blocking concerns.
• Contributors MUST aim to foster an open, welcoming, and harassment-free space.
• Contributors SHOULD recommend changes in the form of patches.
• Contributors who want to be maintainers SHOULD participate consistently and often.

Maintainers

• 'Maintainers' are contributors trusted to steward a project and vote.
• Maintainers MUST have the 'owner' role on GitHub and NPM.
• Maintainers MUST have 2FA enabled on GitHub and NPM.
• Maintainers SHOULD communicate in a project's CONTRIBUTING.md how contributors can get started and what is expected in a pull request.
• Maintainers SHOULD communicate in the project's CONTRIBUTING.md what types of changes in a project pull request are frequently blocked from merging.
• Maintainers SHOULD review and merge outstanding patches for the project they maintain.
• Maintainers MAY review and merge patches for other projects.
• Maintainers SHOULD NOT merge their own pull requests.
• Maintainers SHOULD aim to make contributing a fun and simple experience.
• Maintainers SHOULD merge project pull requests in a fast and friendly manner.
• Maintainers SHOULD NOT suggest non-blocking changes on project pull requests.
• Maintainers SHOULD close pull requests that are outdated in comparison to the main branch.
• Maintainers SHOULD invite high-quality contributors to become maintainers.
• Maintainers SHOULD remove anyone who fails to apply this process.

Governance

• The governance repository MUST be hosted at https://github.com/ssb-js/ssb-js.git.
• Roles and repositories in the SSB-JS namespace MUST match the governance repository.
• Activity in the SSB-JS namespace MUST apply the process from the governance repository.
• Patches to the governance repository MUST NOT be merged unless the latest commit on a pull request is approved by ⅔ of active maintainers.
• If there are no active maintainers because their term expired, the previous cohort should be considered 'active maintainers' for the purposes of voting.
• Maintainers MUST merge governance patches that are approved.
• Maintainers MUST NOT merge governance patches that are not approved.

ssb-js's Issues

Contributing.md: org wide or per-repo?

We put in a rule that every repo should have a CONTRIBUTING.md file, but so far none of the repos have this. So this is a good moment to ask ourselves: do we want the same ways-of-working (with git, with PR expectations, etc) everywhere, or do we allow it per-repo?

Let's talk on a call instead of github

I'm starting to see chaffed by these issues and PRs ... I guess it's the opening phase and no avoiding it.
But I would personally rather see some faces and hear voices to ground this conversation.

We can talk about some details sure, but I just wanna talk about how people are and what they care about. We can always continue thread here.

and tags pushed to github

and tags pushed to github

Originally posted by @mixmix in #9 (comment)

2FA required for all members

@arj03 could you enable 2FA for your GH account?

Allocate study time for maintainers

I think it would be good if we could allocate some study time for maintainers. I don't necessarily mean that that time is covered by any grant (but if it could, it would be great), what I want is to be able to pair someone new to a module with someone who is more versed in that module and study for a bit.

I want all maintainers to be comfortable with the stack and ssb protocol before they are expected to merge complex patches. We can consider this a pre-warm routine for the launch of ssb-js.

Task automation with ssb-scripts

ssb-scripts

Create a JavaScript application or series of scripts bundled in a package that allows us to perform and automate common tasks across all the SSB applications.

Rationale

Keeping a consistent code style, linting rules, and toolchain selection is a challenging goal to achieve, and, in most cases, you could say impossible.

Having an independent package controlling all these elements will allow us to perform all these operations without adding extra work on the package developers and maintainers.

Rules and automation

The following is a list of the tools I consider we can use in all the SSB packages to keep a consistent feel in the code style and automate tasks like CI testing.

We can add more if we consider it necessary.

• Linting with ESLint
• Code formatting with Prettier
• Unit testing with Tape
• Package bootstrapping (optional)

How

ssb-scripts will add/replace some of the host’s package.log scripts, allowing the developer to run the tools directly from the host package.

	...
	"scripts": {
		"lint": "ssb-scripts --lint"
	},
	...

Inspiration

We can use a similar approach to the one used in React Scripts.

ToDo

• Create package and add the repository to ssb-js.

Merge commits disabled?

@staltz I went to merge your PRs in ssb-keys but it wouldn't let me -- it says that merge commits have been 'disabled for this repository'. Was that intentional? We don't have any rules against locking each other out of normal actions, but I'm surprised that I can't merge pull requests anymore.

Explicit maintainers and time limits

1. I would like to see at least 2 names next to each of these projects.
This will force us to try out what that feels like, and also prevent us from accidentally slipping into the state we are in with SSBC > where there are m owners, n modules, and heaps of PRs sitting around and falling through cracks.

2. I would like to put a time limit on this

We MUST remove and manually add back ALL maintainers and ALL projects at Jan 31st 2021. All commitments after that > point will be contained in pull-requests which follow.

(see %BhaX8GGC+jOYIXDx6WC18+UTAkjmC4qAeNuWrdGQUQ8=.sha256 where I expand on why I'm keen on this)

Originally posted by @mixmix in #1 (comment)

"vote" language

what is "vote" - do you mean signal approval for changes to governance?

Originally posted by @mixmix in #11 (comment)

Code of Conduct

We need a code of conduct, preferably a separate .md file in this governance repo. And then we need to add a rule that every Maintainer and Contributor MUST adhere to it.

Code style

This is one of my least favorite conversations on the planet, but I think we should have it once in one place instead of having the same conversations in bits and pieces all over the modules. What are the minimum 'code style' standards that we want to enforce? Here are my preferences:

• I'd prefer to use popular convention instead of inventing our own.
• I'd prefer to use boring conventions so that our code is familiar and predictable.
• I'd prefer to separate concerns so that our formatting (syntax) and logic (semantics) can be changed independently.

I'd suggest:

• ESLint:Recommended for semantics -- Most/all modern linters use ESLint under the hood, and all of the most common + boring + uncontroversial rules have been added to a 'recommended' ruleset that comes with ESLint. This is the smallest and most agreeable ruleset I'm aware of, and applying it to our modules has been quick and easy.
• Prettier for syntax -- 41 times more npm downloads than StandardJS, 18x more GitHub dependents, formats dozens of languages (Markdown, JS-in-Markdown (!), CSS, GraphQL, etc), and produces an uncontroversial style that's boring and familiar enough for everyone.

I was originally thinking that maintainers could just use their own code style, but I doubt that we want to change code style every 6 months or whatever, so maybe we should just have a default code style so that we can decide on and then move on to actually-interesting problems. Anyone have any big blocking concerns about ESLint + Prettier, or suggestions for more-boring style guides? My goal is to hit the sweet point between 'useless' and 'controversial'.

some people are owners, some people members

in the ssb-js some people are owners and others members.
I assume that was a mistake?

How and when to do releases

One of the things I liked about SSB in the beginning was that the main branch as always pushed to npm more or less after a merge. This meant that it was quite easy to get small changes in and pushed out quickly. It might also have been one of the problems that made so many PRs go stale, as nobody wanted to be the one pushing these changes to npm and thus face the consequence of what happens if the stuff doesn't work. Not sure.

I have noticed that some modules lately have started to accumulate changes that are not published.

What do people think? And should this be something for the ssb-js to take a stance on, or should it be left to the maintainer, it seems to me that with such a tight system of modules, it would make most sense to have 1 rule for the whole org?