Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great.
Contributions to this project are released to the public under the project's open source license.
This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.
The majority of contributions won't need to touch any Ruby code at all.
Linguist uses the charlock_holmes
character encoding detection library which in turn uses ICU, and the libgit2 bindings for Ruby provided by rugged
.
Bundler v1.10.0 or newer is required for installing the Ruby gem dependencies.
Docker is also required when adding or updating grammars.
These components have their own dependencies - icu4c
, and cmake
and pkg-config
respectively - which you may need to install before you can install Linguist.
For example, on macOS with Homebrew:
brew install cmake pkg-config icu4c
brew cask install docker
On Ubuntu:
apt-get install cmake pkg-config libicu-dev docker-ce
The latest version of Bundler v1 can be installed with gem install bundler -v "~>1.10"
.
Before you can start contributing to Linguist, you'll need to set up your environment first.
Clone the repo and run script/bootstrap
to install its dependencies.
git clone https://github.com/github/linguist.git
cd linguist/
script/bootstrap
To run Linguist from the cloned repository, you will need to generate the code samples first:
bundle exec rake samples
Run this command each time a sample has been modified.
To run Linguist from the cloned repository:
bundle exec bin/github-linguist --breakdown
We try only to add new extensions once they have some usage on GitHub. In most cases we prefer that extensions be in use in hundreds of repositories before supporting them in Linguist.
To add support for a new extension:
languages.yml
.
Keep the extensions in alphabetical order, sorted case-sensitively (uppercase before lowercase).
The exception is the primary extension: it should always be first.Additionally, if this extension is already listed in languages.yml
and associated with another language, then sometimes a few more steps will need to be taken:
.yourextension
files are present in the samples directory for each language that uses .yourextension
..yourextension
files (ping @lildude to help with this).
This ensures we're not misclassifying files..yourextension
files then a heuristic may need to be written to help.We try only to add languages once they have some usage on GitHub. In most cases we prefer that each new file extension be in use in hundreds of repositories before supporting them in Linguist.
To add support for a new language:
languages.yml
.
Omit the language_id
field for now.script/add-grammar https://github.com/JaneSmith/MyGrammar
script/update-ids
.In addition, if your new language defines an extension that's already listed in languages.yml
(such as .foo
) then sometimes a few more steps will need to be taken:
.foo
files are present in the samples directory for each language that uses .foo
..foo
files (ping @lildude to help with this).
This ensures we're not misclassifying files..foo
files, then a heuristic may need to be written to help.Remember, the goal here is to try and avoid false positives!
Most languages are detected by their file extension defined in languages.yml
.
For disambiguating between files with common extensions, Linguist applies some heuristics and a statistical classifier.
This process can help differentiate between, for example, .h
files which could be either C, C++, or Obj-C.
Misclassifications can often be solved by either adding a new filename or extension for the language or adding more samples to make the classifier smarter.
Syntax highlighting in GitHub is performed using TextMate-compatible grammars.
These are the same grammars used by TextMate, Sublime Text, and Atom.
Every language in languages.yml
is mapped to its corresponding TextMate scopeName
.
This scope name will be used when picking up a grammar for highlighting.
Assuming your code is being detected as the right language, in most cases syntax highlighting problems are due to a bug in the language grammar rather than a bug in Linguist.
vendor/README.md
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.
If you can, try to reproduce the highlighting problem in the text editor that the grammar is designed for (TextMate, Sublime Text, or Atom) and include that information in your bug report.
You can also try to fix the bug yourself and submit a pull-request. TextMate's documentation offers a good introduction on how to work with TextMate-compatible grammars. Note that Linguist uses PCRE regular expressions, while TextMate uses Oniguruma. Although they are mostly compatible there might be some differences in syntax and semantics between the two. You can test grammars using Lightshow.
Once the bug has been fixed upstream, we'll pick it up for GitHub in the next release of Linguist.
We'd like to ensure Linguist and GitHub.com are using the latest and greatest grammars that are consistent with the current usage but understand that sometimes a grammar can lag behind the evolution of a language or even stop being developed. This often results in someone grasping the opportunity to create a newer and better and more actively maintained grammar, and we'd love to use it and pass on it's functionality to our users.
Switching the source of a grammar is really easy:
script/add-grammar --replace MyGrammar https://github.com/PeterPan/MyGrammar
This command will analyze the grammar and, if no problems are found, add it to the repository. If problems are found, please report these problems to the grammar maintainer as you will not be able to add the grammar if problems are found.
Please only add grammars that have one of these licenses.
Please then open a pull request for the updated grammar.
Many of the colors associated with the languages within Linguist have been in place for a very long time. The colors were often chosen based on the colors used by the language at the time and since then users will have become familiar with those colors as they appear on GitHub.com. If you would like to change the color of a language, we ask that you propose your suggested color change to the wider community for your language to gain consensus before submitting a pull request. Please do this in a community forum or repository used and known by the wider community of that language, not the Linguist repository.
Once you've received consensus that the community is happy with your proposed color change, please feel free to open a PR making the change and link to the public discussion where this was agreed by the community. If there are official branding guidelines to support the colour choice, please link to those too.
Please note that Linguist currently implements a color proximity test to ensure colors are sufficiently different from one another so you may not be able to use the precise color you want - reds and blues are really popular. As such, we recommend you test the color change locally before making your plea to the wider language community.
You can run the tests locally with:
bundle exec rake test
Sometimes getting the tests running can be too much work, especially if you don't have much Ruby experience. It's okay: be lazy and let GitHub Actions run the tests for you. Just open a pull request and the bot will start cranking away.
Here's our current build status:
Linguist is maintained with by:
As Linguist is a production dependency for GitHub we have a couple of workflow restrictions:
If you are the current maintainer of this gem:
git checkout -b release-vxx.xx.xx
script/bootstrap
git submodule update --remote
.
If any submodules are updated:
grammars.yml
: script/grammar-compiler update -f
script/licensed
script/licensed status
bundle exec rake check_grammars
git commit -a
bundle exec rake samples
bundle exec rake test
GEM_VERSION=$(git describe --tags 2>/dev/null | sed 's/-/./g' | sed 's/v//') bundle exec rake build_gem
lib/linguist/VERSION
, like this.bundle exec rake build_gem
git tag vx.xx.xx; git push --tags
git log --pretty=format:"- %s" --reverse refs/tags/[OLD TAG]...refs/tags/[NEW TAG]
like this
./script/build-grammars-tarball
) and attach it to the GitHub releasegem push --key github --host https://rubygems.pkg.github.com/github github-linguist-3.0.0.gem
. See Configuring RubyGems for use with GitHub Package Registry for more details.gem push github-linguist-3.0.0.gem
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。