diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..26c94272 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,31 @@ +## Contributing + +The majority of contributions won't need to touch any Ruby code at all. The [master language list][languages] is just a YAML configuration file. + +Almost all bug fixes or new language additions should come with some additional code samples. Just drop them under [`samples/`][samples] in the correct subdirectory and our test suite will automatically test them. In most cases you shouldn't need to add any new assertions. + +### My code is detected as the wrong language + +This can usually be solved either by adding a new filename or file name extension to the language's entry in [`languages.yml`][languages] or adding more [samples][samples] for your language to the repository to make Linguist's classifier smarter. + +### Syntax highlighting looks wrong + +Assuming your code is being detected as the right language (see above), in most cases this is due to a bug in the language grammar rather than a bug in Linguist. [`grammars.yml`][grammars] lists all the grammars we use for syntax highlighting on github.com. Find the one corresponding to your code's programming language and submit a bug report upstream. + +You can also try to fix the bug yourself and submit a Pull Request. [This piece from TextMate's documentation](http://manual.macromates.com/en/language_grammars) offers a good introduction on how to work with TextMate-compatible grammars. + +Once the bug has been fixed upstream, please let us know and we'll pick it up for GitHub. + +### I want to add support for the `X` programming language + +Great! You'll need to: + +0. Add an entry for your language to [`languages.yml`][languages]. +0. Add a grammar for your language to [`grammars.yml`][grammars]. Please use `script/download-grammars --add URL` to add the grammar. +0. Add samples for your language to the [samples directory][samples]. + +We try only to add languages once they have some usage on GitHub, so please note in-the-wild usage examples in your pull request. + +[grammars]: /grammars.yml +[languages]: /lib/linguist/languages.yml +[samples]: /samples diff --git a/README.md b/README.md index 36d1fcd2..4eacde73 100644 --- a/README.md +++ b/README.md @@ -26,15 +26,7 @@ See [lib/linguist/language.rb](https://github.com/github/linguist/blob/master/li Syntax highlighting in GitHub is performed using TextMate-compatible grammars. These are the same grammars that TextMate, Sublime Text and Atom use. -Every language in `languages.yml` is mapped to its corresponding TM `scope`. This scope will be used when picking up a grammar for highlighting. **When adding a new language to Linguist, please add its corrsponding scope too (assuming there's an existing TextMate bundle) so syntax highlighting works for it**. - -#### I found a bug! - -The `grammars.yml` file contains the list of all the repositories where we fetch TextMate grammars for highlighting. If you find a bug in the highlighting for any given language, please consult this Grammars list to find the source of the grammar, and submit the bug report upstream. - -You can also try to fix the bug yourself and submit a Pull Request. [This piece from TextMate's documentation](http://manual.macromates.com/en/language_grammars) offers a good introduction on how to work with TextMate-compatible grammars. - -Once the bug has been fixed upstream, please let us know and we'll pick it up for GitHub. +Every language in `languages.yml` is mapped to its corresponding TM `scope`. This scope will be used when picking up a grammar for highlighting. **When adding a new language to Linguist, please add its corresponding scope too (assuming there's an existing TextMate bundle, Sublime Text package, or Atom package) so syntax highlighting works for it**. ### Stats @@ -153,14 +145,6 @@ To run the tests: bundle exec rake test -## Contributing - -The majority of contributions won't need to touch any Ruby code at all. The [master language list](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml) is just a YAML configuration file. - -We try to only add languages once they have some usage on GitHub, so please note in-the-wild usage examples in your pull request. - -Almost all bug fixes or new language additions should come with some additional code samples. Just drop them under [`samples/`](https://github.com/github/linguist/tree/master/samples) in the correct subdirectory and our test suite will automatically test them. In most cases you shouldn't need to add any new assertions. - ### A note on language extensions Linguist has a number of methods available to it for identifying the language of a particular file. The initial lookup is based upon the extension of the file, possible file extensions are defined in an array called `extensions`. Take a look at this example for example for `Perl`: