|
| 1 | +Contributing |
| 2 | +==================== |
| 3 | + |
| 4 | +## Introduction |
| 5 | + |
| 6 | +First of all, thank you for taking the time to contribute! |
| 7 | + |
| 8 | +Before starting, make yourself familiar with the `nativescript-dev-webpack`'s [documentation](http://docs.nativescript.org/best-practices/bundling-with-webpack) and the official [NativeScript Code Of Conduct]( https://github.com/NativeScript/codeofconduct). |
| 9 | + |
| 10 | +## Project Structure |
| 11 | + |
| 12 | +The repository contains several ingredients: |
| 13 | +* `installer.js` - combination of postinstall scripts for adding or removing webpack configurations and necessary dependecies when installing the plugin. |
| 14 | +* `prepublish` - [Webpack config](https://webpack.js.org/concepts/configuration/) snippets used for generating webpack configuration templates. The latter are generated with the npm's `prepublishOnly` script. **If you want to modify the distributed webpack configurations - that's the right place to do it.** |
| 15 | +* `templates` - webpack config templates for different types of projects - NativeScript with JavaScript, NativeScript with TypeScript and NativeScript Angular projects. |
| 16 | +* `plugins` - several [Webpack plugins](https://webpack.js.org/concepts/plugins/) necessary for bundling NativeScript applications. |
| 17 | +* `snapshot/android` - tools used with the `NativeScriptSnapshot` plugin for generating V8 Heap Snapshots. |
| 18 | +* `nativescript-target` - configuration of a [Webpack deployment target](https://webpack.js.org/concepts/targets/) for building NativeScript applications. |
| 19 | +* `bin` - helper node/npm scripts for projects using the plugin. |
| 20 | +* `bin/ns-bundle` - node script used for bundling the project with Webpack and building the native Android/iOS application with NativeScript CLI. |
| 21 | +## Setup |
| 22 | +1. [Fork](https://help.github.com/articles/fork-a-repo/) and clone the GitHub repository: |
| 23 | + ```bash |
| 24 | + git clone https://github.com/your-username/nativescript-dev-webpack.git |
| 25 | + ``` |
| 26 | + |
| 27 | +2. Add an 'upstream' remote pointing to the original repository: |
| 28 | + ```bash |
| 29 | + cd nativescript-dev-webpack |
| 30 | + git remote add upstream https://github.com/NativeScript/nativescript-dev-webpack.git |
| 31 | + ``` |
| 32 | + |
| 33 | +3. Create a branch for your changes: |
| 34 | + ```bash |
| 35 | + git checkout -b <my-fix-branch> master |
| 36 | + ``` |
| 37 | + |
| 38 | +4. Install devDependencies: |
| 39 | + ```bash |
| 40 | + npm install |
| 41 | + ``` |
| 42 | + |
| 43 | +You are good to go! The plugin is written in plain JavaScript. You're strongly encouraged to follow the official NativeScript [Coding Conventions](https://github.com/NativeScript/NativeScript/blob/master/CodingConvention.md) and to use ES features available in NodeJS v6. If unsure, check on [node.green](http://node.green/). |
| 44 | + |
| 45 | +## Testing locally |
| 46 | + |
| 47 | +1. Create a new NativeScript project with NativeScript CLI: |
| 48 | + ``` bash |
| 49 | + tns create testapp # pass --ng/--tsc for Angular/TypeScript app |
| 50 | + ``` |
| 51 | + |
| 52 | +2. Install your local copy of the plugin using either `npm install` or `npm link`. |
| 53 | + ``` bash |
| 54 | + npm install/link /path/to/repo/nativescript-dev-webpack |
| 55 | + ``` |
| 56 | + |
| 57 | +3. The first command will copy the files, while the second one will create a symlink to the local directory. Because of the symlink, all the changes you make in `node_modules/nativescript-dev-webpack` will be 'synced' with `/path/to/repo/nativescript-dev-webpack` and vice-versa. |
| 58 | + |
| 59 | +4. Make sure to force-update the project's configuration files if it's already using Webpack. |
| 60 | + ``` bash |
| 61 | + rm -rf node_modules platforms webpack.* app/vendor* |
| 62 | + ./node_modules/.bin/update-ns-webpack # force update dependecies and add the new configurations |
| 63 | + npm i # install the new dependencies |
| 64 | + ``` |
| 65 | + |
| 66 | +## Reporting Bugs |
| 67 | + |
| 68 | +1. Always update to the most recent master release; the bug may already be resolved. |
| 69 | +2. Search for similar issues in the issues list for this repo; it may already be an identified problem. |
| 70 | +3. If this is a bug or problem that is clear, simple, and is unlikely to require any discussion -- it is OK to open an issue on GitHub with a reproduction of the bug including workflows and screenshots. If possible, submit a Pull Request with a failing test, entire application or module. If you'd rather take matters into your own hands, fix the bug yourself (jump down to the [Submitting a PR](#pr) section). |
| 71 | + |
| 72 | +## Requesting Features |
| 73 | + |
| 74 | +1. Use Github Issues to submit feature requests. |
| 75 | +2. First, search for a similar request and extend it if applicable. This way it would be easier for the community to track the features. |
| 76 | +3. When requesting a new feature, please provide as much detail as possible about why you need the feature in your apps. We prefer that you explain a need rather than explain a technical solution for it. That might trigger a nice conversation on finding the best and broadest technical solution to a specific need. |
| 77 | + |
| 78 | +## Submitting PR |
| 79 | + |
| 80 | +1. Create one or several commits describing your changes. Follow the [Angular Commit message guidelines](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit#heading=h.uyo6cb12dt6w). |
| 81 | + |
| 82 | +2. Push your branch to GitHub: |
| 83 | + ```bash |
| 84 | + git push origin my-fix-branch |
| 85 | + ``` |
| 86 | + |
| 87 | +3. In GitHub, send a pull request to `nativescript-dev-webpack:master`. If we suggest changes, then: |
| 88 | + |
| 89 | + * Make the required updates. |
| 90 | + * Commit the changes to your branch (e.g. `my-fix-branch`). |
| 91 | + * Push the changes to your GitHub repository (this will update your PR). |
| 92 | + |
| 93 | +4. If your branch gets too outdated you may need to rebase it on top of the upstream master and force push to update your PR: |
| 94 | + |
| 95 | + 1. Fetch the latest changes |
| 96 | + ```bash |
| 97 | + git fetch upstream |
| 98 | + ``` |
| 99 | + |
| 100 | + 2. Check out to your fork's local `master` branch |
| 101 | + ```bash |
| 102 | + git checkout master |
| 103 | + ``` |
| 104 | + |
| 105 | + 3. Merge the original repo changes into your local `master` branch |
| 106 | + ```bash |
| 107 | + git merge upstream/master |
| 108 | + ``` |
| 109 | + |
| 110 | + 4. Rebase it on top of `master` |
| 111 | + ```bash |
| 112 | + git rebase -i master |
| 113 | + ``` |
| 114 | + |
| 115 | + 5. Update your PR with force push |
| 116 | + ```bash |
| 117 | + git push -f origin my-fix-branch |
| 118 | + ``` |
| 119 | + |
| 120 | +Thank you for your contribution! |
0 commit comments