diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 2c7b49ee..74ef64bf 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -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 - @`. 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 + @`. 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 diff --git a/docs/RUNNING-LOCALLY.md b/docs/RUNNING-LOCALLY.md deleted file mode 100644 index 02f2c91c..00000000 --- a/docs/RUNNING-LOCALLY.md +++ /dev/null @@ -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 -```