diff --git a/Committer-How-To.md b/Committer-How-To.md new file mode 100644 index 0000000..d847be8 --- /dev/null +++ b/Committer-How-To.md @@ -0,0 +1,190 @@ +# 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](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 + +1. A committer can suggest to make you as a committer with creating a Misc ticket in Redmine. +2. You need to reply the ticket that you want to be a committer. +3. Get the approval of matz about getting a commit right. This is also need to be a reply to the ticket. + +(It is recommended that the proposer get a rough consensus of committers who are working in the area which you will work in. With the consensus committers will review your commit and help if you wonder something after you become a committer) + +After the approval, Send a mail with the following information to <cvs-admin AT ruby-lang.org>. [[ruby-dev:23675](http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-dev/23675)], [[ruby-dev:24652](http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-dev/24652)] + +required: + +* Account name you want to use for ruby-lang.org. This is for Key of [`config/email.yml`](https://github.com/ruby/git.ruby-lang.org/blob/master/config/email.yml) to be used by [the authorization on pre-receive hook](https://github.com/ruby/git.ruby-lang.org/blob/master/bin/check-email-and-refname.rb) +* Create the pull-request to add your account name and e-mail address for https://github.com/ruby/git.ruby-lang.org/blob/master/config/email.yml + * We will invite this address for our private Slack workspace. If you want to use the different address, please share it. +* Create the pull-request to add your SSH public key to https://github.com/ruby/git.ruby-lang.org/blob/master/recipes/files/var/git/.ssh/authorized_keys + * Please fill the account name of first section like `"SVN_ACCOUNT_NAME=hsbt"`. +* If you don't use GitHub, Please send your public key and email address to `cvs-admin@ruby-lang.org` + +optional: + +* GitHub Account name +* Redmine(bugs.ruby-lang.org) Account name or e-mail address. + * We recommend to sign up to the redmine with your mail address because our canonical discussion place it redmine. +* If you want to use `ruby-lang.org` domain for e-mail address like `foo@ruby-lang.org. Where to forward your mail from your-account@ruby-lang.org +* We provide the free account of 1password for Ruby Core team. Please share your email address for this if you want to use it. +* Subscribe to ruby-core for discussioning feature/bugfix of Ruby. + * And ruby-cvs for reading every commits. + * subscribe to ruby-dev if you read Japanese. + +## What to do after you become a committer + +See [Building Ruby](https://docs.ruby-lang.org/en/master/contributing/building_ruby_md.html). And committer needs to care the following things: + +* 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. + +## What to do when you commit + +### Consensus + +* Never add a new feature or change a spec without discussion on redmine/ruby-core mailing-list nor [[Maintainers|maintainer]]'s permission. +* Especially on interpreter, VM, GC or such core of core, class or method naming 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 + +* Some libraries are maintained on their own repository. On those libs the ones in the ruby's repository are just copy. + * Check https://github.com/ruby/ruby/blob/master/doc/maintainers.md to know maintainers. + * Check https://github.com/ruby/ and send a pull request to it if it exists. + +### Git + +* Since April 23, 2019, we mainly use Git for Ruby's version control + * `master` and `ruby_2_7` (and future stable branches) are only managed by Git. + * `ruby_2_6` and older branches are managed by SVN, but they're synced to Git. +* Branching + * `master` is for development. + * `ruby_*_*` branches are for stable versions. Branch maintainers backport `master` commits to them. +* Git repositories + * Mirror (fetch *and merge pull requests*): https://github.com/ruby/ruby.git + * To avoid overloading the master server, it's strongly recommended to use this for `git fetch` or `git clone`. + * **You may not directly push commits to `master` branch on GitHub, but you can merge pull requests** and they'll be automatically synced to the master repository. + * You need to be in ruby organization's ruby-committers team on GitHub to have access to merge pull requests. Ask @hsbt to get invited. + * Even if you have access to, you may not create a topic branch on GitHub ruby/ruby . Use your own fork to create a pull request. + * Both "Squash and merge" and "Rebase and merge" are allowed. Feel free to use what you prefer. + * Master (for committer's push): https://git.ruby-lang.org/ruby.git + * You need to have your git commit's email address on [git.ruby-lang.org/config/email.yml](https://github.com/ruby/git.ruby-lang.org/blob/master/config/email.yml) to push commits to this repository. +* Setup: + For committing, push to git@git.ruby-lang.org:ruby.git + + ``` + $ git clone --depth=1000 https://github.com/ruby/ruby # use a favorite depth + Cloning into 'ruby'... + ... + $ cd ruby + $ git config --add remote.origin.fetch '+refs/notes/commits:refs/notes/commits' + $ git fetch + .. + From https://github.com/ruby/ruby + * [new ref] refs/notes/commits -> refs/notes/commits + ``` + +* Configuration for ssh + * Learn how to use ssh-agent. Don't repeat yourself. + * Read ssh_config(5). +* 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. + +## Continuous Integration (CI) + +After you commit, check that CI stays green. [List of CI servers used for Ruby](https://bugs.ruby-lang.org/projects/ruby/wiki/CIServers) + +* https://github.com/ruby/ruby/actions +* https://rubyci.org/ +* http://ci.rvm.jp/ + +## Documentation + +### RDoc + +Writing RDocs is preferred: see [Documentation Guide](https://docs.ruby-lang.org/en/master/contributing/documentation_guide_md.html) + +### Reference manual + +* [Object oriented scripting language Ruby - Reference manual](https://docs.ruby-lang.org/) + +## Redmine + +* You can edit any wiki page. (login required) +* Feature request or bug report on [redmine](http://redmine.ruby-lang.org/projects/show/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](https://github.com/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 + +* [[DeveloperHowTo]] +* [[Maintainers]]