Contributing to Lisk Core
First off, thanks for taking the time to contribute!
The following is a set of guidelines for contributing to Lisk Core, which are hosted in the LiskHQ Organization on GitHub. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
Table Of Contents
Code of Conduct
Every repository within LiskHQ comes with a LICENSE file. Please read it carefully before committing your code to one of the repositories.
Help! I don’t want to read this whole thing, I just have a question.
Lisk is an open-source decentralized project, there are many ways and platforms to get help. These are some of them:
If you prefer to chat with LiskHQ and other developers directly:
- Join the LiskHQ Gitter
- Even though Gitter is a chat service, sometimes it takes several hours for community members to respond — please be patient!
How Can I Contribute?
LiskHQ uses GitHub as its sole source of truth. Everything happens here. Lightcurve employees who contribute to Lisk are expected to do so in the same way as everyone else. In other words, this document applies equally to all contributors.
master is unsafe for production use
We will do our best to keep
master in good shape, with tests passing at all
times. But in order to move fast, we will make API changes that your application
might not be compatible with. We will do our best to communicate these changes
and always version appropriately so you can lock into a specific, stable
In case you’ve never submitted a pull request (PR) via GitHub before, please read this short tutorial. If you’ve submitted a PR before, there should be nothing surprising about our procedures for Lisk.
Before submitting a pull request, please make sure the following is done:
- Fork the repo.
- If you are creating a pull request that addresses a specific issue, take a
look at the projects that issue is a part of (in the right-hand sidebar).
Most issues will be a part of a project for a specific version, such as
"Version 1.0.0". If this is the case, create your branch from the relevant
version branch, e.g.
1.0.0, and submit your pull request against that branch as a base. Otherwise, create your branch from
- Add tests to the code you have contributed! All new code must come with complete test coverage.
- End all files with a newline. In general, your code should conform to the
rules listed in the
.editorconfigfile. There are plugins for most editors/IDEs to do this for you automatically. Update the README for the changes that adhere to your new code.
- Format your code using Prettier. This can be performed manually
npm run format.
- Submit a pull request via GitHub. Include issue numbers in the PR title, at
the end with:
Description - Closes #IssueNumber.
- Check that Jenkins CI tests pass (pull request turns green). First time contributors will need to wait for a trusted team member to start Jenkins CI on a Pull Request.
This section guides you through submitting a bug report for Lisk Core.
Following these guidelines helps maintainers and the community understand your
Before creating bug reports, please check this list as you might find out that you don’t need to create one. When you are creating a bug report, please include as many details as possible. Fill out the required template, the information it asks for helps us resolve issues faster.
Note: If you find a Closed issue that seems like it is the same thing
that you’re experiencing, open a new issue and include a link to the original issue in the body of your new one.
Before Submitting A Bug Report
- Check the FAQs for a list of common questions and problems.
- Determine which repository the problem should be reported in.
- Perform a cursory search to see if the problem has already been reported. If it has and the issue is still open, add a comment to the existing issue instead of opening a new one.
How Do I Submit A (Good) Bug Report?
Bugs are tracked as GitHub issues. After you’ve determined which repository your bug is related to, create an issue on that repository and provide the following information by filling in the template.
Explain the problem and include additional details to help maintainers reproduce the problem:
- Use a clear and descriptive title for the issue to identify the problem.
- Describe the exact steps which reproduce the problem in as many details as possible. When listing steps, don’t just say what you did, but explain how you did it. Make sure to erase sensitive information from the configuration or details you are passing - NEVER SHARE YOUR SECRET PASSPHRASES OR PRIVATE KEYS.
- Provide specific examples to demonstrate the steps. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you’re providing snippets in the issue, use Markdown code blocks.
- Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior.
- Explain which behavior you expected to see instead and why.
- Include screenshots and animated GIFs which show you following the described steps and clearly demonstrate the problem. You can use this tool to record GIFs on macOS and Windows, and this tool or this tool on Linux.
- If the problem wasn’t triggered by a specific action, describe what you were doing before the problem happened and share more information using the guidelines below.
Provide more context by answering these questions:
- Did the problem start happening recently (e.g. after updating to a new version of Lisk Core, Lisk or any other repository) or was this always a problem?
- If the problem started happening recently, can you reproduce the problem in an older version of Lisk Core? What’s the most recent version in which the problem doesn’t happen? You can download older versions of Lisk Core from [the releases page](https://github.com/LiskHQ/Lisk Core/releases).
- Can you reliably reproduce the issue? If not, provide details about how often the problem happens and under which conditions it normally happens.
This section guides you through submitting an enhancement suggestion for
Lisk Core, including completely new features and minor improvements to
existing functionality. Following these guidelines helps maintainers and the
community understand your suggestion
When you are creating an enhancement suggestion, please include as many details as possible. Fill in the template, including the steps that you imagine you would take if the feature you’re requesting existed.
How Do I Submit A (Good) Enhancement Suggestion?
Enhancement suggestions are tracked as GitHub issues. After you’ve determined which repository your enhancement suggestion is related to, create an issue on that repository and provide the following information:
- Use a clear and descriptive title for the issue to identify the suggestion.
- Provide a step-by-step description of the suggested enhancement in as many details as possible.
- Provide specific examples to demonstrate the steps. Include copy/pasteable snippets which you use in those examples, as Markdown code blocks.
- Describe the current behavior and explain which behavior you expected to see instead and why.
- Include screenshots and animated GIFs which help you demonstrate the steps or point out the part of Lisk Core which the suggestion is related to. You can use this tool to record GIFs on macOS and Windows, and this tool or this tool on Linux.
- Explain why this enhancement would be useful to most Lisk and Lisk Core users.
- Specify which version of Lisk and Lisk Core you’re using.
- Specify the name and version of the OS you’re using.
Git Commit Messages
- Use the present tense ("Add feature" not "Added feature")
- Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
- Limit the first line to 72 characters or less
- Reference issues and pull requests liberally after the first line
- Consider starting the commit message with an applicable emoji:
:seedling:when adding a new feature
:bug:when fixing a bug
:books:when adding or updating documentation
:nail_care:when making changes to code style (e.g. lint settings)
:recycle:when refactoring code
:fire:when removing code or files (including dependencies)
:racehorse:when improving performance
:white_check_mark:when adding or updating tests
:construction_worker:when updating the build process
:bowtie:when updating CI
:house:when performing chores
:new:when adding a new dependency
:arrow_up:when upgrading a dependency
:arrow_down:when downgrading a dependency
:back:when reverting changes
On Lisk we are using Prettier and ESLint. Our ESLint style expands Airbnb’s style settings and expresses some opinions not covered by Prettier’s formatting concerns. You can get more details here: https://github.com/LiskHQ/eslint-config-lisk-base
Code Documentation Styleguide
For code documentation, we use JSDoc. With JSDoc you can generate a static HTML documentation site. To build the documentation site, run the following command:
npm run docs:build
To host the documentation site (e.g. for easy access via a browser), use the following command:
npm run docs:serve
If you add or change code, please always provide or update the corresponding code documentation.
Always mandatory: A general description of what the code is doing. If tags follow, leave a blank line between the description and the tags.
Tags to use:
|Tag||When to use|
||Describes the constructor of a class.|
||Describes an event, that the app is listening to.|
||If convenient, provide an example.|
||Only if JSDoc does not recognize the code as a function, but it is one.|
||Adds internal or external inline links.|
||Describes child-parent hierarchies. Usable for code tagged as
||When a module is exported and it is not a
||Describes a parent folder or object.|
||Required for each parameter of a function.|
||For private functions.|
||Describes the property of an object.|
||Describes the modules required by a class or module.|
||Required for all functions with an explicit return statement.|
||Adds additional information, e.g. about the parent.|
||When an error can be thrown.|
||If there are open todos for the following code.|
||For defining custom types to be used in other JSDoc blocks.|
For examples please have a look in the existing code.
These contribution guidelines were inspired by and are based on Atom’s contribution guidelines. They were modified for the purposes of this repository. https://github.com/atom/atom/blob/master/CONTRIBUTING.md - Copyright (c) 2011-2017 GitHub Inc. (MIT)