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