While the following guidelines are not an absolute requirement, writing your code by these standards will ensure greater compatibility with the ARK Ecosystem and increases the likelihood your pull request will be accepted.
Repositories across an organization should have a consistent basic structure to make it easy to find everything across different repositories.
At a bare minimum a repository should contain the following:
- README.md - Should contain at least a description, installation instructions and a contact address for security issues.
- LICENSE - Should contain the software license of the project, commonly the MIT License for open-source projects.
- .editorconfig - Should contain a configuration that is enforced by everyone's editor if an appropriate plugin is installed.
- .gitignore - Should contain a list of files and directories that should not be committed with
- .circleci/config.yml - Should contain a configuration for CircleCI to run tests.
When a new repository is created for a project, the first thing you should do is create a
develop branch and set it as default. This will indicate to developers that this project is not stable yet. This branch should be used until the initial implementation is done, and merged to
master without squashing.
master should then be set as the default branch.
Once the initial implementation is done and merged, only squash merging should be enabled and all future PRs should be squashed with meaningful commit messages.
When working on any project all pull-requests must be squashed.
The goal of doing so first and foremost is to keep PRs small and focused on a single issue. If you think to yourself: "all my hard work and organized commits are going to be lost", then your PR is most likely out of scope and trying to solve more then one issue at a time which means you should split it up into multiple PRs that are meaningful even after being squashed.
Another benefit of squashing is to have a clean & flat git history which allows to easily blame changes without having to go through 100 commits to finally reach what you were looking for.
We only care about the net effect of the pull-requests, i.e. "feat: wallet integration". We don't care about the 30 commits of "bugfix, added, removed, refactored". We want a clear and concise history without any noise.
How to Label and Organize GitHub Issues & Pull Requests
To make everyone's life easier when looking for issues or pull requests of specific types, priority or severity it is important to make proper use of labels so it is possible to identify the status and importance without having to look into it.
Type: Buglabel always has to be combined with a
Severity: *label to indicate how severe the problem caused by the bug is and how many users are affected by it. The combination of those determines how fast the bug needs to be fixed.
- Bounty tiers need to be assigned before a pull request is merged. If no tier is assigned or is assigned to a team member the ARKEcosystem Bot will comment in the affected issue.
- For issues that are tasks a
Difficulty: *label should be assigned to provide developers a sense of how much work it will be.
Complexity: *labels should never be assigned manually as the ARKEcosystem Bot will evaluate the complexity of a pull request and assign a label.
- Custom reward at the discretion of the team, for large projects or changes.
- Awarded for big features, important fixes or significant improvements. This is valued at 100 USD.
- Awarded for performance, minor features or substantial documentation changes. This is valued at 50 USD.
- Awarded for code refactoring, moderate docs changes or full translations. This is valued at 25 USD.
- Awarded for adding test coverage or resolving small bugs. This is valued at 10 USD.
- Awarded for small documentation updates or minor code refactoring. This is valued a 5 USD.
- Awarded for typos, text corrections, dependency updates, etc. This is valued a 1 USD.
- Needs specialized, in-depth review.
- More than 256 lines changed.
- Less than 256 lines changed.
- Less than 64 lines changed.
- The issue requires an extensive understanding of the code base.
- The issue requires an advanced understanding of the code base.
- The issue requires a basic understanding of the code base.
- The issue doesn't require any specific knowledge about the code base.
- The issue or pull request affects the development environment.
- The issue or pull request affects the production environment.
- The issue or pull request affects the test environment.
- The issue or pull request affects the continuous integration environment.
- The issue or pull request affects users on Windows.
- The issue or pull request affects users on Linux.
- The issue or pull request affects users on Android.
- The issue or pull request affects users on macOS.
- The issue or pull request affects users on iOS.
- The issue or pull request will affect all users.
- The issue or pull request will affect most users.
- The issue or pull request will affect roughly half of users.
- The issue or pull request will not affect most users.
- The issue is blocking an upcoming release.
- The issue causes data loss, crashes or hangs processes, makes the system unresponsive, etc.
- The issue reports incorrect functionality, a confusing user experience, etc.
- The issue reports cosmetic items such as formatting, spelling, colors, etc.
- The pull request could not be merged because it did not get any updates in a timely fashion.
- The issue is legitimate, but it is not something the team is currently able or willing to work on.
- The issue has been resolved.
- A code owner has approved the pull request.
- A member has approved the pull request.
- A collaborator has approved the pull request.
- A contributor has approved the pull request.
- The proposed solution has been accepted.
- The issue is not assigned to anyone and available to be worked on.
- The issue or pull request is being worked on.
- The issue or pull request is not being worked on for the time being.
- The pull request is in need of updates but there has not been a sufficient response.
- The pull request is blocked from being merged for the time being.
- A developer of the team cannot reproduce the issue.
- The pull request was reverted after an initial merge.
Has Merge Conflicts
- The pull request cannot be merged because it has a merge conflict.
- The Circle CI build failed when running for this pull request.
- The issue needs more information before it can be verified and resolved.
- The issue needs more investigation before it can be verified and resolved.
- The issue or pull request needs a review by a developer of the team.
- The issue or pull request relates to a feature that needs test coverage.
- The pull request needs additional changes before it can be merged.
- The issue or pull request needs more discussion before it can be closed or merged.
- The pull request needs additional documentation before it can be merged.
- The issue or pull request is related to the test config, platform or setup.
- The issue or pull request is related to functional tests such as end-to-end or browser testing.
- The issue or pull request is related to integration tests between internal or external elements.
- The issue or pull request is related to unit tests for testing individual elements.
- The issue is a request for new functionality.
- The issue or pull request is related to an upcoming release.
- The pull request updates dependencies or configuration files.
- The issue or pull request relates to performance.
- The pull request improves or enhances an existing implementation.
- The issue or pull request is a duplicate of another feature request or bug report.
- The issue is a bug report, but the behavior is intended.
- The issue or pull request documents or introduces a breaking change.
- The issue relates to broken or incorrect behavior.
- The pull request fixes an incorrect functionality or behavior.
- The issue is a bug that relates to functionality known to work in previous releases.
- The issue documents functionality that could expose private data or cause harm otherwise.
- The issue is a discussion about a generic topic.
- The issue or pull request relates to documentation.
- The issue contains information for users by a developer of the team.
- The issue is more of a question than a request for new features or a report of broken features.
- The issue is a request to set up third-party integrations or any general non-code related tasks.
Good First Contribution
- The issue appears to have a simple solution.
- The issue reports problems with the compliance of contribution guidelines or code standards.
- The issue is a weekly report of the latest activities.
Assigning Bounty Tiers Before Merging a Pull Request
Before a developer merges a PR, it is required to assign one of the seven bounty labels. Those labels will be used by the ARKEcosystem Bot to calculate bounty rewards and inform the contributors about those and other activities or requests.
Tier 1 - $100
Tier 1 pull requests cover substantial code changes that usually bring new functionality and have a higher impact on the codebase.
Examples of this include a new API endpoint, resolving structural issues that cause circular dependencies, or adding new bigger features to our codebase (an example would be settings page to the explorer, adding new indenticon package to the desktop wallet or a new small non-essential plugin in the Core).
Tier 2 - $50
This tier covers medium features and improvements to the codebase that bring in new functionality, have a big impact on the performance of the product or significant optimizations and refactors of the code.
An example would be optimizing some parts of the Core for improved performance of a specific function, implementing a medium, non-critical new feature in the desktop wallet or writing large documentation files that require an understanding of the ARK code.
Tier 3 - $25
These pull requests cover smaller refactors or optimizations of the code or small non-essential features.
An example of this would be reducing complexity or improving the performance of existing code, improving the readability of the code or writing new documentation files, full translations of the projects aka desktop wallet or mobile wallet.
Tier 4 - $10
Standard small tier pull requests that fix minor bugs or add a new test.
Examples of this include adding more test coverage for existing functionality or resolving small bugs that usually get reported by users.
Tier 5 - $5
Small documentation updates or improvements that don’t have much code or smaller refactors of the code.
Tier 6 - $1
The lowest tier is for items that don’t usually have much to do with the code, but rather, are considered cosmetics.
An example would be a typo, language corrections, grammar corrections, dependency update, link updates or broken links.
Tier 0 - Custom
If you want to work on much more significant changes or custom projects that you don’t think fit any of the above tiers contact us at firstname.lastname@example.org.
Some examples of what a custom tier 0 could cover — developing new modules for
core that bring in new functionalities (PoW module instead of DPoS), different voting systems, proxy voting, implementing AIPs …
Some issues will also have labels with custom (usually higher) values that you can take on. Labels on those issues will have a defined monetary value, so if you see these available you can request to take point on resolving them. Upon completion and review you will receive payment in ARK.