2018-11-07 13:47:03 +00:00
# Contributing to Embark
2017-03-10 03:11:54 +00:00
2018-11-07 13:47:03 +00:00
We would love for you to contribute to Embark and help make it even better than it is
today! As a contributor, here are the guidelines we would like you to follow:
2017-03-10 03:11:54 +00:00
2018-11-07 13:47:03 +00:00
- [Code of Conduct ](#coc )
- [Question or Problem? ](#question )
- [Issues and Bugs ](#issue )
- [Feature Requests ](#feature )
- [Submission Guidelines ](#submit )
- [Coding Rules ](#rules )
- [Commit Message Guidelines ](#commit )
2017-03-10 03:11:54 +00:00
2018-11-07 13:47:03 +00:00
## <a name="coc"></a> Code of Conduct
Help us keep Embark open and inclusive. Please read and follow our [Code of Conduct ](./CODE_OF_CONDUCT.md ).
2017-03-10 03:11:54 +00:00
2018-11-07 13:47:03 +00:00
## <a name="question"></a> Got a Question or Problem?
2017-03-10 03:11:54 +00:00
2018-11-07 13:47:03 +00:00
Do not open issues for general support questions as we want to keep GitHub issues for bug reports and feature requests. You've got much better chances of getting your question answered on [Stack Exchange ](https://ethereum.stackexchange.com/search?tab=newest&q=embark ) where the questions should be tagged with tag `embark` .
2017-03-10 03:11:54 +00:00
2018-11-07 13:47:03 +00:00
Stack Exchange is a much better place to ask questions since:
2017-03-10 03:11:54 +00:00
2018-11-07 13:47:03 +00:00
- there are thousands of people willing to help
- questions and answers stay available for public viewing so your question / answer might help someone else
- Stack Exchange's voting system assures that the best answers are prominently visible.
2017-03-10 03:11:54 +00:00
2018-11-07 13:47:03 +00:00
To save your and our time, we will systematically close all issues that are requests for general support and redirect people to Stack Exchange.
2017-03-10 03:11:54 +00:00
2018-11-07 13:47:03 +00:00
If you would like to chat about the question in real-time, you can reach out via [our gitter channel ](https://gitter.im/embark-framework/Lobby ).
2017-03-10 03:11:54 +00:00
2018-11-07 13:47:03 +00:00
## <a name="issue"></a> Found a Bug?
If you find a bug in the source code, you can help us by
[submitting an issue ](#submit-issue ) to our [GitHub Repository ](https://github.com/embark-framework/embark/ ). Even better, you can
[submit a Pull Request ](#submit-pr ) with a fix.
2017-03-10 03:11:54 +00:00
2018-11-07 13:47:03 +00:00
## <a name="feature"></a> Missing a Feature?
You can *request* a new feature by [submitting an issue ](#submit-issue ) to our GitHub
Repository. If you would like to *implement* a new feature, please submit an issue with
a proposal for your work first, to be sure that we can use it.
Please consider what kind of change it is:
2017-03-10 03:11:54 +00:00
2018-11-07 13:47:03 +00:00
* For a **Major Feature** , first open an issue and outline your proposal so that it can be
discussed. This will also allow us to better coordinate our efforts, prevent duplication of work,
and help you to craft the change so that it is successfully accepted into the project.
* **Small Features** can be crafted and directly [submitted as a Pull Request ](#submit-pr ).
2017-03-10 03:11:54 +00:00
2018-11-07 13:47:03 +00:00
## <a name="submit"></a> Submission Guidelines
2017-03-10 03:11:54 +00:00
2018-11-07 13:47:03 +00:00
### <a name="submit-issue"></a> Submitting an Issue
2017-03-10 03:11:54 +00:00
2018-11-07 13:47:03 +00:00
Before you submit an issue, please search the issue tracker, maybe an issue for your problem already exists and the discussion might inform you of workarounds readily available.
We want to fix all the issues as soon as possible, but before fixing a bug we need to reproduce and confirm it. In order to reproduce bugs, we will systematically ask you to provide steps to reproduce your issue.
You can file new issues by filling out our [new issue form ](https://github.com/embark-framework/embark/issues/new/choose ).
### <a name="submit-pr"></a> Submitting a Pull Request (PR)
Before you submit your Pull Request (PR) consider the following guidelines:
1. Search [GitHub ](https://github.com/embark-framework/embark/pulls ) for an open or closed PR
that relates to your submission. You don't want to duplicate effort.
1. Fork the embark-framework/embark repo.
1. Make your changes in a new git branch:
```shell
2018-11-09 08:54:27 +00:00
git checkout -b my-fix-branch master
2018-11-07 13:47:03 +00:00
```
1. Create your patch, **including appropriate test cases** .
build: implement a monorepo with Lerna
TL;DR
=====
`yarn install` in a fresh clone of the repo.
`yarn reboot` when switching branches.
When pulling in these changes, there may be untracked files at the root in
all/some of:
```
.embark/
.nyc_output/
coverage/
dist/
embark-ui/
test_apps/
```
They can be safely deleted since those paths are no longer in use at the root.
Many of the scripts in the top-level `package.json` support Lerna's [filter
options]. For example:
`yarn build --scope embark` build only `packages/embark`.
`yarn build --ignore embark-ui` build everything except `packages/embark-ui`.
Scoping scripts will be more useful when there are more packages in the
monorepo and, for example, `yarn start` doesn't need to be invoked for all of
them while working on just a few of them simultaneously, e.g `embark` and
`embarkjs`.
It's also possible to `cd` into a particular package and run its scripts
directly:
```
cd packages/embark && yarn watch
```
Hot Topics & Questions
======================
What should be done about the [README][embark-readme] for `packages/embark`?
Should the top-level README be duplicated in that package?
Lerna is setup to use [Fixed/Locked mode][fixed-locked], and accordingly
`packages/embark-ui` is set to `4.0.0-beta.0`. The same will be true when
adding embarkjs, swarm-api, etc. to the monorepo. Is this acceptable or do we
want to use [Independent mode][independent]?
Scripts
=======
If a package doesn't have a matching script, `lerna run` skips it
automatically. For example, `packages/embark-ui` doesn't have a `typecheck`
script.
`yarn build`
------------
Runs babel, webpack, etc. according to a package's `build` script.
`yarn build:no-ui` is a shortcut for `yarn build --ignore embark-ui`.
`yarn ci`
---------
Runs a series of scripts relevant in a CI context according to a package's `ci`
script. For `packages/embark` that's `lint typecheck build test package`.
Also runs the `ci` script of the embedded `test_dapps` monorepo.
`yarn clean`
------------
Runs rimraf, etc. according to a package's `clean` script.
`yarn globalize`
----------------
Makes the development embark available on the global PATH, either via
symlink (Linux, macOS) or a shim script (Windows).
`yarn lint`
-----------
Runs eslint, etc. according to a package's `lint` script.
`yarn package`
--------------
Invokes `npm pack` according to a package's `package` script.
`yarn qa`
---------
Very similar to `ci`, runs a series of scripts according to a package's `qa`
script. The big difference between `ci` and `qa` is that at the top-level `qa`
first kicks off `reboot:full`.
There is a `preqa` script ([invoked automatically][npm-scripts]), which is a
bit of a wart. It makes sure that `embark reset` can be run successfully in
`packages/embark/templates/*` when the `reboot` script invokes the `reset`
script.
The `qa` script is invoked by `yarn release` before the latter proceeds to
invoke `lerna publish`.
`yarn reboot`
-------------
Invokes the `reset` script and then does `yarn install`.
The `reboot:full` variant invokes `reset:full` and then does `yarn install`.
`yarn release`
--------------
Works in concert with [lerna publish], which will prompt to verify the version
before proceeding. Use `n` to cancel instead of `ctrl-c` as `lerna publish` has
been seen to occasionally misbehave when not exited cleanly (e.g. creating a
tag when it shouldn't have).
```
yarn release [bump] [--options]
```
* `[bump]` see [`publish` positionals][pub-pos] and [`version`
positionals][ver-pos]; an exact version can also be specified.
* `--preid` prerelease identifier, e.g. `beta`; when doing a prerelease bump
will default to whatever identifier is currently in use.
* `--dist-tag` registry distribution tag, defaults to `latest`.
* `--message` commit message format, defaults to `chore(release): %v`.
* `--sign` indicates that the git commit and tag should be signed; not signed
by default.
* `--release-branch` default is `master`; must match the current branch.
* `--git-remote` default is `origin`.
* `--registry` default is `https://registry.npmjs.org/` per the top-level
[`lerna.json`][lerna-json].
To release `4.0.0-beta.1` as `embark@next` (assuming version is currently at
`4.0.0-beta.0`) could do:
```
yarn release prerelease --dist-tag next
```
For *test releases* (there is no longer a `--dry-run` option) [verdaccio] and a
filesystem git remote can be used.
Condensend instructions:
```
mkdir -p ~/temp/clones && cd ~/temp/clones
git clone git@github.com:embark-framework/embark.git
cd ~/repos/embark
git remote add FAKEembark ~/temp/clones/embark
```
in another terminal:
```
npm i -g verdaccio && verdaccio
```
in the first terminal:
```
yarn release --git-remote FAKEembark --registry http://localhost:4873/
```
`yarn reset`
------------
Invokes cleaning and resetting steps according to a package's `reset`
script. The big difference between `clean` and `reset` is that `reset` is
intended to delete a package's `node_modules`.
The `reset:full` variant deletes the monorepo's top-level `node_modules` at the
end. That shouldn't be necessary too often, e.g. in day-to-day work when
switching branches, which is why there is `reboot` / `reset` vs. `reboot:full`
/ `reset:full`.
Errors may be seen related to invocation of `embark reset` if embark is not
built, but `reset` will still complete successfully.
`yarn start`
------------
Runs babel, webpack, tsc, etc. (in parallel, in watch mode) according to a
package's `start` script.
`yarn test`
-----------
Run mocha, etc. according to a package's `test` script.
The `test:full` variant runs a series of scripts: `lint typecheck test
test_dapps`.
`yarn test_dapps`
-----------------
Runs the `test` script of the embedded `test_dapps` monorepo.
The `test_dapps:ci` and `test_dapps:qa` variants run the `ci` and `qa` scripts
of the embedded `test_dapps` monorepo, respectively.
`yarn typecheck`
----------------
Runs tsc, etc. according to a package's `typecheck` script.
Notes
=====
`npx` is used in some of the top-level and package scripts to ensure the
scripts can run even if `node_modules` is missing.
[`"nohoist"`][nohoist] specifies a couple of embark packages because
[`restrictPath`][restrictpath] is interfering with access to modules that are
located in a higher-up `node_modules`.
All dependencies in `packages/embark-ui` have been made `devDependencies` since
its production build is self-contained.
`packages/embark`'s existing CHANGELOG's formatting has been slightly adjusted
to match the formatting that Lerna will use going forward (entries in the log
haven't been modified).
Lerna will generate a CHANGELOG at the top-level and in each package. Since
we're transitioning to a monorepo, things may look a little wonky with respect
to old entries in `packages/embark/CHANGELOG.md` and going forward we need to
consider how scoping our commits corresponds to member-packages of the
monorepo.
In `packages/embark`, `test` invokes `scripts/test`, which starts a child
process wherein `process.env.DAPP_PATH` is a temporary path that has all of
`packages/embark/dist/test` copied into it, so that paths to test
helpers/fixtures don't need to be prefixed with `dist/test/` and so that a
`.embark` directory doesn't get written into `packages/embark`.
The `"engines"` specified in top-level and packages' `package.json` reflect a
node and npm pair that match (a source of confusion in the past). The pair was
chosen according to the first post v5 npm that's bundled with node. A
`"runtime"` key/object has been introduced in `packages/embark/package.json`
which is used as the basis for specifying the minimum version of node that can
be used to run embark, and that's what is checked by `bin/embark`.
Some changes have been introduced, e.g. in `lib/core/config` and
`lib/utils/solidity/remapImports` so that it's *not* implicitly assumed that
`process.env.DAPP_PATH` / `fs.dappPath()` are the same as
`process.cwd()`. There are probably several++ places where that assumption is
still in effect, and we should work to identify and correct them.
`embark reset` now deletes `embarkArtifacts/` within a dapp root, and
`embarkArtifacts/` is git-ignored.
`lib/core/env` adds all `node_modules` relative to `process.env.EMBARK_PATH` to
`NODE_PATH` so that embark's modules can be resolved as expected whether
embark's `node_modules` have been deduped or are installed in npm's flat
"global style".
`checkDependencies` has been inlined (see `lib/utils/checkDependencies`) and
slightly modified to support dependencies that have been hoisted into a
higher-up `node_modules`, e.g. as part of a yarn workspace. eslint has been
disabled for that script to avoid more involved changes to it.
`test_apps` is not in `packages/embark`; rather, there is `test_dapps` at the
top-level of the monorepo. `test_dapps` is an embedded monorepo, and its `ci` /
`qa` scripts `npm install` embark from freshly built tarballs of the packages
in the outer monorepo and then use that installation to run `embark test` in
the dapps. This should allow us to rapidly detect breakage related to
auto-bumps in transitive dependencies.
[filter options]: https://github.com/lerna/lerna/tree/master/core/filter-options
[embark-readme]: https://github.com/embark-framework/embark/blob/build/lerna/packages/embark/README.md
[fixed-locked]: https://github.com/lerna/lerna#fixedlocked-mode-default
[independent]: https://github.com/lerna/lerna#independent-mode
[npm-scripts]: https://docs.npmjs.com/misc/scripts
[lerna publish]: https://github.com/lerna/lerna/tree/master/commands/publish
[pub-pos]: https://github.com/lerna/lerna/tree/master/commands/publish#positionals
[ver-pos]: https://github.com/lerna/lerna/tree/master/commands/version#positionals
[lerna-json]: https://github.com/embark-framework/embark/blob/build/lerna/lerna.json#L11
[verdaccio]: https://www.npmjs.com/package/verdaccio
[nohoist]: https://github.com/embark-framework/embark/blob/build/lerna/package.json#L52-L55
[restrictpath]: https://github.com/embark-framework/embark/blob/build/lerna/packages/embark/src/lib/core/fs.js#L9
2019-01-28 18:15:05 +00:00
1. Run the QA suite, by running `$ npm run qa` and ensure that all steps succeed.
2018-11-07 13:47:03 +00:00
1. Commit your changes using a descriptive commit message that follows our
[commit message conventions ](#commit ). Adherence to these conventions
is necessary because release notes are automatically generated from these messages.
```shell
git commit -a
```
Note: the optional commit `-a` command line option will automatically "add" and "rm" edited files.
1. Push your branch to GitHub:
```shell
git push origin my-fix-branch
```
2018-11-09 08:54:27 +00:00
1. In GitHub, send a pull request to `embark:master` .
2018-11-07 13:47:03 +00:00
* If we suggest changes then:
* Make the required updates.
* Re-run the test suites to ensure tests are still passing.
* Rebase your branch and force push to your GitHub repository (this will update your Pull Request):
```shell
2018-11-09 08:54:27 +00:00
git rebase master -i
2018-11-07 13:47:03 +00:00
git push -f
```
That's it! Thank you for your contribution!
#### After your pull request is merged
After your pull request is merged, you can safely delete your branch and pull the changes
from the main (upstream) repository:
* Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows:
```shell
git push origin --delete my-fix-branch
```
2018-11-09 08:54:27 +00:00
* Check out the master branch:
2018-11-07 13:47:03 +00:00
```shell
2018-11-09 08:54:27 +00:00
git checkout master -f
2018-11-07 13:47:03 +00:00
```
* Delete the local branch:
```shell
git branch -D my-fix-branch
```
2018-11-09 08:54:27 +00:00
* Update your master with the latest upstream version:
2018-11-07 13:47:03 +00:00
```shell
2018-11-09 08:54:27 +00:00
git pull --ff upstream master
2018-11-07 13:47:03 +00:00
```
## <a name="rules"></a> Coding Rules
To ensure consistency throughout the source code, keep these rules in mind as you are working:
* All public API methods **must be documented** .
## <a name="commit"></a> Commit Message Guidelines
We have very precise rules over how our git commit messages can be formatted. This leads to **more
readable messages** that are easy to follow when looking through the **project history** . But also,
we use the git commit messages to **generate the Embark change log** .
### Commit Message Format
Each commit message consists of a **header** , a **body** and a **footer** . The header has a special
format that includes a **type** , a **scope** and a **subject** :
```
2019-03-20 00:57:52 +00:00
type(@embark|@cockpit/< SCOPE > ): < subject >
2018-11-07 13:47:03 +00:00
< BLANK LINE >
< body >
< BLANK LINE >
< footer >
```
The **header** is mandatory and the **scope** of the header is optional.
Any line of the commit message cannot be longer 100 characters! This allows the message to be easier
to read on GitHub as well as in various git tools.
The footer should contain a [closing reference to an issue ](https://help.github.com/articles/closing-issues-via-commit-messages/ ) if any.
Samples:
```
docs(changelog): update changelog to beta.5
```
```
fix(release): need to depend on latest rxjs and zone.js
The version in our package.json gets copied to the one we publish, and users need the latest of these.
```
### Revert
If the commit reverts a previous commit, it should begin with `revert: ` , followed by the header of the reverted commit. In the body it should say: `This reverts commit <hash>.` , where the hash is the SHA of the commit being reverted.
### Type
Must be one of the following:
* **build**: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
* **ci**: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
* **docs**: Documentation only changes
* **feat**: A new feature
* **fix**: A bug fix
* **perf**: A code change that improves performance
* **refactor**: A code change that neither fixes a bug nor adds a feature
* **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
* **test**: Adding missing tests or correcting existing tests
2017-03-10 03:11:54 +00:00
### Scope
2018-11-07 13:47:03 +00:00
The scope should be the name of the npm package affected (as perceived by the person reading the changelog generated from commit messages.
The following is the list of supported scopes:
* **@embark/cli** - Embark command line interface
* **@embark/core** - Embark core
2019-03-20 00:57:52 +00:00
* **@embark/< `module`>** - Embark core module (any folder name under `packages/embark/src/lib/modules` ), ie `@embark/console` or `@embark/debugger`
* **@embark/< `package`>** - Embark npm package in the monorepo (any folder name under `packages/` ), ie `@embark/embarkjs` or `@embark/embark-compiler`
* **@cockpit/< `section`>** - Cockpit site section, ie `@cockpit/explorer`
2017-03-10 03:11:54 +00:00
2018-11-07 13:47:03 +00:00
There are currently a few exceptions to the "use package name" rule:
2017-03-10 03:11:54 +00:00
2018-11-07 13:47:03 +00:00
* **packaging**: used for changes that change the npm package layout in all of our packages, e.g. public path changes, package.json changes done to all packages, d.ts file/format changes, changes to bundles, etc.
* **changelog**: used for updating the release notes in CHANGELOG.md
* none/empty string: useful for `style` , `test` and `refactor` changes that are done across all packages (e.g. `style: add missing semicolons` )
2017-03-10 03:11:54 +00:00
2018-11-07 13:47:03 +00:00
### Subject
The subject contains a succinct description of the change:
2017-03-10 03:11:54 +00:00
2018-11-07 13:47:03 +00:00
* use the imperative, present tense: "change" not "changed" nor "changes"
* don't capitalize the first letter
* no dot (.) at the end
2017-03-10 03:11:54 +00:00
2018-11-07 13:47:03 +00:00
### Body
Just as in the **subject** , use the imperative, present tense: "change" not "changed" nor "changes".
The body should include the motivation for the change and contrast this with previous behavior.
2017-03-10 03:11:54 +00:00
2018-11-07 13:47:03 +00:00
### Footer
The footer should contain any information about **Breaking Changes** and is also the place to
reference GitHub issues that this commit **Closes** .
2017-03-10 03:11:54 +00:00
2018-11-07 13:47:03 +00:00
**Breaking Changes** should start with the word `BREAKING CHANGE:` with a space or two newlines. The rest of the commit message is then used for this.
