2013-05-08 22:15:24 -04:00
= Contributing to Ruby
Ruby has a vast and friendly community with hundreds of people contributing to
a thriving open-source ecosystem. This guide is designed to cover ways for
participating in the development of CRuby.
There are plenty of ways for you to help even if you're not ready to write
code or documentation. You can help by reporting issues, testing patches, and
trying out beta releases with your applications.
== How To Report
If you've encountered a bug in Ruby please report it to the redmine issue
2016-09-11 06:33:36 -04:00
tracker available at {bugs.ruby-lang.org}[https://bugs.ruby-lang.org/]. Do not
2013-05-08 22:15:24 -04:00
report security vulnerabilities here, there is a {separate
channel}[rdoc-label:label-Reporting+Security+Issues] for them.
There are a few simple steps you should follow in order to receive feedback
on your ticket.
* If you haven't already,
{sign up for an account}[https://bugs.ruby-lang.org/account/register] on the
bug tracker.
* Try the latest version.
If you aren't already using the latest version, try installing a newer
stable release. See
2016-09-11 06:33:36 -04:00
{Downloading Ruby}[https://www.ruby-lang.org/en/downloads/].
2013-05-08 22:15:24 -04:00
* Look to see if anyone already reported your issue, try
{searching on redmine}[https://bugs.ruby-lang.org/projects/ruby-trunk/issues]
for your problem.
* If you can't find a ticket addressing your issue,
{create a new one}[https://bugs.ruby-lang.org/projects/ruby-trunk/issues/new].
* Choose the target version, usually current. Bugs will be first fixed in the
current release and then {backported}[rdoc-label:label-Backport+Requests].
* Fill in the Ruby version you're using when experiencing this issue
(<code>ruby -v</code>).
* Attach any logs or reproducible programs to provide additional information.
Reproducible scripts should be as small as possible.
* Briefly describe your problem. A 2-3 sentence description will help give a
quick response.
* Pick a category, such as core for common problems, or lib for a standard
library.
* Check the {Maintainers
list}[https://bugs.ruby-lang.org/projects/ruby/wiki/Maintainers] and assign
the ticket if there is an active maintainer for the library or feature.
* If the ticket doesn't have any replies after 10 days, you can send a
reminder.
* Please reply to feedback requests. If a bug report doesn't get any feedback,
it'll eventually get rejected.
2013-12-01 03:15:36 -05:00
=== Reporting to downstream distributions
2015-11-28 19:13:05 -05:00
You can report downstream issues for the following distributions via their bug tracker:
2013-12-01 03:15:36 -05:00
2018-06-30 04:11:16 -04:00
* {debian}[https://bugs.debian.org/cgi-bin/pkgreport.cgi?src=ruby-defaults]
2013-12-01 03:15:36 -05:00
* {freebsd}[http://www.freebsd.org/cgi/query-pr-summary.cgi?text=ruby]
* {redhat}[https://bugzilla.redhat.com/buglist.cgi?bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=MODIFIED]
2018-06-30 04:11:16 -04:00
* {macports}[https://trac.macports.org/query?status=assigned&status=new&status=reopened&port=~ruby]
2013-12-01 03:15:36 -05:00
* etc (add your distribution bug tracker here)
2013-12-01 03:16:20 -05:00
=== Platform Maintainers
2015-11-28 19:13:05 -05:00
For platform specific bugs in Ruby, you can assign your ticket to the current
2013-12-01 03:16:20 -05:00
maintainer for a specific platform.
The current active platform maintainers are as follows:
2017-12-25 00:16:05 -05:00
[mswin64 (Microsoft Windows)]
2013-12-01 03:16:20 -05:00
NAKAMURA Usaku (usa)
[mingw32 (Minimalist GNU for Windows)]
Nobuyoshi Nakada (nobu)
[AIX]
Yutaka Kanemoto (kanemoto)
[FreeBSD]
Akinori MUSHA (knu)
[Solaris]
Naohisa Goto (ngoto)
[RHEL, CentOS]
2018-01-08 03:12:04 -05:00
KOSAKI Motohiro (kosaki)
2017-12-25 00:16:05 -05:00
[macOS]
2013-12-01 03:16:20 -05:00
Kenta Murata (mrkn)
2019-06-01 03:52:40 -04:00
[OpenBSD]
Jeremy Evans (jeremyevans0)
2013-12-01 03:16:20 -05:00
[cygwin, bcc32, djgpp, wince, ...]
none. (Maintainer WANTED)
2013-05-08 22:15:24 -04:00
== Reporting Security Issues
Security vulnerabilities receive special treatment since they may negatively
affect many users. There is a private mailing list that all security issues
should be reported to and will be handled discretely. Email the
mailto:security@ruby-lang.org list and the problem will be published after
fixes have been released. You can also encrypt the issue using {the PGP public
2016-09-11 06:33:36 -04:00
key}[https://www.ruby-lang.org/security.asc] for the list.
2013-05-08 22:15:24 -04:00
2013-12-01 03:17:11 -05:00
== Reporting Other Issues
If you're having an issue with the website, or maybe the mailing list, you can
contact the webmaster to help resolve the problem.
The current webmaster is:
* Hiroshi SHIBATA (hsbt)
You can also report issues with the ruby-lang.org website on the issue tracker:
* {issue tracker}[https://github.com/ruby/www.ruby-lang.org/issues]
2013-05-08 22:15:24 -04:00
== Resolve Existing Issues
As a next step beyond reporting issues you can help the core team resolve
existing issues. If you check the Everyone's Issues list in GitHub Issues,
2015-11-28 19:13:05 -05:00
you will find a lot of issues already requiring attention. What can you do for
2013-05-08 22:15:24 -04:00
these? Quite a bit, actually:
When a bug report goes for a while without any feedback, it goes to the bug
graveyard which is unfortunate. If you check the {issues
2015-11-28 19:13:05 -05:00
list}[https://bugs.ruby-lang.org/projects/ruby-trunk/issues] you will find lots
2013-05-08 22:15:24 -04:00
of delinquent bugs that require attention.
You can help by verifying the existing tickets, try to reproduce the reported
issue on your own and comment if you still experience the bug. Some issues
lack attention because of too much ambiguity, to help you can narrow down the
problem and provide more specific details or instructions to reproduce the
bug. You might also try contributing a failing test in the form of a patch,
which we will cover later in this guide.
It may also help to try out patches other contributors have submitted to
redmine, if gone without notice. In this case the +patch+ command is your
friend, see <code>man patch</code> for more information. Basically this would
go something like this:
2019-07-01 20:34:08 -04:00
cd path/to/ruby
2013-05-08 22:15:24 -04:00
patch -p0 < path/to/patch
You will then be prompted to apply the patch with the associated files. After
building ruby again, you should try to run the tests and verify if the change
actually worked or fixed the bug. It's important to provide valuable feedback
on the patch that can help reach the overall goal, try to answer some of these
questions:
* What do you like about this change?
* What would you do differently?
* Are there any other edge cases not tested?
* Is there any documentation that would be affected by this change?
If you can answer some or all of these questions, you're on the right track.
If your comment simply says "+1", then odds are that other reviewers aren't
going to take it too seriously. Show that you took the time to review the
patch.
== How To Request Features
2015-11-28 19:13:05 -05:00
If there's a new feature that you want to see added to Ruby, you will need to
2013-05-08 22:15:24 -04:00
write a convincing proposal and patch to implement the feature.
For new features in CRuby, use the {'Feature'
tracker}[https://bugs.ruby-lang.org/projects/ruby-trunk/issues?set_filter=1&tracker_id=2]
2019-07-01 20:34:08 -04:00
on ruby-master. For non-CRuby dependent features, features that would apply to
2013-05-08 22:15:24 -04:00
alternate Ruby implementations such as JRuby and Rubinius, use the {CommonRuby
tracker}[https://bugs.ruby-lang.org/projects/common-ruby].
When writing a proposal be sure to check for previous discussions on the
topic and have a solid use case. You will need to be persuasive and convince
Matz on your new feature. You should also consider the potential compatibility
issues that this new feature might raise.
Consider making your feature into a gem, and if there are enough people who
benefit from your feature it could help persuade ruby-core. Although feature
requests can seem like an alluring way to contribute to Ruby, often these
discussions can lead nowhere and exhaust time and energy that could be better
spent fixing bugs. Choose your battles.
2015-11-28 19:13:05 -05:00
A good template for a feature proposal should look something like this:
2013-05-08 22:15:24 -04:00
[Abstract]
Summary of your feature
[Background]
Describe current behavior and why it is problem. Related work, such as
solutions in other language helps us to understand the problem.
[Proposal]
Describe your proposal in details
[Details]
If it has complicated feature, describe it
[Usecase]
How would your feature be used? Who will benefit from it?
[Discussion]
Discuss about this proposal. A list of pros and cons will help start
discussion.
[Limitation]
Limitation of your proposal
[Another alternative proposal]
If there are alternative proposals, show them.
[See also]
Links to the other related resources
2013-11-28 05:29:54 -05:00
=== Slideshow
2015-11-28 19:13:05 -05:00
At the Ruby Developer Meeting in Japan, committers discuss Feature Proposals together in Tokyo. We will judge proposals and then accept, reject, or give feedback for them.
If you have a stalled proposal, making a slide to submit is good way to get feedback.
2013-11-28 05:29:54 -05:00
Slides should be:
* One-page slide
* Include a corresponding ticket number
* MUST include a figure and/or short example code
* SHOULD have less sentence in natural language (try to write less than 140 characters)
2013-12-12 21:21:09 -05:00
* It is RECOMMENDED to itemize: motivation/use case, proposal, pros/cons, corner case
2013-11-28 05:29:54 -05:00
* PDF or Image (Web browsers can show it)
Please note:
* Even if the proposal is generally acceptable, it won't be accepted without writing corner cases in the ticket
2013-12-12 02:21:19 -05:00
* Slide's example: DevelopersMeeting20130727Japan
2013-11-28 05:29:54 -05:00
2013-05-08 22:15:24 -04:00
== Backport Requests
2015-11-28 19:13:05 -05:00
When a new version of Ruby is released, it starts at patch level 0 (p0), and
2019-07-01 20:34:08 -04:00
bugs will be fixed first on the master branch. If it's determined that a bug
2013-05-08 22:15:24 -04:00
exists in a previous version of Ruby that is still in the bug fix stage of
maintenance, then a patch will be backported. After the maintenance stage of a
particular Ruby version ends, it goes into "security fix only" mode which
means only security related vulnerabilities will be backported. Versions in
End-of-life (EOL) will not receive any updates and it is recommended you
upgrade as soon as possible.
If a major security issue is found or after a certain amount of time since the
last patch level release, a new patch-level release will be made.
When submitting a backport request please confirm the bug has been fixed in
newer versions and exists in maintenance mode versions. There is a backport
tracker for each major version still in maintenance where you can request a
particular revision merged in the affected version of Ruby.
Each major version of Ruby has a release manager that should be assigned to
handle backport requests. You can find the list of release managers on the
{wiki}[https://bugs.ruby-lang.org/projects/ruby/wiki/ReleaseEngineering].
2015-12-24 13:06:31 -05:00
=== Branches
2013-12-01 03:18:04 -05:00
2015-12-24 13:06:31 -05:00
Status and maintainers of branches are listed on the
{wiki}[https://bugs.ruby-lang.org/projects/ruby/wiki/ReleaseEngineering].
2013-12-01 03:18:04 -05:00
2013-05-08 22:15:24 -04:00
== Running tests
In order to help resolve existing issues and contributing patches to Ruby you
need to be able to run the test suite.
2019-04-22 06:02:17 -04:00
CRuby uses git for source control, the {git homepage}[https://git-scm.com/]
has installation instructions with links to documentation for learning more
about git. There is a mirror of the repository on {github}[https://github.com/ruby/ruby].
2019-10-15 07:18:06 -04:00
For other resources see the {ruby-core documentation on
2016-09-11 06:33:36 -04:00
ruby-lang.org}[https://www.ruby-lang.org/en/community/ruby-core/].
2013-05-08 22:15:24 -04:00
Install the prerequisite dependencies for building the CRuby interpreter to
run tests.
* C compiler
2019-08-03 01:56:41 -04:00
* autoconf - 2.67 or later, preferably 2.69.
* bison - 2.0 or later, preferably 3.4.
* gperf - 3.0.3 or later, preferably 3.1.
2013-05-08 22:15:24 -04:00
* ruby - Ruby itself is prerequisite in order to build Ruby from source. It
can be 1.8.
You should also have access to development headers for the following
libraries, but these are not required:
* NDBM/QDBM
* GDBM
2019-07-01 20:26:18 -04:00
* OpenSSL/LibreSSL
2013-05-08 22:15:24 -04:00
* readline/editline(libedit)
* zlib
* libffi
* libyaml
* libexecinfo (FreeBSD)
Now let's build CRuby:
* Checkout the CRuby source code:
2019-07-01 20:34:08 -04:00
git clone https://github.com/ruby/ruby.git ruby-master
2013-05-08 22:15:24 -04:00
* Generate the configuration files and build:
2019-07-01 20:34:08 -04:00
cd ruby-master
2013-05-08 22:15:24 -04:00
autoconf
mkdir build && cd build # its good practice to build outside of source dir
2019-07-01 20:34:08 -04:00
mkdir ~/.rubies # we will install to .rubies/ruby-master in our home dir
../configure --prefix="${HOME}/.rubies/ruby-master"
2016-01-03 10:24:10 -05:00
make up && make install
2013-05-08 22:15:24 -04:00
After adding Ruby to your PATH, you should be ready to run the test suite:
make test
You can also use +test-all+ to run all of the tests with the RUNRUBY
interpreter just built. Use TESTS or RUNRUBYOPT to pass parameters, such as:
make test-all TESTS=-v
This is also how you can run a specific test from our build dir:
make test-all TESTS=drb/test_drb.rb
2016-01-03 10:24:10 -05:00
You can run +test+ and +test-all+ at once by +check+ .
make check
2015-11-28 19:13:05 -05:00
For older versions of Ruby you will need to run the build setup again after
2013-05-08 22:15:24 -04:00
checking out the associated branch in git, for example if you wanted to
checkout 1.9.3:
2018-07-27 23:34:30 -04:00
git clone https://github.com/ruby/ruby.git --branch ruby_1_9_3
2013-05-08 22:15:24 -04:00
2016-01-03 10:24:10 -05:00
Once you checked out the source code, you can update the local copy by:
make up
Or, update, build, install and check, by just:
make love
2013-05-08 22:15:24 -04:00
== Contributing Documentation
If you're interested in contributing documentation directly to CRuby there is
2018-09-05 19:15:02 -04:00
some information available at
{Contributing}[https://github.com/ruby/ruby#contributing].
2013-05-08 22:15:24 -04:00
There is also the {Ruby Reference
2018-06-30 04:10:58 -04:00
Manual}[https://github.com/rurema/doctree/wiki] in Japanese.
2013-05-08 22:15:24 -04:00
== Contributing A Patch
2013-11-28 07:15:59 -05:00
=== Deciding what to patch
Before you submit a patch, there are a few things you should know:
* Pay attention to the maintenance policy for stable and maintained versions of Ruby.
* Released versions in security mode will not merge feature changes.
* Search for previous discussions on ruby-core to verify the maintenance policy
* Patches must be distributed under Ruby's license.
* This license may change in the future, you must join the discussion if you don't agree to the change
To improve the chance your patch will be accepted please follow these simple rules:
2019-07-01 20:34:08 -04:00
* Bug fixes should be committed on master first
2013-11-28 07:15:59 -05:00
* Format of the patch file must be a unified diff (ie: diff -pu, svn diff, or git diff)
* Don't introduce cosmetic changes
* Follow the original coding style of the code
* Don't mix different changes in one commit
2013-05-08 22:15:24 -04:00
First thing you should do is check out the code if you haven't already:
2019-07-01 20:34:08 -04:00
git clone https://github.com/ruby/ruby.git ruby-master
2013-05-08 22:15:24 -04:00
Now create a dedicated branch:
2019-07-01 20:34:08 -04:00
cd ruby-master
2013-05-08 22:15:24 -04:00
git checkout -b my_new_branch
The name of your branch doesn't really matter because it will only exist on
your local computer and won't be part of the official Ruby repository. It will
be used to create patches based on the differences between your branch and
2019-07-01 20:34:08 -04:00
master, or edge Ruby.
2013-05-08 22:15:24 -04:00
2013-11-28 07:17:11 -05:00
=== Coding style
2013-05-08 22:15:24 -04:00
Here are some general rules to follow when writing Ruby and C code for CRuby:
2018-06-30 21:38:14 -04:00
* Indent 4 spaces for C without tabs (old codes might use tabs for eight-space indentation,
but newer codes recommend to use spaces only)
2013-05-08 22:15:24 -04:00
* Indent 2 space tabs for Ruby
* Do not use TABs in ruby codes
* ANSI C style for 1.9+ for function declarations
* Follow C90 (not C99) Standard
* PascalStyle for class/module names.
* UNDERSCORE_SEPARATED_UPPER_CASE for other constants.
* Capitalize words.
* ABBRs should be all upper case.
* Do as others do
2019-06-17 18:48:44 -04:00
=== Commit messages
2013-11-28 07:18:35 -05:00
2019-06-17 18:48:44 -04:00
When you're ready to commit:
2013-11-28 07:18:35 -05:00
2019-06-17 18:48:44 -04:00
git commit path/to/files
2013-05-08 22:15:24 -04:00
2019-06-17 18:48:44 -04:00
This will open your editor in which you write your commit message.
Use the following style for commit messages:
2013-05-08 22:15:24 -04:00
2019-12-19 19:19:39 -05:00
* Use a succinct subject line.
2019-06-17 18:48:44 -04:00
* Include reasoning behind the change in the commit message, focusing on why
the change is being made.
* Refer to redmine issue (such as Fixes [Bug #1234] or Implements
[Feature #3456]), or discussion on the mailing list
(such as [ruby-core:12345]).
* For GitHub issues, use [GH-#] (such as [Fixes GH-234]).
* Follow the style used by other committers.
2013-05-08 22:15:24 -04:00
2019-06-17 18:48:44 -04:00
=== Contributing your code
2013-05-08 22:15:24 -04:00
Now that you've got some code you want to contribute, let's get set up to
generate a patch. Start by forking the github mirror, check the {github docs on
forking}[https://help.github.com/articles/fork-a-repo] if you get stuck here.
2015-12-22 12:18:59 -05:00
You will only need a github account if you intend to host your repository
2014-01-28 13:42:39 -05:00
on github.
2013-05-08 22:15:24 -04:00
Next copy the writable url for your fork and add it as a git remote, replace
"my_username" with your github account name:
git remote add my_fork git@github.com:my_username/ruby.git
# Now we can push our branch to our fork
git push my_fork my_new_branch
In order to generate a patch that you can upload to the bug tracker, we can use
the github interface to review our changes just visit
2019-07-01 20:34:08 -04:00
https://github.com/my_username/ruby/compare/master...my_new_branch
2013-05-08 22:15:24 -04:00
Next, you can simply add '.patch' to the end of this URL and it will generate
the patch for you, save the file to your computer and upload it to the bug
tracker. Alternatively you can submit a pull request, but for the best chances
to receive feedback add it is recommended you add it to redmine.
2014-01-28 13:42:39 -05:00
Since git is a distributed system, you are welcome to host your git repository
2015-12-24 18:23:46 -05:00
on any {publicly accessible hosting
2014-01-28 13:42:39 -05:00
site}[https://git.wiki.kernel.org/index.php/GitHosting], including {hosting your
own}[https://www.kernel.org/pub/software/scm/git/docs/user-manual.html#public-repositories]
2018-06-30 04:11:16 -04:00
You may use the {'git format-patch'}[https://git-scm.com/docs/git-format-patch]
2014-01-28 13:42:39 -05:00
command to generate patch files to upload to redmine. You may also use
2018-06-30 04:11:16 -04:00
the {'git request-pull'}[https://git-scm.com/docs/git-request-pull] command for
2014-01-28 13:42:39 -05:00
formatting pull request messages to redmine.
2019-06-17 18:48:44 -04:00
=== Updating the official repository
If you are a committer, you can push changes directly into the official
repository:
git push origin your-branch-name:master
However, it is likely will have become outdated, and you will have to
update it. In that case, run:
git fetch origin
git rebase remotes/origin/master
and then try pushing your changes again.