|
| 1 | +DalekJS has a few very specific guidelines in addition |
| 2 | +to some of the standard guidelines that Github and open |
| 3 | +source projects in general recommend. These guidelines |
| 4 | +are here to facilitate your contribution and streamline |
| 5 | +the process of getting the changes merged in and released. |
| 6 | + |
| 7 | +If you don't follow these guidelines, we'll still work |
| 8 | +with you to get the changes in. Any contribution you can |
| 9 | +make will help tremendously. Following these guidelines |
| 10 | +will help to streamline the pull request and change |
| 11 | +submission process. |
| 12 | + |
| 13 | +## Documentation Fixes |
| 14 | + |
| 15 | +If you notice any problems with any documentation, please |
| 16 | +fix it and we'll get it merged as soon as we can. For |
| 17 | +small things like typos and grammar (which we know I'm |
| 18 | +terrible with), just click the "Edit this file" button |
| 19 | +and send in the pull request for the fix. For larger |
| 20 | +changes and big swaths of documentation changes, a regular |
| 21 | +pull request as outlined below is more appropriate. |
| 22 | + |
| 23 | +## Pull Requests |
| 24 | + |
| 25 | +See [Github's documentation for pull requests](https://help.github.com/articles/using-pull-requests). |
| 26 | + |
| 27 | +Pull requests are by far the best way to contribute to |
| 28 | +DalekJS. Any time you can send us a pull request with |
| 29 | +the changes that you want, we will have an easier time |
| 30 | +seeing what you are trying to do. But a pull request in |
| 31 | +itself is not usually sufficient. There needs to be some |
| 32 | +context and purpose with it, and it should be done |
| 33 | +against specific branch. |
| 34 | + |
| 35 | +## General Submission Guidelines |
| 36 | + |
| 37 | +These guidelines are generally applicable whether or not |
| 38 | +you are submitting a bug or a pull request. Please try to |
| 39 | +include as much of this information as possible with any |
| 40 | +submission. |
| 41 | + |
| 42 | +### Version Numbers |
| 43 | + |
| 44 | +In order to best help out with bugs, we need to know the |
| 45 | +following information in your bug submission: |
| 46 | + |
| 47 | +* DalekJS version # |
| 48 | +* Operating System / version # |
| 49 | +* Browser and version # |
| 50 | + |
| 51 | +Including this information in a submission will help |
| 52 | +us to test the problem and ensure that the bug is |
| 53 | +both reproduced and corrected on the platforms / versions |
| 54 | +that you are having issues with. |
| 55 | + |
| 56 | +### Provide A Meaningful Description |
| 57 | + |
| 58 | +It doesn't matter how beautiful and "obvious" your fix is. |
| 59 | +We have 10,000,000,000 things floating around the project |
| 60 | +at any given moment and we will not immediately understand |
| 61 | +why you are making changes. |
| 62 | + |
| 63 | +Given that, it is very important to provide a meaningful |
| 64 | +description with your pull requests that alter any code. |
| 65 | +A good format for these descriptions will include three things: |
| 66 | + |
| 67 | +1. Why: The problem you are facing (in as much detail as is |
| 68 | +necessary to describe the problem to someone who doesn't |
| 69 | +know anything about the system you're building) |
| 70 | + |
| 71 | +2. What: A summary of the proposed solution |
| 72 | + |
| 73 | +3. How: A description of how this solution solves the problem, |
| 74 | +in more detail than item #2 |
| 75 | + |
| 76 | +4. Any additional discussion on possible problems this might |
| 77 | +introduce, questions that you have related to the changes, etc. |
| 78 | + |
| 79 | +Without at least the first 2 items in this list, we won't |
| 80 | +have any clue why you're changing the code. The first thing |
| 81 | +we'll ask, then, is that you add that information. |
| 82 | + |
| 83 | +### Create A Topic Branch For Your Work |
| 84 | + |
| 85 | +The work you are doing for your pull request should not be |
| 86 | +done in the master branch of your forked repository. Create |
| 87 | +a topic branch for your work. This allows you to isolate |
| 88 | +the work you are doing from other changes that may be happening. |
| 89 | + |
| 90 | +Github is a smart system, too. If you submit a pull request |
| 91 | +from a topic branch and we ask you to fix something, pushing |
| 92 | +a change to your topic branch will automatically update the |
| 93 | +pull request. |
| 94 | + |
| 95 | +### Isolate Your Changes For The Pull Request |
| 96 | + |
| 97 | +See the previous item on creating a topic branch. |
| 98 | + |
| 99 | +If you don't use a topic branch, we may ask you to re-do your |
| 100 | +pull request on a topic branch. If your pull request contains |
| 101 | +commits or other changes that are not related to the pull |
| 102 | +request, we will ask you to re-do your pull request. |
| 103 | + |
| 104 | +### Branch from "wip" not "master" |
| 105 | + |
| 106 | +The "master" branch of the DalekJS repository is for |
| 107 | +production release code, and documentation updates only. Never |
| 108 | +create a pull request from the master branch. Always create |
| 109 | +a branch for your work from the "wip" branch. This will |
| 110 | +facilitate easier pull request management for the continuous |
| 111 | +work that is done in the dev branch. |
| 112 | + |
| 113 | +### Submit Specs With Your Pull Request |
| 114 | + |
| 115 | +Whenever possible, submit the specs (unit tests) that |
| 116 | +correspond to your pull request. |
| 117 | + |
| 118 | +I would rather see a pull request that is nothing but a |
| 119 | +failing spec, than see a large change made to the real |
| 120 | +code with no test to support the change. |
| 121 | + |
| 122 | +In fact... |
| 123 | + |
| 124 | +## Submit A Failing Spec If You Don't Know How To Fix The Problem |
| 125 | + |
| 126 | +If you are stuck in a scenario that fails in your app, |
| 127 | +but you don't know how to fix it, submit a failing spec |
| 128 | +to show the failing scenario. Follow the guidelines for |
| 129 | +pull request submission, but don't worry about fixing the |
| 130 | +problem. A failing spec to show that a problem exists is |
| 131 | +a very very very helpful pull request for us. |
| 132 | + |
| 133 | +We'll even accept a failing test pasted in to the ticket |
| 134 | +description instead of a pull request. That would at |
| 135 | +least get us started on creating the failing test in the code. |
| 136 | + |
| 137 | +## Don't Be A Troll |
| 138 | + |
| 139 | +It is very sad that we need to include this section of |
| 140 | +the contribution guidelines... |
| 141 | + |
| 142 | +If you are running in to a scenario with a problem, don't |
| 143 | +be a troll. Comment like "does DalekJS even have tests?" |
| 144 | +are not useful, funny or constructive. In fact, it may get |
| 145 | +you blocked and reported for abuse to Github. |
| 146 | + |
| 147 | +Submit a useful comment describing the scenario that is |
| 148 | +having an issue. Show us a failing test. Show us some |
| 149 | +code that is not behaving the way the documentation says |
| 150 | +it should. Be useful and work with us to fix the problem. |
| 151 | + |
| 152 | +We're all for criticism and tearing apart DalekJS for |
| 153 | +the problems it has. Do it in a constructive and helpful |
| 154 | +manner: "There isn't a test for this scenario. Here's a |
| 155 | +rough idea for one that shows the problem." Tell us why |
| 156 | +you don't like Marionette. Tell us that someone else is |
| 157 | +building something better and why that other thing fits |
| 158 | +your scenario and needs better than Marionette does. Just |
| 159 | +do it in a manner that allows us to learn from your |
| 160 | +experiences, instead of reacting to you being a troll |
| 161 | +(likely causing us to get defensive and miss an opportunity |
| 162 | +to learn something). |
| 163 | + |
| 164 | +----------- |
| 165 | +All credit for this goes to @derickbaily, he is not involved in this project anyhow, |
| 166 | +but made this nice piece up for backbone.marionette. |
0 commit comments