doc: Merge running locally into contributing guide (#1640)

As recently several people have been asking for things
that are described in `RUNNING-LOCALLY.md`, but couldn't be
found in the `CONTRIBUTING.md`, this consilidates the two into
one single resource to look for on how to get started developing.

Change-Type: patch
This commit is contained in:
Jonas Hermsmeier 2017-07-31 17:24:33 +02:00 committed by GitHub
parent 07ac2ecf4c
commit 25d50fed74
2 changed files with 103 additions and 116 deletions

View File

@ -10,47 +10,87 @@ High-level Etcher overview
Make sure you checkout our [ARCHITECTURE.md][ARCHITECTURE] guide, which aims to
explain how all the pieces fit together.
Running locally
---------------
See the [RUNNING-LOCALLY.md][RUNNING-LOCALLY] guide.
Developing
----------
We rely on various `make` targets to perform some common tasks:
### Prerequisites
- `make lint`: Run the linter.
- `make sass`: Compile SCSS files.
#### Common
We make use of [EditorConfig] to communicate indentation, line endings and
other text editing default. We encourage you to install the relevant plugin in
your text editor of choice to avoid having to fix any issues during the review
process.
- [NodeJS](https://nodejs.org) (at least v6)
- [Python](https://www.python.org)
- [jq](https://stedolan.github.io/jq/)
- [curl](https://curl.haxx.se/)
Commit Guidelines
-----------------
```sh
pip install -r requirements.txt
```
See [COMMIT-GUIDELINES.md][COMMIT-GUIDELINES] for a thorough guide on how to
write commit messages.
You might need to run this with `sudo` or administrator permissions.
Updating a dependency
---------------------
#### Windows
Given we use [npm shrinkwrap][shrinkwrap], we have to take extra steps to make
sure the `npm-shrinkwrap.json` file gets updated correctly when we update a
dependency.
- [NSIS v2.51](http://nsis.sourceforge.net/Main_Page) (v3.x won't work)
- Either one of the following:
- [Visual C++ 2015 Build Tools](http://landinghub.visualstudio.com/visual-cpp-build-tools) containing standalone compilers, libraries and scripts
- Install the [windows-build-tools](https://github.com/felixrieseberg/windows-build-tools) via npm with `npm install --global windows-build-tools`
- [Visual Studio Community 2015](https://www.microsoft.com/en-us/download/details.aspx?id=48146) (free) (other editions, like Professional and Enterprise, should work too)
**NOTE:** Visual Studio 2015 doesn't install C++ by default. You have to rerun the
setup, select "Modify" and then check `Visual C++ -> Common Tools for Visual
C++ 2015` (see http://stackoverflow.com/a/31955339)
- [MinGW](http://www.mingw.org)
Use the following steps to ensure everything goes flawlessly:
The following MinGW packages are required:
- Run `make electron-develop` to ensure you don't have extraneous dependencies
you might have brought during development, or you are running older
dependencies because you come from another branch or reference.
- `msys-make`
- `msys-unzip`
- `msys-zip`
- `msys-bash`
- `msys-coreutils`
- Install the new version of the dependency. For example: `npm install --save
<package>@<version>`. This will update the `npm-shrinkwrap.json` file.
#### OS X
- Commit *both* `package.json` and `npm-shrinkwrap.json`.
- [XCode](https://developer.apple.com/xcode/) or [XCode Command Line Tools],
which can be installed by running `xcode-select --install`.
### Cloning the project
```sh
git clone https://github.com/resin-io/etcher
cd etcher
```
### Installing npm dependencies
**Make sure you have all the pre-requisites listed above installed in your
system before running the `install` script.**
**NOTE:** Please make use of the following scripts to install npm dependencies rather
than simply running `npm install` given that we need to do extra configuration
to make sure native dependencies are correctly compiled for Electron, otherwise
the application might not run successfully.
If you're on Windows, **run the command from the _Developer Command Prompt for
VS2015_**, to ensure all Visual Studio command utilities are available in the
`%PATH%`.
```sh
make electron-develop
```
### Running the application
#### GUI
```sh
npm start
```
#### CLI
```sh
node bin/etcher
```
Testing
-------
@ -75,6 +115,34 @@ systems as they can before sending a pull request.
*The test suite is run automatically by CI servers when you send a pull
request.*
We also rely on various `make` targets to perform some common tasks:
- `make lint`: Run the linter.
- `make sass`: Compile SCSS files.
We make use of [EditorConfig] to communicate indentation, line endings and
other text editing default. We encourage you to install the relevant plugin in
your text editor of choice to avoid having to fix any issues during the review
process.
Updating a dependency
---------------------
Given we use [npm shrinkwrap][shrinkwrap], we have to take extra steps to make
sure the `npm-shrinkwrap.json` file gets updated correctly when we update a
dependency.
Use the following steps to ensure everything goes flawlessly:
- Run `make electron-develop` to ensure you don't have extraneous dependencies
you might have brought during development, or you are running older
dependencies because you come from another branch or reference.
- Install the new version of the dependency. For example: `npm install --save
<package>@<version>`. This will update the `npm-shrinkwrap.json` file.
- Commit *both* `package.json` and `npm-shrinkwrap.json`.
Diffing Binaries
----------------
@ -97,6 +165,12 @@ $ git config --global diff.hex.binary true
If you don't have `hexdump` available on your platform,
you can try [hxd], which is also a bit faster.
Commit Guidelines
-----------------
See [COMMIT-GUIDELINES.md][COMMIT-GUIDELINES] for a thorough guide on how to
write commit messages.
Sending a pull request
----------------------
@ -133,8 +207,8 @@ systems we support.
Don't hesitate to get in touch if you have any questions or need any help!
[ARCHITECTURE]: https://github.com/resin-io/etcher/blob/master/docs/ARCHITECTURE.md
[RUNNING-LOCALLY]: https://github.com/resin-io/etcher/blob/master/docs/RUNNING-LOCALLY.md
[COMMIT-GUIDELINES]: https://github.com/resin-io/etcher/blob/master/docs/COMMIT-GUIDELINES.md
[EditorConfig]: http://editorconfig.org
[shrinkwrap]: https://docs.npmjs.com/cli/shrinkwrap
[hxd]: https://github.com/jhermsmeier/hxd
[XCode Command Line Tools]: https://developer.apple.com/library/content/technotes/tn2339/_index.html

View File

@ -1,87 +0,0 @@
Running locally
===============
This document aims to serve as a guide to get Etcher running locally on your
development machine.
Prerequisites
-------------
### Common
- [NodeJS](https://nodejs.org) (at least v6)
- [Python](https://www.python.org)
- [jq](https://stedolan.github.io/jq/)
- [curl](https://curl.haxx.se/)
```sh
pip install -r requirements.txt
```
You might need to run this with `sudo` or administrator permissions.
### Windows
- [NSIS v2.51](http://nsis.sourceforge.net/Main_Page) (v3.x won't work)
- Either one of the following:
- [Visual C++ 2015 Build Tools](http://landinghub.visualstudio.com/visual-cpp-build-tools) containing standalone compilers, libraries and scripts
- Install the [windows-build-tools](https://github.com/felixrieseberg/windows-build-tools) via npm with `npm install --global windows-build-tools`
- [Visual Studio Community 2015](https://www.microsoft.com/en-us/download/details.aspx?id=48146) (free) (other editions, like Professional and Enterprise, should work too)
**NOTE:** Visual Studio 2015 doesn't install C++ by default. You have to rerun the
setup, select "Modify" and then check `Visual C++ -> Common Tools for Visual
C++ 2015` (see http://stackoverflow.com/a/31955339)
- [MinGW](http://www.mingw.org)
The following MinGW packages are required:
- `msys-make`
- `msys-unzip`
- `msys-zip`
- `msys-bash`
- `msys-coreutils`
### OS X
- [XCode](https://developer.apple.com/xcode/)
Cloning the project
-------------------
```sh
git clone https://github.com/resin-io/etcher
cd etcher
```
Installing npm dependencies
---------------------------
**Make sure you have all the pre-requisites listed above installed in your
system before running the `install` script.**
Please make use of the following scripts to install npm dependencies rather
than simply running `npm install` given that we need to do extra configuration
to make sure native dependencies are correctly compiled for Electron, otherwise
the application might not run successfully.
If you're on Windows, **run the command from the _Developer Command Prompt for
VS2015_**, to ensure all Visual Studio command utilities are available in the
`%PATH%`.
```sh
make electron-develop
```
Running the application
-----------------------
### GUI
```sh
npm start
```
### CLI
```sh
node bin/etcher
```