Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
300 lines (238 sloc) 14.6 KB

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

  1. Code of Conduct

  2. Help! I don’t want to read this whole thing, I just have one question. 🔎

  3. How Can I Contribute?

    1. Reporting Bugs
    2. Suggesting Enhancements
    3. Pull Requests
  4. Styleguides

    1. Git Commit Messages
    2. JavaScript Styleguide
    3. Code Documentation Styleguide

Code of Conduct

This project and everyone participating in it is governed by the Lisk Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to info@lisk.io.

Project License

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 version.

Pull Requests

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:

  1. Fork the repo.
  2. 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 master.
  3. Add tests to the code you have contributed! All new code must come with complete test coverage.
  4. End all files with a newline. In general, your code should conform to the rules listed in the .editorconfig file. 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.
  5. Ensure the test and linting suites pass. Follow the JavaScript styleguide from Airbnb with the lisk extension.
  6. Format your code using Prettier. This can be performed manually with npm run format.
  7. Submit a pull request via GitHub. Include issue numbers in the PR title, at the end with: Description - Closes #IssueNumber.
  8. 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.

Reporting Bugs

This section guides you through submitting a bug report for Lisk Core. Following these guidelines helps maintainers and the community understand your report 📝, reproduce the behavior 💻 💻, and find related reports 🔎.

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

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.

Suggesting Enhancements

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 📝 and find related suggestions 🔎.

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.

Styleguides

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: :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

JavaScript Styleguide

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
@class Describes the constructor of a class.
@event Describes an event, that the app is listening to.
@example If convenient, provide an example.
@func Only if JSDoc does not recognize the code as a function, but it is one.
@link Adds internal or external inline links.
@memberof Describes child-parent hierarchies. Usable for code tagged as @class or @namespace.
@module When a module is exported and it is not a @class.
@namespace Describes a parent folder or object.
@param Required for each parameter of a function.
@private For private functions.
@property Describes the property of an object.
@requires Describes the modules required by a class or module.
@returns Required for all functions with an explicit return statement.
@see Adds additional information, e.g. about the parent.
@throws When an error can be thrown.
@todo If there are open todos for the following code.
@typedef 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)

You can’t perform that action at this time.