ruby-changes:28568
From: zzak <ko1@a...>
Date: Thu, 9 May 2013 11:15:37 +0900 (JST)
Subject: [ruby-changes:28568] zzak:r40620 (trunk): * doc/contributing.rdoc: Add guide for contributing to CRuby
zzak 2013-05-09 11:15:24 +0900 (Thu, 09 May 2013) New Revision: 40620 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=40620 Log: * doc/contributing.rdoc: Add guide for contributing to CRuby Added files: trunk/doc/contributing.rdoc Modified files: trunk/ChangeLog Index: doc/contributing.rdoc =================================================================== --- doc/contributing.rdoc (revision 0) +++ doc/contributing.rdoc (revision 40620) @@ -0,0 +1,345 @@ https://github.com/ruby/ruby/blob/trunk/doc/contributing.rdoc#L1 += 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 {bugs.ruby-lang.org}[http://bugs.ruby-lang.org/]. 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}[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 + {Downloading Ruby}[http://www.ruby-lang.org/en/downloads/]. +* 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. + +== 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@r... list and the problem will be published after +fixes have been released. You can also encrypt the issue using {the PGP public +key}[http://www.ruby-lang.org/security.asc] 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}[https://bugs.ruby-lang.org/projects/ruby-trunk/issues] 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 +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 + +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' +tracker}[https://bugs.ruby-lang.org/projects/ruby-trunk/issues?set_filter=1&tracker_id=2] +on ruby-trunk. For non-CRuby dependent features, features that would apply to +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. + +A good template for feature proposal should look something like this: + +[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 + +== 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 +{wiki}[https://bugs.ruby-lang.org/projects/ruby/wiki/ReleaseEngineering]. + +== 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 +{svnbook.red-bean.com}[http://svnbook.red-bean.com/]. For other resources see +the {ruby-core documentation on +ruby-lang.org}[http://www.ruby-lang.org/en/community/ruby-core/]. + +This guide will use git for contributing. The {git +homepage}[http://git-scm.com/] has installation instructions with links to +documentation for learning more about git. There is a mirror of the subversion +repository on {github}[https://github.com/ruby/ruby]. + +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 +* NDBM/QDBM +* GDBM +* 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://github.com/ruby/ruby.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://github.com/ruby/ruby.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 +{documenting-ruby.org}[http://documenting-ruby.org/]. + +There is also the {Ruby Reference +Manual}[https://bugs.ruby-lang.org/projects/rurema] in Japanese. + +== Contributing A Patch + +First thing you should do is check out the code if you haven't already: + + git clone git://github.com/ruby/ruby.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. +* UNDERSCORE_SEPARATED_UPPER_CASE for other constants. +* 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 <yourmail@e...> + + * 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 +Logs}[http://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs], +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}[https://help.github.com/articles/fork-a-repo] 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 git@g...: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 +https://github.com/my_username/ruby/compare/trunk...my_new_branch + +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. + + + + Index: ChangeLog =================================================================== --- ChangeLog (revision 40619) +++ ChangeLog (revision 40620) @@ -1,3 +1,7 @@ https://github.com/ruby/ruby/blob/trunk/ChangeLog#L1 +Thu May 9 11:14:18 2013 Zachary Scott <zachary@z...> + + * doc/contributing.rdoc: Add guide for contributing to CRuby + Thu May 9 04:55:49 2013 Tanaka Akira <akr@f...> * configure.in: Check socket library again. shutdown() is used in -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/