Merge pull request #826 from cobyism/rework-contributing-guides

Better contributing guidelines

Author: Coby Chapple

CONTRIBUTING.md

@@ -1,3 +1,34 @@
-Since this repo includes a large and diverse number of programming languages, frameworks, editors, and ecosystems, it's *very helpful* if you can provide a link to information supporting your pull request. Up-to-date, canonical documentation that mentions the files to be ignored is best.
+# Contributing guidelines
 
-This ensures we can efficiently go through pull requests and keep quality high.
+We’d love you to help us improve this project. To help us keep this collection
+high quality, we request that contributions adhere to the following guidelines.
+
+- **Provide a link to the application or project’s homepage**. Unless it’s
+  extremely popular, there’s a chance the maintainers don’t know about or use
+  the language, framework, editor, app, or project your change applies to.
+  
+- **Provide links to documentation** supporting the change you’re making.
+  Current, canonical documentation mentioning the files being ignored is best.
+  If documentation isn’t available to support your change, do the best you can
+  to explain what the files being ignored are for.
+  
+- **Explain why you’re making a change**. Even if it seems self-evident, please
+  take a sentence or two to tell us why your change or addition should happen.
+  It’s especially helpful to articulate why this change applies to *everyone*
+  who works with the applicable technology, rather than just you or your team.
+  
+- **Please consider the scope of your change**. If your change specific to a
+  certain language or framework, then make sure the change is made to the
+  template for that language or framework, rather than to the template for an
+  editor, tool, or operating system.
+
+- **Please only modify *one template* per pull request**. This helps keep pull
+  requests and feedback focused on a specific project or technology.
+
+In general, the more you can do to help us understand the change you’re making,
+the more likely we’ll be to accept your contribution quickly.
+
+Please also understand that we can’t list every tool that ever existed.
+Our aim is to curate a collection of the *most common and helpful* templates,
+not to make sure we cover every project possible. If we choose not to
+include your language, tool, or project, it’s not because it’s not awesome.

README.md

@@ -1,41 +1,79 @@
-# A Collection of Useful .gitignore Templates
+# A collection of `.gitignore` templates
 
-That's what we're trying to build. Please contribute
-by [forking][fk] and sending a [pull request][pr].
+This is GitHub’s collection of [`.gitignore`][man] file templates.
+We use this list to populate the `.gitignore` template choosers available
+in the GitHub.com interface when creating new repositories and files.
 
-Also **please** only modify **one file** per commit. This'll
-make merging easier for everyone.
+For more information about how `.gitignore` files work, and how to use them,
+the following resources are a great place to start:
 
-Global gitignores (OS-specific, editor-specific) should go into the
-`Global/` directory.
+- The [Ignoring Files chapter][chapter] of the [Pro Git][progit] book.
+- The [Ignoring Files article][help] on the GitHub Help site.
+- The [gitignore(5)][man] manual page.
 
-For more information on gitignore: [gitignore(5)][g5]
+[man]: http://git-scm.com/docs/gitignore
+[help]: https://help.github.com/articles/ignoring-files
+[chapter]: http://git-scm.com/book/en/Git-Basics-Recording-Changes-to-the-Repository#Ignoring-Files
+[progit]: http://git-scm.com/book
 
-[fk]: http://help.github.com/forking/
-[pr]: http://help.github.com/pull-requests/
-[g5]: http://man.cx/gitignore
+## Folder structure
+
+The files in the root directory are for `.gitignore` templates that are
+project specific, such as language or framework specific templates.
+Global (operating system or editor specific) templates should go into the
+[`Global/`](./Global) directory.
+
+## Contributing guidelines
+
+We’d love you to help us improve this project. To help us keep this collection
+high quality, we request that contributions adhere to the following guidelines.
 
-## Pull Requests
+- **Provide a link to the application or project’s homepage**. Unless it’s
+  extremely popular, there’s a chance the maintainers don’t know about or use
+  the language, framework, editor, app, or project your change applies to.
+  
+- **Provide links to documentation** supporting the change you’re making.
+  Current, canonical documentation mentioning the files being ignored is best.
+  If documentation isn’t available to support your change, do the best you can
+  to explain what the files being ignored are for.
+  
+- **Explain why you’re making a change**. Even if it seems self-evident, please
+  take a sentence or two to tell us why your change or addition should happen.
+  It’s especially helpful to articulate why this change applies to *everyone*
+  who works with the applicable technology, rather than just you or your team.
+  
+- **Please consider the scope of your change**. If your change specific to a
+  certain language or framework, then make sure the change is made to the
+  template for that language or framework, rather than to the template for an
+  editor, tool, or operating system.
 
-Since this repo includes a large and diverse
-number of programming languages, frameworks, editors,
-and ecosystems, it's **very helpful** if you can provide
-a link to information supporting your pull request.
-Up-to-date, canonical documentation that mentions the files
-to be ignored is best.
+- **Please only modify *one template* per pull request**. This helps keep pull
+  requests and feedback focused on a specific project or technology.
 
-This ensures we can efficiently go through pull requests
-and keep quality high.
+In general, the more you can do to help us understand the change you’re making,
+the more likely we’ll be to accept your contribution quickly.
 
-## Global Ignores
+Please also understand that we can’t list every tool that ever existed.
+Our aim is to curate a collection of the *most common and helpful* templates,
+not to make sure we cover every project possible. If we choose not to
+include your language, tool, or project, it’s not because it’s not awesome.
 
-git has a global configuration that applies rules to all of
-your projects. For example:
+## Contributing workflow
 
-    git config --global core.excludesfile ~/.global_ignore
+Here’s how we suggest you go about proposing a change to this project:
+
+1. [Fork this project][fork] to your account.
+2. [Create a branch][branch] for the change you intend to make.
+3. Make your changes to your fork.
+4. [Send a pull request][pr] from your fork’s branch to our `master` branch.
+
+Using the web-based interface to make changes is fine too, and will help you
+by automatically forking the project and prompting to send a pull request too.
+
+[fork]: http://help.github.com/forking/
+[branch]: https://help.github.com/articles/creating-and-deleting-branches-within-your-repository
+[pr]: http://help.github.com/pull-requests/
 
-... will apply the rules in ~/.global_ignore for all of your repos.
+## License
 
-This is useful if you use an editor (like Emacs) that drops backup files,
-or if you work in an environment that generates binary or intermediate
-files that are always ignored.
+[MIT](./LICENSE).