Goals of this repository
- To gather standards, patterns and workflows which we adopt, in order to provide a central source of truth regarding our “current thinking”, which can then be applied to individual Lisk projects as and when appropriate.
- To serve as a base for new projects.
When starting a new Lisk project, use this repository as a base. With a few
small customizations, you will have a skeleton project up and running in a few
minutes. The easiest way to bootstrap a new project is using the
curl --silent --user my_github_username "https://raw.githubusercontent.com/LiskHQ/lisk-template/master/bin/bootstrap.sh" | bash -ls my-fresh-lisk-project
If you have two-factor authentication enabled on your GitHub account, you will need to generate an access token rather than authenticating via curl. Having logged into GitHub using a browser, view the bootstrap script in the same browser. Click "Raw" to view the raw file. Then copy the full URL (including the access token) and run the following:
curl --silent "the_url_i_just_copied?token=remember_the_token" | bash -ls my-fresh-lisk-project
my_github_usernamein the first command should be replaced with your GitHub username. You will be prompted for your GitHub password.
- Watch out: some terminal applications automatically escape pasted strings, which may conflict with the quoting used in the examples above. If you get a 404 error and you've authenticated successfully with GitHub, check to see if the URL has escape characters which should be removed.
-loption tells bash to act as if it had been invoked as a login shell. If you use nvm as your Node.js version manager, then it will be used to set the correct version of Node.js when installing NPM dependencies.
my-fresh-lisk-projectshould be replaced with the name you’ve chosen for your new project.
If you would rather complete this process on your own, you should follow these steps:
- Clone the repository.
- Reinitialise git (by removing the
git initand committing everything into the initial commit).
- Find and replace all instances of
lisk-templatewith your project name (assuming the name of your project is the same as its GitHub namespace).
- Commit these customization changes.
More precise steps can be viewed in the
You will need to update the project description. Other fields will be given a sensible value but may need to be updated depending on the project.
Installed for your convenience are the following:
- Prettier for standard code formatting.
- ESLint plus various configs and plugins, to enforce additional rules beyond Prettier’s remit.
- Husky and lint-staged to help with running checks/builds before/after various git/NPM commands.
- Mocha, Chai and Sinon plus plugins for tests.
- nyc and Coveralls for coverage.
These can be removed as appropriate, along with the corresponding NPM scripts.
startwill run your source code using
babel-node, which is not performant but does not require transpilation.
formatwill format your source and test code using Prettier.
lintwill lint everything relevant with ESLint.
testwill run your tests and instrument your code using nyc. (With the initial setup this results in a failing test: the first step in TDD’s red-green-refactor process!)
test:watchwill watch for changes and rerun your tests.
test:watch:minwill do the same but using the
minreporter (useful if you just want to check if your changes break a test).
coverwill output a coverage report (differs based on the environment).
buildwill transpile your source code using Babel.
precommitwill format staged files and lint everything before you commit.
prepushwill lint and test before you push.
prepublishOnlywill run the
prepushchecks and the
buildcommand. Note: this is run automatically before publishing in NPM v5+ but must be performed manually in NPM 3 (the currently supported NPM version).
Documentation for contributors
Several files especially relevant for contributors can be found in the
CODE_OF_CONDUCT.mdwhich should probably be left as it is.
CONTRIBUTING.mdwhich will benefit from project-specific customization.
PULL_REQUEST_TEMPLATE.mdwhich may need to be adapted to your project.
- Additionally, in the root of the project is the
LICENSEfile, which should be left alone unless your project is being released under a different license. In this case the
licensefield of the
package.jsonfile should be updated as well.
- Source code should go in
src, test code should go in
- File and directory names should be
underscore_separatedfor best cross-file system compatibility. (I.e. not in camel case etc.)
- nyc output goes into
.nyc_output, and built files are put into a
distdirectory which is created when needed.
- Files you do not want to commit can be placed in
tmp(you will need to create these directories yourself).
The test directory has some configuration and setup files, and is otherwise
divided into a
specs directory and a
steps directory. The intention is for
specifications to contain implementation-neutral Mocha suites, and the
(reusable) steps to be implemented in the
steps directory. See this
blogpost for an introduction.
If this approach does not suit your project the structure can be replaced as necessary. However, the configuration and setup should probably be preserved. Helpful things in place include:
- Combining Babel, nyc and Mocha.
- Adding Chai’s
expectas a global, and initialising plugins.
Thenfrom mocha-bdd as globals.
sinonand a sinon
sandboxas globals, and resetting the sandbox after each test in a global hook (it is recommended to use the sandbox wherever possible to avoid manual resets).
This project assumes a standard CI setup on Jenkins. There are three Jenkinsfiles:
Jenkinsfilefor branches/PRs which lints, tests, reports coverage to Coveralls, and notifies GitHub.
Jenkinsfile.privatewhich checks branches/PRs for known vulnerabilities in the installed dependencies using Snyk if
package.jsonhas changed. The results should not be publicly viewable in Jenkins.
Jenkinsfile.nightlywhich checks the
masterbranch for vulnerabilities nightly. The results should also not be publicly viewable in Jenkins.
.snyk file configures Snyk.
In order to set up continuous integration for your project you will need to do the following:
- Modify the main Jenkinsfile to your requirements.
- Update your GitHub project settings to allow Jenkins to submit information.
- Set up the main Jenkins project, the private project, and the private nightly
project in the
- Add a Coveralls configuration file at
~/.coveralls.yml-lisk-templateon all Jenkins nodes that will be used to build lisk-template.
.editorconfigcan be used in combination with plugins for a wide range of editors/IDEs to ensure consistency of certain key syntax details.
.npmignoreensures that as little as possible is included when published to NPM. This may require adjustment.
- If the project is for a client, or otherwise will not be used as a library in
other projects, consider replacing
babel-polyfill(see the details section of the Babel Polyfill documentation).
- The official language for all Lisk projects is US English (although we may also support translations into other languages on a per-project basis).
Applying these standards
All of these standards should be applied with the specific project in mind. There might be good reasons to delay the application of some standard, or to avoid it completely. In particular, the following are very likely to vary from project to project:
- The Babel plugins
babel-polyfillmight make more sense)
- Use of Babel at all
mocha-bdddependency and the testing structure
npm run buildscript
Copyright © 2017 Lisk Foundation
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.