| 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.
|