Ruby

=begin

= Committer How to

== How to become a committer

* Send good patches to ruby-core list. Send patches, send patches and send patches. Someday the core team will say "OK, commit it by yourself" and you will be granted commit right.

* Port Ruby to a non-POSIX platform. The core team will grant you to the permission so that you can maintain Ruby for that platform.

* Write a great library. If the core team wanted to add the library to Ruby's standard library, you will be granted the right so that you can maintain it.

  * This way is very hard because RubyGems made it easy for users to installing a new library.

* Citing from ((<Linus Torvalds - Part II : Open Voices: The Linux Foundation Podcast|URL:http://linux-foundation.org/weblogs/openvoices/linus-torvalds-part-ii/>)):

  * ((|Jim Zemlin|)): Any final advice for an organization or an individual that wants to get involved in working on the Linux front?

  * ((|Linus Torvalds|)): I get the question of “Where should I start?” fairly often and my advice is just don’t even ask that question. It’s more like if you’re not interested enough in one particular area that you already know what you want to try to do, don’t do it. Just let it go and then when you hit something where you say, “I could do this better” and you actually feel motivated enough that you go from saying that to doing that, you will have answered that question yourself.

== What to do for registering you as a committer

Get the approval of matz about getting a commit right.

After the approval, Send a mail with the following information to <cvs-admin AT ruby-lang.org>. [[ruby-dev:23675]], [[ruby-dev:24652]]

* Your PGP public key.

* Account name you want to use. This is for

  * Subversion

  * ((|your-account|))@ruby-lang.org

* Your SSH2 public key.

* Where to forward your mail from ((|your-account|))@ruby-lang.org

You must sign that mail with PGP. [[ruby-dev:25599]]

== What is necessary

* Development environment for your platform

* Another ruby - 1.9 series of ruby needs a ruby binary to bootstrap itself. (BASERUBY)

  * BASERUBY can be Ruby 1.8

* subversion

* SSH client

* GnuPG

* MUA

* IRC client

* autoconf (2.60 or later)

* bison

* (gperf)

* (git)

=== How to use GPG

How to generate your PGP keys

* ((<URL:http://www.gnupg.org/>))

How to sign a mail with PGP

* ((<EnigMail|URL:https://addons.mozilla.org/en-US/thunderbird/addon/71>)) for Thunderbird

* ((<GPGMail|URL:http://www.sente.ch/software/GPGMail/English.lproj/GPGMail.html>)) for Apple Mail.app

=== How to generate your SSH keys

You might already have your keys when you have OpenSSH. See (((%~/.ssh/id_rsa%)) or ((%~/.ssh/id_dsa%)). You can use them if you have.

Otherwise generate one with ssh-keygen(1).

 $ ssh-keygen -b 2048 -f ruby_key

 Generating public/private rsa key pair.

 Enter passphrase (empty for no passphrase): <TYPE SOMETHING>

 Enter same passphrase again: <TYPE SOMETHING>

 Your identification has been saved in ruby_key.

 Your public key has been saved in ruby_key.pub.

 The key fingerprint is:

 XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX your@hostname

Then you will have your private key ((%ruby_key%)) and public key ((%ruby_key.pub%)). Keep your private key secret. Pass the public key to the cvs-admin.

=== IRC

IRC clients

* ((<LimeChat|URL:http://limechat.net/>)) - for win, mac

* XChat (X), XChat-gnome (Gnome)

* riece (Emacs)

IRC proxy bot

* ((<Nadoka|URL:http://www.atdot.net/nadoka/nadoka.en.html>))

* ((<Tiarra|URL:http://www.clovery.jp/tiarra/>))

== What to do after you become a committer

* Always build Ruby outside of (({$(srcdir)}))

  * e.g. Suppose that there are source codes in ((%/path/to/somewhere/src%)) and building at ((%/path/to/somewhere/obj%)). Then, at ((%obj%)), do ((%../src/configure%))

* Always build Ruby inside of (({$(srcdir)})) too, using ((%./configure%)).

* Subscribe to ruby-core and ruby-cvs.

  * subscribe to ruby-dev if you read Japanese.

* Sign up to the redmine.

  * Sign up with your mail address that you use for sending to ruby-core.

  * Tell the mail address to another committer and ask him/her to register you as a developer for [[project:Ruby]].

* Keep contact to #ruby-core@freenode.

  * #ruby-ja@ircnet or #ruby-ja@freenode too if you read Japanese.

* Sign up to ((<Coverity|URL:http://scan.coverity.com/>)).

  * Ask how to sign up to another committer at an IRC channel.

* Get your GPG key signed.

  * Let other committer sign your key.

  * Print your GPG fingerprints on your business card.

* If you have github account, add your-svn-account@b2dd03c8-39d4-4d8f-98ff-823fe69b080e to your email addresses. Then you will see your icon in https://github.com/ruby/ruby/commits/trunk and so on.

* Send  a patch for ((<ruby-committers.yml|URL:http://coderepos.org/share/browser/lang/ruby/ruby-committers/ruby-committers.yml>)) to <yugui AT yugui.jp>. Or you can update the YAML by yourself if you have a ((<CodeRepos|URL:http://coderepos.org/share/>)) account.

== What to do when you commit

=== Consensus

* Never add a new feature or change a spec without discussion on the mailing list nor [[Maintainers|maintainer]]'s permission.

* Especially on interpreter, VM, GC or such core of core, get matz's approval.

* Feel free to commit trivial changes, e.g. typo fix.

* Gradually learn what needs discussion and what you can commit without discussion. You will do a mistake and the maintainer will complain against it, but don't worry too much.

* Never commit without compiling ruby.  Compiling miniruby is not sufficient.

  (1) Do ((%make test%)) too. (better than just building)

  (2) Do ((%make test-all%)) too. (better than just test)

  (3) Do ((%make test-rubyspec%)) too. (better than just test-all)

=== Contact to a maintainer

* Some libraries are maintained on their own repository. On those libs the ones in the ruby's repository are just copy.

  * Send a mail to the maintainer after commit.

  * Send a patch to ruby-core and the maintainer instead of committing it directly if possible.

* minitest

* rdoc

* rubygems

* rake

* soap (1.8)

* wsdl (1.8)

=== Subversion

* Configuration for subversion

  * [[ruby-dev:30043]] (English)

* Configuration for ssh

  * Learn how to use ssh-agent.  Don't repeat yourself.

  * Read ssh_config(5).

* Branching

  * /trunk is for development.

  * Each branch for stable versions. (e.g. ruby_1_8, ruby_1_8_7)

* Never commit two or more changesets as one commit.

* Commit log

  * Write exactly what you have written in ((%ChangeLog%)), with the addition of the original revision number in case of a backport.

    (Without header, no tabs)

     Example is like following:

     * filename.c (rb_xxx_yyy): short description of this commit.

       Fixes [bug:#XXXX] [ruby-core:XXXX].

       (rb_zzz_aaa): yet another part.

     * filename.h (MACRO_NAME): value changed.

  * Fold by 80 columns (copy from ((%ChangeLog%)) without tabs)

  * You can command the Redmine in a commit message.

    * [[redmine:VersionControlSystem]]

  * `make change` will write change.log which you can fill in and copy to ChangeLog.

* svn mail

  * [[redmine:MailingList]]

=== ChangeLog

((<GNU Coding Standards : Change Logs|URL:http://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs>))

 Thu Jan  1 00:00:00 2004  Your Name  <yourmail@example.com>

 	* 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.

* Timestamps must be in JST (+09:00), in the style as above.

* Two whitespaces between the timestamp and your name. Two whitespaces 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.

* One blank line between entries.

* Do as other committers do.

* What to write and what need not: [[ruby-talk:120515]]

  * No need for an entry on fixing typo.

  * Referring a contributor/reporter.

    * Respect contributors [[ruby-dev:24936]]

  * Write one when you are not sure if you should write or not.

==== Template

 Thu Jan  1 03:03:03 2004  Your Name  <yourmail@example.com>

 	* filename.c (rb_xxx_yyy): short description of this commit.

 	  Fixes [ruby-dev:XXXX].

 	  (rb_zzz_aaa): yet another part.

 	* filename.h (MACRO_NAME): value changed.

 Thu Jan  1 02:02:02 2004  Your Name  <yourmail@example.com>

 	* filename.rb (XXXX#yyyy): short description of this commit.

 	  Patch by Foo Bar <foo-bar AT example.org>.

 Thu Jan  1 01:01:01 2004  Your Name  <yourmail@example.com>

 	* filename.c (rb_aaa_bbb): short description of this commit.

 	  See [ruby-core:XXX].

 	  Reported by Baz Qux <baz-qux AT example.org>.

=== RDoc

Writing RDocs is preferred 

* ((<RDoc template|URL:http://arton.no-ip.info/collabo/backyard/?RDoc%A4%CE%A5%C6%A5%F3%A5%D7%A5%EC%A1%BC%A5%C8>)) (Japanese) by arton

* ((<RDoc Documentation|URL:http://www.ruby-doc.org/stdlib/libdoc/rdoc/rdoc/files/rdoc/README.html>))

=== Reference manual

* ((<Object oriented scripting language Ruby - Reference manual|URL:http://www.ruby-lang.org/ja/man/>)) (Japanese, frozen)

* ((<Ruby reference manual renewal project|URL:http://doc.loveruby.net/refm/api/view/index>)) (Japanese, under development)

=== svn:ignore

== How to backport

* checkout the branch

* use tool/merger.rb.

== How to announce

How to announce from ruby-lang.org.

=== Subversion

svn.ruby-lang.org is automatically synchronized with ci.ruby-lang.org.

Send an email to cvs-admin AT ruby-lang.org for administration request.

=== FTP

Upload to carbon.ruby-lang.org:/home/ftp/pub/ with SCP.

=== WWW

* Ask the www team on ((<redmine|URL:http://redmine.ruby-lang.org/projects/show/www>)).

* Send an email to <webmaster AT ruby-lang.org> for administration request.

=== Redmine

* You can edit any wiki page. (login required)

* Feature request or bug report on ((<redmine|URL:http://redmine.ruby-lang.org/projects/show/redmine>))

* Send an email to <its-admin AT ruby-lang.org> for administration request.

=== Servers

* lithium, carbon, boron

* Status

  * ci.ruby-lang.org:

    * svn (for development. members only)

  * svn.ruby-lang.org:

    * Anonymous svn: svn.ruby-lang.org

    * issue tracking system: redmine.ruby-lang.org

  * carbon.ruby-lang.org:

    * WWW: www.ruby-lang.org, raa.ruby-lang.org

    * FTP: ftp.ruby-lang.org

    * Anonymous CVS: cvs.ruby-lang.org

    * mailing lists

  * boron.rubyist.net: 

    * WWW: www.rubyist.net

* ((<list of elements|URL:http://en.wikipedia.org/wiki/List_of_elements_by_atomic_number>))

== Misc

* Tools for compilation

  * autoconf (2.60 or later)

  * bison

  * (gperf)

  * (ruby) (building the 1.9 needs ruby)

* Test cases

  * Adding test cases (bootstraptest / test)

  * Testing test cases

    * make test

    * make test-all

    * "make check" executes both test and test-all.

* Integration with ((<RubySpec|URL:http://www.rubyspec.org>))

  * make update-rubyspec for retrieving specs.

    * git required

  * make test-rubyspec for checking

* diff format

  * unified diff (-u)

  * -p

* ((<ViewVC|URL:http://svn.ruby-lang.org/cgi-bin/viewvc.cgi/?root=ruby>))

* ML : ruby-dev, ruby-list, ruby-core, ruby-talk

* commit mail (ruby-cvs)

* IRC channel

  * IRCnet: #ruby:*.jp  (Japanese)

  * freenode: #ruby-core (English)

* ((<CIA Open Source Notification System|URL:http://cia.navi.cx/stats/project/ruby>))

* .document

* NEWS

  * Add an entry when you add a feature or change a spec.

== See also

* [[DeveloperHowTo]]

* [[Maintainers]]

=end