contributing.md

Contribution Guidelines

• We use master as the integration branch. All pull requests must pass CI to get merged. I don’t expect it to be perfectly stable until some time so if for some reason something is broken in master or in CI and you know how to fix it, please do, it would same time for everyone.
• Don’t use long-running branches, try to merge things to master frequently, even when features are not complete. It makes things easier to review PRs and identify possible breaking changes. It’s not a hard rule and obviously depends on each case, but I think trying to merge branches at least once a week should be a good start.
• We’re using ESLint (https://eslint.org/) for JS best practices and Prettier (https://prettier.io/) for code formatting. Most IDEs should have integrations for these.
• JS being a dynamically typed language, we’re using Flow (https://flow.org/) for static type analysis. It might be burdensome sometimes and display rather cryptic error messages but please take some time to really go through its docs and understand how it works, it is very good at preventing possible runtime errors that would be hard to catch otherwise.
• For unit tests we are using Jest (https://jestjs.io/). I guess people have different opinions about what should go in units tests or not, so for now I think we can treat them as covering “things you don’t want other people to break”. We already have a large code-base and it shouldn’t be expected that anyone is fully aware of how everything works, so if someone breaks a feature you built and wasn’t covered by tests, it’s on you not them.
• Not everything should necessarily be in the js-mainframe repository. Most low-level logic such as handling JSON-RPC communication and cryptographic primitives is part of the js-tools repository, and the Swarm APIs and provided by Erebos. Eventually any logic that is not “Mainframe-specific” could be extracted to specific libraries, so that most of the logic in js-mainframe can be about wiring discrete pieces together in a coherent way. That said, this should be seen more as an ongoing “constant refactoring” pattern happening over time when seen relevant rather than a hard rule, don’t hesitate to start implementing the necessary logic for the features you need directly in js-mainframe at first, and then we can revisit where this logic should live.
• Before undertaking possibly large changes, please discuss with @howleysv and @PaulLeCam first so we can have an idea how these changes can impact the overall architecture, and then with Adam or I if the implementation is not trivial so we can try to figure out the best way to include these changes in the existing code-base.