U:RDoc::TopLevel[ iI"contributing.rdoc:EFcRDoc::Parser::Simpleo:RDoc::Markup::Document: @parts[»S:RDoc::Markup::Heading: leveli: textI"Contributing to Ruby;To:RDoc::Markup::BlankLineo:RDoc::Markup::Paragraph;[I"TRuby has a vast and friendly community with hundreds of people contributing to ;TI"Pa thriving open-source ecosystem. This guide is designed to cover ways for ;TI"/participating in the development of CRuby.;T@ o; ;[I"PThere are plenty of ways for you to help even if you're not ready to write ;TI"Tcode or documentation. You can help by reporting issues, testing patches, and ;TI"5trying out beta releases with your applications.;T@ S; ; i; I"How To Report;T@ o; ;[ I"OIf you've encountered a bug in Ruby please report it to the redmine issue ;TI"Utracker available at {bugs.ruby-lang.org}[https://bugs.ruby-lang.org/]. Do not ;TI"@report security vulnerabilities here, there is a {separate ;TI"Cchannel}[rdoc-label:label-Reporting+Security+Issues] for them.;T@ o; ;[I"QThere are a few simple steps you should follow in order to receive feedback ;TI"on your ticket.;T@ o:RDoc::Markup::List: @type: BULLET: @items[o:RDoc::Markup::ListItem: @label0;[o; ;[I"If you haven't already, ;TI"R{sign up for an account}[https://bugs.ruby-lang.org/account/register] on the ;TI"bug tracker.;To;;0;[o; ;[I"Try the latest version.;T@ o; ;[I"LIf you aren't already using the latest version, try installing a newer ;TI"stable release. See ;TI"A{Downloading Ruby}[https://www.ruby-lang.org/en/downloads/].;To;;0;[o; ;[I"ruby -v).;To;;0;[o; ;[I"QAttach any logs or reproducible programs to provide additional information. ;TI"9Reproducible scripts should be as small as possible.;To;;0;[o; ;[I"QBriefly describe your problem. A 2-3 sentence description will help give a ;TI"quick response.;To;;0;[o; ;[I"NPick a category, such as core for common problems, or lib for a standard ;TI" library.;To;;0;[o; ;[I"Check the {Maintainers ;TI"Qlist}[https://bugs.ruby-lang.org/projects/ruby/wiki/Maintainers] and assign ;TI"Lthe ticket if there is an active maintainer for the library or feature.;To;;0;[o; ;[I"JIf the ticket doesn't have any replies after 10 days, you can send a ;TI"reminder.;To;;0;[o; ;[I"RPlease reply to feedback requests. If a bug report doesn't get any feedback, ;TI"#it'll eventually get rejected.;T@ S; ; i; I"*Reporting to downstream distributions;T@ o; ;[I"\You can report downstream issues for the following distributions via their bug tracker:;T@ o;;;;[ o;;0;[o; ;[I"M{debian}[http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=ruby-defaults];To;;0;[o; ;[I"I{freebsd}[http://www.freebsd.org/cgi/query-pr-summary.cgi?text=ruby];To;;0;[o; ;[I"|{redhat}[https://bugzilla.redhat.com/buglist.cgi?bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=MODIFIED];To;;0;[o; ;[I"e{macports}[http://trac.macports.org/query?status=assigned&status=new&status=reopened&port=~ruby];To;;0;[o; ;[I"1etc (add your distribution bug tracker here);T@ S; ; i; I"Platform Maintainers;T@ o; ;[I"SFor platform specific bugs in Ruby, you can assign your ticket to the current ;TI"(maintainer for a specific platform.;T@ o; ;[I"graveyard which is unfortunate. If you check the {issues ;TI"Ulist}[https://bugs.ruby-lang.org/projects/ruby-trunk/issues] you will find lots ;TI"/of delinquent bugs that require attention.;T@ o; ;[ I"SYou can help by verifying the existing tickets, try to reproduce the reported ;TI"Pissue on your own and comment if you still experience the bug. Some issues ;TI"Slack attention because of too much ambiguity, to help you can narrow down the ;TI"Pproblem and provide more specific details or instructions to reproduce the ;TI"Qbug. You might also try contributing a failing test in the form of a patch, ;TI"-which we will cover later in this guide.;T@ o; ;[ I"NIt may also help to try out patches other contributors have submitted to ;TI"Oredmine, if gone without notice. In this case the +patch+ command is your ;TI"Sfriend, see man patch for more information. Basically this would ;TI"go something like this:;T@ o:RDoc::Markup::Verbatim;[I"cd path/to/ruby/trunk ;TI"patch -p0 < path/to/patch ;T: @format0o; ;[ I"SYou will then be prompted to apply the patch with the associated files. After ;TI"Sbuilding ruby again, you should try to run the tests and verify if the change ;TI"Sactually worked or fixed the bug. It's important to provide valuable feedback ;TI"Ton the patch that can help reach the overall goal, try to answer some of these ;TI"questions:;T@ o;;;;[ o;;0;[o; ;[I"(What do you like about this change?;To;;0;[o; ;[I"#What would you do differently?;To;;0;[o; ;[I"/Are there any other edge cases not tested?;To;;0;[o; ;[I"FIs there any documentation that would be affected by this change?;T@ o; ;[ I"RIf you can answer some or all of these questions, you're on the right track. ;TI"QIf your comment simply says "+1", then odds are that other reviewers aren't ;TI"Ogoing to take it too seriously. Show that you took the time to review the ;TI" patch.;T@ S; ; i; I"How To Request Features;T@ o; ;[I"SIf there's a new feature that you want to see added to Ruby, you will need to ;TI"Dwrite a convincing proposal and patch to implement the feature.;T@ o; ;[ I"3For new features in CRuby, use the {'Feature' ;TI"_tracker}[https://bugs.ruby-lang.org/projects/ruby-trunk/issues?set_filter=1&tracker_id=2] ;TI"Son ruby-trunk. For non-CRuby dependent features, features that would apply to ;TI"Talternate Ruby implementations such as JRuby and Rubinius, use the {CommonRuby ;TI"?tracker}[https://bugs.ruby-lang.org/projects/common-ruby].;T@ o; ;[ I"NWhen writing a proposal be sure to check for previous discussions on the ;TI"Rtopic and have a solid use case. You will need to be persuasive and convince ;TI"TMatz on your new feature. You should also consider the potential compatibility ;TI".issues that this new feature might raise.;T@ o; ;[ I"QConsider making your feature into a gem, and if there are enough people who ;TI"Rbenefit from your feature it could help persuade ruby-core. Although feature ;TI"Orequests can seem like an alluring way to contribute to Ruby, often these ;TI"Sdiscussions can lead nowhere and exhaust time and energy that could be better ;TI",spent fixing bugs. Choose your battles.;T@ o; ;[I"LA good template for a feature proposal should look something like this:;T@ o;;;;[o;;[I" Abstract;T;[o; ;[I"Summary of your feature;To;;[I"Background;T;[o; ;[I"LDescribe current behavior and why it is problem. Related work, such as ;TI"Dsolutions in other language helps us to understand the problem.;To;;[I" Proposal;T;[o; ;[I"&Describe your proposal in details;To;;[I" Details;T;[o; ;[I"/If it has complicated feature, describe it;To;;[I" Usecase;T;[o; ;[I">How would your feature be used? Who will benefit from it?;To;;[I"Discussion;T;[o; ;[I"JDiscuss about this proposal. A list of pros and cons will help start ;TI"discussion.;To;;[I"Limitation;T;[o; ;[I" Limitation of your proposal;To;;[I"!Another alternative proposal;T;[o; ;[I"3If there are alternative proposals, show them.;To;;[I" See also;T;[o; ;[I")Links to the other related resources;T@ S; ; i; I"Slideshow;T@ o; ;[I"¬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. ;TI"ZIf you have a stalled proposal, making a slide to submit is good way to get feedback.;T@ o; ;[I"Slides should be:;T@ o;;;;[ o;;0;[o; ;[I"One-page slide;To;;0;[o; ;[I"*Include a corresponding ticket number;To;;0;[o; ;[I"4MUST include a figure and/or short example code;To;;0;[o; ;[I"ZSHOULD have less sentence in natural language (try to write less than 140 characters);To;;0;[o; ;[I"XIt is RECOMMENDED to itemize: motivation/use case, proposal, pros/cons, corner case;To;;0;[o; ;[I",PDF or Image (Web browsers can show it);T@ o; ;[I"Please note:;T@ o;;;;[o;;0;[o; ;[I"rEven if the proposal is generally acceptable, it won't be accepted without writing corner cases in the ticket;To;;0;[o; ;[I"4Slide's example: DevelopersMeeting20130727Japan;T@ S; ; i; I"Backport Requests;T@ o; ;[ I"RWhen a new version of Ruby is released, it starts at patch level 0 (p0), and ;TI"Qbugs will be fixed first on the trunk branch. If it's determined that a bug ;TI"Pexists in a previous version of Ruby that is still in the bug fix stage of ;TI"Tmaintenance, then a patch will be backported. After the maintenance stage of a ;TI"Oparticular Ruby version ends, it goes into "security fix only" mode which ;TI"Qmeans only security related vulnerabilities will be backported. Versions in ;TI"NEnd-of-life (EOL) will not receive any updates and it is recommended you ;TI"!upgrade as soon as possible.;T@ o; ;[I"TIf a major security issue is found or after a certain amount of time since the ;TI"Flast patch level release, a new patch-level release will be made.;T@ o; ;[ I"QWhen submitting a backport request please confirm the bug has been fixed in ;TI"Qnewer versions and exists in maintenance mode versions. There is a backport ;TI"Qtracker for each major version still in maintenance where you can request a ;TI"@particular revision merged in the affected version of Ruby.;T@ o; ;[I"QEach major version of Ruby has a release manager that should be assigned to ;TI"Phandle backport requests. You can find the list of release managers on the ;TI"N{wiki}[https://bugs.ruby-lang.org/projects/ruby/wiki/ReleaseEngineering].;T@ S; ; i; I" Branches;T@ o; ;[I":Status and maintainers of branches are listed on the ;TI"N{wiki}[https://bugs.ruby-lang.org/projects/ruby/wiki/ReleaseEngineering].;T@ S; ; i; I"Running tests;T@ o; ;[I"SIn order to help resolve existing issues and contributing patches to Ruby you ;TI"+need to be able to run the test suite.;T@ o; ;[ I"ICRuby uses subversion for source control, you can find installation ;TI"Dinstructions and lots of great info to learn subversion on the ;TI"S{svnbook.red-bean.com}[http://svnbook.red-bean.com/]. For other resources see ;TI"%the {ruby-core documentation on ;TI"Gruby-lang.org}[https://www.ruby-lang.org/en/community/ruby-core/].;T@ o; ;[ I"9This guide will use git for contributing. The {git ;TI"Phomepage}[http://git-scm.com/] has installation instructions with links to ;TI"Tdocumentation for learning more about git. There is a mirror of the subversion ;TI":repository on {github}[https://github.com/ruby/ruby].;T@ o; ;[I"QInstall the prerequisite dependencies for building the CRuby interpreter to ;TI"run tests.;T@ o;;;;[ o;;0;[o; ;[I"C compiler;To;;0;[o; ;[I" autoconf;To;;0;[o; ;[I" bison;To;;0;[o; ;[I" gperf;To;;0;[o; ;[I"Oruby - Ruby itself is prerequisite in order to build Ruby from source. It ;TI"can be 1.8.;T@ o; ;[I"JYou should also have access to development headers for the following ;TI"+libraries, but these are not required:;T@ o;;;;[o;;0;[o; ;[I" Tcl/Tk;To;;0;[o; ;[I"NDBM/QDBM;To;;0;[o; ;[I" GDBM;To;;0;[o; ;[I" OpenSSL;To;;0;[o; ;[I"readline/editline(libedit);To;;0;[o; ;[I" zlib;To;;0;[o; ;[I" libffi;To;;0;[o; ;[I" libyaml;To;;0;[o; ;[I"libexecinfo (FreeBSD);T@ o; ;[I"Now let's build CRuby:;T@ o;;;;[o;;0;[o; ;[I"$Checkout the CRuby source code:;T@ o;;[I"9git clone git://github.com/ruby/ruby.git ruby-trunk ;T;0o;;0;[o; ;[I"0Generate the configuration files and build:;T@ o;;[ I"cd ruby-trunk ;TI"autoconf ;TI"Pmkdir build && cd build # its good practice to build outside of source dir ;TI"Mmkdir ~/.rubies # we will install to .rubies/ruby-trunk in our home dir ;TI"8../configure --prefix="${HOME}/.rubies/ruby-trunk" ;TI"make up && make install ;T;0o; ;[I"OAfter adding Ruby to your PATH, you should be ready to run the test suite:;T@ o;;[I"make test ;T;0o; ;[I"JYou can also use +test-all+ to run all of the tests with the RUNRUBY ;TI"Qinterpreter just built. Use TESTS or RUNRUBYOPT to pass parameters, such as:;T@ o;;[I"make test-all TESTS=-v ;T;0o; ;[I"EThis is also how you can run a specific test from our build dir:;T@ o;;[I")make test-all TESTS=drb/test_drb.rb ;T;0o; ;[I";You can run +test+ and +test-all+ at once by +check+ .;T@ o;;[I"make check ;T;0o; ;[I"QFor older versions of Ruby you will need to run the build setup again after ;TI"Mchecking out the associated branch in git, for example if you wanted to ;TI"checkout 1.9.3:;T@ o;;[I"Bgit clone git://github.com/ruby/ruby.git --branch ruby_1_9_3 ;T;0o; ;[I"LOnce you checked out the source code, you can update the local copy by:;T@ o;;[I" make up ;T;0o; ;[I"3Or, update, build, install and check, by just:;T@ o;;[I"make love ;T;0S; ; i; I"Contributing Documentation;T@ o; ;[I"SIf you're interested in contributing documentation directly to CRuby there is ;TI"*a wealth of information available at ;TI":{documenting-ruby.org}[http://documenting-ruby.org/].;T@ o; ;[I"'There is also the {Ruby Reference ;TI"EManual}[https://bugs.ruby-lang.org/projects/rurema] in Japanese.;T@ S; ; i; I"Contributing A Patch;T@ S; ; i; I"Deciding what to patch;T@ o; ;[I"GBefore you submit a patch, there are a few things you should know:;T@ o;;;;[ o;;0;[o; ;[I"XPay attention to the maintenance policy for stable and maintained versions of Ruby.;To;;0;[o; ;[I"GReleased versions in security mode will not merge feature changes.;To;;0;[o; ;[I"RSearch for previous discussions on ruby-core to verify the maintenance policy;To;;0;[o; ;[I"6Patches must be distributed under Ruby's license.;To;;0;[o; ;[I"iThis license may change in the future, you must join the discussion if you don't agree to the change;T@ o; ;[I"XTo improve the chance your patch will be accepted please follow these simple rules:;T@ o;;;;[ o;;0;[o; ;[I"1Bug fixes should be committed on trunk first;To;;0;[o; ;[I"ZFormat of the patch file must be a unified diff (ie: diff -pu, svn diff, or git diff);To;;0;[o; ;[I"%Don't introduce cosmetic changes;To;;0;[o; ;[I"1Follow the original coding style of the code;To;;0;[o; ;[I".Don't mix different changes in one commit;T@ o; ;[I"LFirst thing you should do is check out the code if you haven't already:;T@ o;;[I"9git clone git://github.com/ruby/ruby.git ruby-trunk ;T;0o; ;[I"#Now create a dedicated branch:;T@ o;;[I"cd ruby-trunk ;TI"#git checkout -b my_new_branch ;T;0o; ;[ I"QThe name of your branch doesn't really matter because it will only exist on ;TI"Tyour local computer and won't be part of the official Ruby repository. It will ;TI"Pbe used to create patches based on the differences between your branch and ;TI"trunk, or edge Ruby.;T@ S; ; i; I"Coding style;T@ o; ;[I"RHere are some general rules to follow when writing Ruby and C code for CRuby:;T@ o;;;;[o;;0;[o; ;[I"PIndent 4 spaces for C with tabs for eight-space indentation (emacs default);To;;0;[o; ;[I"!Indent 2 space tabs for Ruby;To;;0;[o; ;[I""Do not use TABs in ruby codes;To;;0;[o; ;[I"4ANSI C style for 1.9+ for function declarations;To;;0;[o; ;[I""Follow C90 (not C99) Standard;To;;0;[o; ;[I"(PascalStyle for class/module names.;To;;0;[o; ;[I"9UNDERSCORE_SEPARATED_UPPER_CASE for other constants.;To;;0;[o; ;[I"Capitalize words.;To;;0;[o; ;[I"$ABBRs should be all upper case.;To;;0;[o; ;[I"Do as others do;T@ S; ; i; I"ChangeLog;T@ o; ;[I"QAlthough not required, if you wish to add a ChangeLog entry for your change ;TI"please note:;T@ o; ;[I"OYou can use the following template for the ChangeLog entry on your commit:;T@ o;;[ I"AThu Jan 1 00:00:00 2004 Your Name ;TI" ;TI"D * filename (function): short description of this commit. ;TI"@ This should include your intention of this change. ;TI"0 [bug:#number] [mailinglist:number] ;TI" ;TI"S * filename2 (function2): additional description for this file/function. ;T;0o; ;[I"3This follows {GNU Coding Standards for Change ;TI"VLogs}[http://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs], ;TI"&some other requirements and tips:;T@ o;;;;[o;;0;[o; ;[I">Timestamps must be in JST (+09:00) in the style as above.;To;;0;[o; ;[I"HTwo spaces between the timestamp and your name. Two spaces between ;TI"%your name and your mail address.;To;;0;[o; ;[I">One blank line between the timestamp and the description.;To;;0;[o; ;[I"IIndent the description with TAB. 2nd line should begin with TAB+2SP.;To;;0;[o; ;[I"'Write a entry (*) for each change.;To;;0;[o; ;[I">Refer to redmine issue or discussion on the mailing list.;To;;0;[o; ;[I":For GitHub issues, use [GH-#] (such as [Fixes GH-234];To;;0;[o; ;[I"$One blank line between entries.;To;;0;[o; ;[I"Do as other committers do.;T@ o; ;[I"MYou can generate the ChangeLog entry by running make change;T@ o; ;[I"UWhen you're ready to commit, copy your ChangeLog entry into the commit message, ;TI"7keeping the same formatting and select your files:;T@ o;;[I"(git commit ChangeLog path/to/files ;T;0o; ;[I"TIn the likely event that your branch becomes outdated, you will have to update ;TI"your working branch:;T@ o;;[I"git fetch origin ;TI"&git rebase remotes/origin/master ;T;0o; ;[ I"ONow that you've got some code you want to contribute, let's get set up to ;TI"Ugenerate a patch. Start by forking the github mirror, check the {github docs on ;TI"Sforking}[https://help.github.com/articles/fork-a-repo] if you get stuck here. ;TI"OYou will only need a github account if you intend to host your repository ;TI"on github.;T@ o; ;[I"RNext copy the writable url for your fork and add it as a git remote, replace ;TI"1"my_username" with your github account name:;T@ o;;[I"@git remote add my_fork git@github.com:my_username/ruby.git ;TI".# Now we can push our branch to our fork ;TI"$git push my_fork my_new_branch ;T;0o; ;[I"UIn order to generate a patch that you can upload to the bug tracker, we can use ;TI";the github interface to review our changes just visit ;TI"Fhttps://github.com/my_username/ruby/compare/trunk...my_new_branch;T@ o; ;[ I"SNext, you can simply add '.patch' to the end of this URL and it will generate ;TI"Pthe patch for you, save the file to your computer and upload it to the bug ;TI"Ttracker. Alternatively you can submit a pull request, but for the best chances ;TI"Eto receive feedback add it is recommended you add it to redmine.;T@ o; ;[ I"TSince git is a distributed system, you are welcome to host your git repository ;TI")on any {publicly accessible hosting ;TI"Vsite}[https://git.wiki.kernel.org/index.php/GitHosting], including {hosting your ;TI"aown}[https://www.kernel.org/pub/software/scm/git/docs/user-manual.html#public-repositories] ;TI"TYou may use the {'git format-patch'}[http://git-scm.com/docs/git-format-patch] ;TI"Mcommand to generate patch files to upload to redmine. You may also use ;TI"Tthe {'git request-pull'}[http://git-scm.com/docs/git-request-pull] command for ;TI"1formatting pull request messages to redmine.;T: @file@:0@omit_headings_from_table_of_contents_below0