path: root/doc
diff options
Diffstat (limited to 'doc')
1 files changed, 345 insertions, 0 deletions
diff --git a/doc/contributing.rdoc b/doc/contributing.rdoc
new file mode 100644
index 0000000..85f7c92
--- /dev/null
+++ b/doc/contributing.rdoc
@@ -0,0 +1,345 @@
+= 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
+tracker available at {}[]. Do not
+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}[] on the
+ bug tracker.
+* Try the latest version.
+ If you aren't already using the latest version, try installing a newer
+ stable release. See
+ {Downloading Ruby}[].
+* Look to see if anyone already reported your issue, try
+ {searching on redmine}[]
+ for your problem.
+* If you can't find a ticket addressing your issue,
+ {create a new one}[].
+* 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}[] 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.
+== 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 list and the problem will be published after
+fixes have been released. You can also encrypt the issue using {the PGP public
+key}[] for the list.
+== 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,
+you'll find lots of issues already requiring attention. What can you do for
+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
+list}[] you'll find lots
+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:
+ cd path/to/ruby/trunk
+ 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
+* 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
+== How To Request Features
+If there's a new feature that you want to see added to Ruby, you'll need to
+write a convincing proposal and patch to implement the feature.
+For new features in CRuby, use the {'Feature'
+on ruby-trunk. For non-CRuby dependent features, features that would apply to
+alternate Ruby implementations such as JRuby and Rubinius, use the {CommonRuby
+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.
+A good template for feature proposal should look something like this:
+ Summary of your feature
+ Describe current behavior and why it is problem. Related work, such as
+ solutions in other language helps us to understand the problem.
+ Describe your proposal in details
+ If it has complicated feature, describe it
+ How would your feature be used? Who will benefit from it?
+ Discuss about this proposal. A list of pros and cons will help start
+ discussion.
+ Limitation of your proposal
+[Another alternative proposal]
+ If there are alternative proposals, show them.
+[See also]
+ Links to the other related resources
+== Backport Requests
+When a new version of Ruby is released it starts at patch level 0 (p0), and
+bugs will be fixed first on the trunk branch. If its determined that a bug
+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
+== Running tests
+In order to help resolve existing issues and contributing patches to Ruby you
+need to be able to run the test suite.
+CRuby uses subversion for source control, you can find installation
+instructions and lots of great info to learn subversion on the
+{}[]. For other resources see
+the {ruby-core documentation on}[].
+This guide will use git for contributing. The {git
+homepage}[] has installation instructions with links to
+documentation for learning more about git. There is a mirror of the subversion
+repository on {github}[].
+Install the prerequisite dependencies for building the CRuby interpreter to
+run tests.
+* C compiler
+* autoconf
+* bison
+* gperf
+* 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:
+* Tcl/Tk
+* Ncurses (or something)
+* OpenSSL
+* readline/editline(libedit)
+* zlib
+* libffi
+* libyaml
+* libexecinfo (FreeBSD)
+Now let's build CRuby:
+* Checkout the CRuby source code:
+ git clone git:// ruby-trunk
+* Generate the configuration files and build:
+ cd ruby-trunk
+ autoconf
+ mkdir build && cd build # its good practice to build outside of source dir
+ mkdir ~/.rubies # we will install to .rubies/ruby-trunk in our home dir
+ ../configure --prefix=~/.rubies/ruby-trunk
+ make && make install
+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
+For older versions of Ruby you'll need to run the build setup again after
+checking out the associated branch in git, for example if you wanted to
+checkout 1.9.3:
+ git clone git:// --branch ruby_1_9_3
+== Contributing Documentation
+If you're interested in contributing documentation directly to CRuby there is
+a wealth of information available at
+There is also the {Ruby Reference
+Manual}[] in Japanese.
+== Contributing A Patch
+First thing you should do is check out the code if you haven't already:
+ git clone git:// ruby-trunk
+Now create a dedicated branch:
+ cd ruby-trunk
+ 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
+trunk, or edge Ruby.
+Here are some general rules to follow when writing Ruby and C code for CRuby:
+* Indent 4 spaces for C with tabs for eight-space indentation (emacs default)
+* 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.
+* Capitalize words.
+* ABBRs should be all upper case.
+* Do as others do
+You can use the following template for the ChangeLog entry on your commit:
+ Thu Jan 1 00:00:00 2004 Your Name <>
+ * filename (function): short description of this commit.
+ This should include your intention of this change.
+ [bug:#number] [mailinglist:number]
+ * filename2 (function2): additional description for this file/function.
+This follows {GNU Coding Standards for Change
+some other requirements and tips:
+* Timestamps must be in JST (+09:00) in the style as above.
+* Two spaces between the timestamp and your name. Two spaces between
+ your name and your mail address.
+* One blank line between the timestamp and the description.
+* Indent the description with TAB. 2nd line should begin with TAB+2SP.
+* Write a entry (*) for each change.
+* Refer to redmine issue or discussion on the mailing list.
+* For GitHub issues, use [GH-#] (such as [Fixes GH-234]
+* One blank line between entries.
+* Do as other committers do.
+You can generate the ChangeLog entry by running <code>make change</code>
+When you're ready to commit, copy your ChangeLog entry into the commit message,
+keeping the same formatting and select your files:
+ git commit ChangeLog path/to/files
+In the likely event that your branch becomes outdated, you will have to update
+your working branch:
+ git fetch origin
+ git rebase remotes/origin/master
+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}[] if you get stuck here.
+here. You will also need a github account if you don't yet have one.
+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
+ # 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
+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.