|
| 1 | +# Contributing to ml-esir-maps-ng |
| 2 | + |
| 3 | +ml-esri-maps-ng welcomes new contributors. This document will guide you |
| 4 | +through the process. |
| 5 | + |
| 6 | + - [Question or Problem?](#question) |
| 7 | + - [Issues and Bugs](#issue) |
| 8 | + - [Feature Requests](#feature) |
| 9 | + - [Submission Guidelines](#submit) |
| 10 | + |
| 11 | +## <a name="question"></a> Got a Question or Problem? |
| 12 | + |
| 13 | +If you have questions about how to use ml-esri-maps-ng, check our documentation on the [Wiki][wiki]. Alternatively, check [Stack Overflow][mlstack] to see if it has been answered there, and post your question there if not. Please tag it with MarkLogic, AngularJS, and Esri-Maps. |
| 14 | + |
| 15 | +## <a name="issue"></a> Found an Issue? |
| 16 | + |
| 17 | +If you find a bug in the source code or a mistake in the documentation, you can help us by |
| 18 | +submitting an issue to our [GitHub Issue Tracker][issue tracker]. Even better you can submit a Pull Request |
| 19 | +with a fix for the issue you filed. |
| 20 | + |
| 21 | +## <a name="feature"></a> Want a Feature? |
| 22 | + |
| 23 | +You can request a new feature by submitting an issue to our [GitHub Issue Tracker][issue tracker]. If you |
| 24 | +would like to implement a new feature then first create a new issue and discuss it with one of our |
| 25 | +project maintainers. |
| 26 | + |
| 27 | +## <a name="submit"></a> Submission Guidelines |
| 28 | + |
| 29 | +### Submitting an Issue |
| 30 | + |
| 31 | +Before you submit your issue search the archive, maybe your question was already answered. |
| 32 | + |
| 33 | +If your issue appears to be a bug, and hasn't been reported, open a new issue. |
| 34 | +Help us to maximize the effort we can spend fixing issues and adding new |
| 35 | +features, by not reporting duplicate issues. Providing the following information will increase the |
| 36 | +chances of your issue being dealt with quickly: |
| 37 | + |
| 38 | +* **Overview of the Issue** - if an error is being thrown a stack trace helps |
| 39 | +* **Motivation for or Use Case** - explain why this is a bug for you |
| 40 | +* **ml-esri-maps-ng Version** - is it a named version or from our master branch |
| 41 | +* **Browser** - Chrome, FireFox, Safari? details help |
| 42 | +* **Suggest a Fix** - if you can't fix the bug yourself, perhaps you can point to what might be |
| 43 | + causing the problem (line of code or commit) |
| 44 | + |
| 45 | +### Submitting a Pull Request |
| 46 | + |
| 47 | +#### Fork ml-esri-maps-ng |
| 48 | + |
| 49 | +Fork the project [on GitHub](https://github.com/marklogic/ml-esri-maps-ng/fork) and clone |
| 50 | +your copy. |
| 51 | + |
| 52 | +```sh |
| 53 | +$ git clone [email protected]:username/ml-esri-maps-ng.git |
| 54 | +$ cd ml-esri-maps-ng |
| 55 | +$ git remote add upstream git://github.com/marklogic/ml-esri-maps-ng.git |
| 56 | +``` |
| 57 | + |
| 58 | +All bug fixes and new features go into the master branch. |
| 59 | + |
| 60 | +We ask that you open an issue in the [issue tracker][] and get agreement from |
| 61 | +at least one of the project maintainers before you start coding. |
| 62 | + |
| 63 | +Nothing is more frustrating than seeing your hard work go to waste because |
| 64 | +your vision does not align with that of a project maintainer. |
| 65 | + |
| 66 | +#### Create a branch for your changes |
| 67 | + |
| 68 | +Okay, so you have decided to fix something. Create a feature branch |
| 69 | +and start hacking: |
| 70 | + |
| 71 | +```sh |
| 72 | +$ git checkout -b my-feature-branch -t origin/master |
| 73 | +``` |
| 74 | + |
| 75 | +#### Formatting code |
| 76 | + |
| 77 | +We use [.editorconfig][] to configure our editors for proper code formatting. If you don't |
| 78 | +use a tool that supports editorconfig be sure to configure your editor to use the settings |
| 79 | +equivalent to our .editorconfig file. |
| 80 | + |
| 81 | +#### Commit your changes |
| 82 | + |
| 83 | +Make sure git knows your name and email address: |
| 84 | + |
| 85 | +```sh |
| 86 | +$ git config --global user.name "J. Random User" |
| 87 | +$ git config --global user.email "[email protected]" |
| 88 | +``` |
| 89 | + |
| 90 | +Writing good commit logs is important. A commit log should describe what |
| 91 | +changed and why. Follow these guidelines when writing one: |
| 92 | + |
| 93 | +1. The first line should be 50 characters or less and contain a short |
| 94 | + description of the change including the Issue number prefixed by a hash (#). |
| 95 | +2. Keep the second line blank. |
| 96 | +3. Wrap all other lines at 72 columns. |
| 97 | + |
| 98 | +A good commit log looks like this: |
| 99 | + |
| 100 | +``` |
| 101 | +Fixing Issue #123: make the whatchamajigger work in MarkLogic 8 |
| 102 | +
|
| 103 | +Body of commit message is a few lines of text, explaining things |
| 104 | +in more detail, possibly giving some background about the issue |
| 105 | +being fixed, etc etc. |
| 106 | +
|
| 107 | +The body of the commit message can be several paragraphs, and |
| 108 | +please do proper word-wrap and keep columns shorter than about |
| 109 | +72 characters or so. That way `git log` will show things |
| 110 | +nicely even when it is indented. |
| 111 | +``` |
| 112 | + |
| 113 | +The header line should be meaningful; it is what other people see when they |
| 114 | +run `git shortlog` or `git log --oneline`. |
| 115 | + |
| 116 | +#### Rebase your repo |
| 117 | + |
| 118 | +Use `git rebase` (not `git merge`) to sync your work from time to time. |
| 119 | + |
| 120 | +```sh |
| 121 | +$ git fetch upstream |
| 122 | +$ git rebase upstream/master |
| 123 | +``` |
| 124 | + |
| 125 | +#### Push your changes |
| 126 | + |
| 127 | +```sh |
| 128 | +$ git push origin my-feature-branch |
| 129 | +``` |
| 130 | + |
| 131 | +#### Submit the pull request |
| 132 | + |
| 133 | +Go to https://github.com/username/ml-esri-maps-ng and select your feature branch. Click |
| 134 | +the 'Pull Request' button and fill out the form. |
| 135 | + |
| 136 | +Pull requests are usually reviewed within a few days. If you get comments |
| 137 | +that need to be to addressed, apply your changes in a separate commit and push that to your |
| 138 | +feature branch. Post a comment in the pull request afterwards; GitHub does |
| 139 | +not send out notifications when you add commits to existing pull requests. |
| 140 | + |
| 141 | +That's it! Thank you for your contribution! |
| 142 | + |
| 143 | +#### After your pull request is merged |
| 144 | + |
| 145 | +After your pull request is merged, you can safely delete your branch and pull the changes |
| 146 | +from the main (upstream) repository: |
| 147 | + |
| 148 | +* Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows: |
| 149 | + |
| 150 | + ```shell |
| 151 | + git push origin --delete my-feature-branch |
| 152 | + ``` |
| 153 | + |
| 154 | +* Check out the master branch: |
| 155 | + |
| 156 | + ```shell |
| 157 | + git checkout master -f |
| 158 | + ``` |
| 159 | + |
| 160 | +* Delete the local branch: |
| 161 | + |
| 162 | + ```shell |
| 163 | + git branch -D my-feature-branch |
| 164 | + ``` |
| 165 | + |
| 166 | +* Update your master with the latest upstream version: |
| 167 | + |
| 168 | + ```shell |
| 169 | + git pull --ff upstream master |
| 170 | + ``` |
| 171 | + |
| 172 | +[wiki]: https://github.com/marklogic/ml-esri-maps-ng/wiki |
| 173 | +[mlstack]: http://stackoverflow.com/questions/tagged/marklogic |
| 174 | +[issue tracker]: https://github.com/marklogic/ml-esri-maps-ng/issues |
| 175 | +[.editorconfig]: http://editorconfig.org/ |
0 commit comments