Project

General

Profile

Committer How to

(Japanese version: CommitterHowtoJa

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:
    • 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]]

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

What is necessary

  • Development environment for your platform
  • Another ruby - Ruby needs a ruby 1.9+ binary to bootstrap itself. (BASERUBY)
  • git
  • SSH client
  • GnuPG (optional)
  • autoconf (2.60 or later)
  • bison

How to use GPG (optional)

How to generate your PGP keys

How to sign a mail with PGP

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

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):
Enter same passphrase again:
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.

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 add you as a member of ruby-core group. (HowToManage).
  • Join the ruby committers Slack (you will be provided a sign-up link via email)
  • Sign up to Coverity.
    • Ask how to sign up to another committer at an IRC channel.
  • Get your GPG key signed. (optional)
    • Let other committer sign your key.
    • Print your GPG fingerprints on your business card.
  • Add your entry to http://github.com/yugui/rubycommitters and send a pull request.

What to do when you commit

Consensus

  • Never add a new feature or change a spec without discussion on the mailing list nor 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-spec too. (better than just test-all)

Contact to a maintainer

Git

(Caution: still incomplete!)

  • Since April 23, 2019, Ruby uses mainly git for version control

    • master is on git
    • older branches are still on svn
  • Get the data from github, with the following command:
    git clone https://github.com/ruby/ruby
    (to check: are there any convenient options we can recommend?)

  • Important: Never push back to github!
    For committing, push to git@git.ruby-lang.org:ruby.git
    (todo: work out a specific command and/or settings)

  • Configuration for ssh

    • Learn how to use ssh-agent. Don't repeat yourself.
    • Read ssh_config(5).
  • Branching

    • master 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

    • Referencing related tickets is a good idea. Redmine automatically updates the tickets with a reference to the commit. 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. see [Feature #XXXX]
    • Include the original revision hash in case of a backport
    • Write as fix https://github.com/ruby/ruby/pull/XXXX to refer tickets in Github. Do not write as [Github fixes #XXXX], it confuses with redmine's ticket.
    • Write as [skip ci] to skip Travis CI, if the commit only changes documents and you are sure.
    • Fold by 80 columns
    • 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 commit message.
  • mail

    • [[redmine:MailingList]]

RDoc

Writing RDocs is preferred

Reference manual

Redmine

  • You can edit any wiki page. (login required)
  • Feature request or bug report on redmine
  • Send an email to <its-admin AT ruby-lang.org> for administration request.
  • You can incorporate mails in ruby-core and ruby-dev ML by Mail to issue.

Statuses

  • Open: a new ticket
  • Assigned: some people are considered qualified (this doesn't mean they are working on the ticket; you can take over it)
  • Feedback: waiting a reaction of the reporter (or someone who can solve deadlock)
  • Third Party's Issue: the ticket is completed because the issue is not Ruby's; Ruby itself is not changed
  • Rejected: the ticket is completed because the issue is invalid or some reason; Ruby itself is not changed
  • Closed: the ticket is completed; Ruby is fixed and maybe it needs to be backported

Backport field

This is advanced field.
If you want to know the detail, see HowToBackport.

Misc

  • Tools for compilation
    • autoconf (2.60 or later)
    • bison
    • ruby (building ruby from source 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 ruby/spec
    • make test-spec MSPECOPT='-j' for running specs
    • Feel free to add and modify specs under spec/ruby (see spec/README.md).
    • Specs are synchronized ~monthly by eregon
  • diff format
    • unified diff (-u)
    • -p
  • GitHub: https://github.com/ruby/ruby
  • cgit: https://git.ruby-lang.org/ruby.git
  • ML : ruby-dev, ruby-list, ruby-core, ruby-talk
  • commit mail (ruby-cvs)
  • NEWS
    • Add an entry when you add a feature or change a spec.

See also