mirror of
https://github.com/ruby/ruby.git
synced 2022-11-09 12:17:21 -05:00
Improve documentation on contributing to Ruby
co-authored-by: Peter Zhu <peter@peterzhu.ca> co-authored-by: Stan Lo <stan001212@gmail.com>
This commit is contained in:
Jemma Issroff
Peter Zhu
parent
becafe1efb
commit
c00feffb46
Notes:
git
2022-05-11 23:59:45 +09:00
13 changed files with 442 additions and 820 deletions
|
|
@ -41,7 +41,6 @@ README.ja.md
|
|||
|
||||
COPYING
|
||||
COPYING.ja
|
||||
CONTRIBUTING.md
|
||||
|
||||
LEGAL
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1 @@
|
|||
Please see the [official issue tracker], [doc/contributing.rdoc] and wiki [HowToContribute].
|
||||
|
||||
[official issue tracker]: https://bugs.ruby-lang.org
|
||||
[doc/contributing.rdoc]: contributing.rdoc
|
||||
[HowToContribute]: https://bugs.ruby-lang.org/projects/ruby/wiki/HowToContribute
|
||||
See ["Contributing to Ruby"](https://docs.ruby-lang.org/en/master/contributing_md.html), which includes setup and build instructions.
|
||||
|
|
|
|||
93
README.md
93
README.md
|
|
@ -74,107 +74,20 @@ in the mail body (not subject) to the address [ruby-talk-request@ruby-lang.org].
|
|||
|
||||
[ruby-talk-request@ruby-lang.org]: mailto:ruby-talk-request@ruby-lang.org?subject=Join%20Ruby%20Mailing%20List&body=subscribe
|
||||
|
||||
## Requirements to build from repository
|
||||
|
||||
1. GNU or BSD make
|
||||
2. C99 compiler
|
||||
3. autoconf 2.67 or higher
|
||||
4. automake 1.15 or higher
|
||||
5. bison 2.3 or higher
|
||||
6. Ruby 2.2 or higher
|
||||
|
||||
When building from a released version, only a C99 compiler and GNU or BSD make
|
||||
is required.
|
||||
|
||||
## How to compile and install
|
||||
|
||||
1. If you want to use Microsoft Visual C++ to compile Ruby, read
|
||||
[win32/README.win32](rdoc-ref:win32/README.win32) instead of this document.
|
||||
|
||||
2. Run `./autogen.sh` to generate configure, when you build the source checked
|
||||
out from the Git repository.
|
||||
|
||||
3. Run `./configure`, which will generate `config.h` and `Makefile`.
|
||||
|
||||
Some C compiler flags may be added by default depending on your
|
||||
environment. Specify `optflags=..` and `warnflags=..` as necessary to
|
||||
override them.
|
||||
|
||||
4. Edit `include/ruby/defines.h` if you need. Usually this step will not be needed.
|
||||
|
||||
5. Optional: Remove comment mark(`#`) before the module names from `ext/Setup`.
|
||||
|
||||
This step is only necessary if you want to link modules statically.
|
||||
|
||||
If you don't want to compile dynamic extensions (probably on architectures
|
||||
which do not allow dynamic loading), remove comment mark from the line
|
||||
"`#option nodynamic`" in `ext/Setup`.
|
||||
|
||||
Usually this step will not be needed.
|
||||
|
||||
6. Run `make`.
|
||||
|
||||
* On Mac, set RUBY\_CODESIGN environment variable with a signing identity.
|
||||
It uses the identity to sign `ruby` binary. See also codesign(1).
|
||||
|
||||
7. Optionally, run '`make check`' to check whether the compiled Ruby
|
||||
interpreter works well. If you see the message "`check succeeded`", your
|
||||
Ruby works as it should (hopefully).
|
||||
|
||||
8. Run '`make install`'.
|
||||
|
||||
This command will create the following directories and install files into
|
||||
them.
|
||||
|
||||
* `${DESTDIR}${prefix}/bin`
|
||||
* `${DESTDIR}${prefix}/include/ruby-${MAJOR}.${MINOR}.${TEENY}`
|
||||
* `${DESTDIR}${prefix}/include/ruby-${MAJOR}.${MINOR}.${TEENY}/${PLATFORM}`
|
||||
* `${DESTDIR}${prefix}/lib`
|
||||
* `${DESTDIR}${prefix}/lib/ruby`
|
||||
* `${DESTDIR}${prefix}/lib/ruby/${MAJOR}.${MINOR}.${TEENY}`
|
||||
* `${DESTDIR}${prefix}/lib/ruby/${MAJOR}.${MINOR}.${TEENY}/${PLATFORM}`
|
||||
* `${DESTDIR}${prefix}/lib/ruby/site_ruby`
|
||||
* `${DESTDIR}${prefix}/lib/ruby/site_ruby/${MAJOR}.${MINOR}.${TEENY}`
|
||||
* `${DESTDIR}${prefix}/lib/ruby/site_ruby/${MAJOR}.${MINOR}.${TEENY}/${PLATFORM}`
|
||||
* `${DESTDIR}${prefix}/lib/ruby/vendor_ruby`
|
||||
* `${DESTDIR}${prefix}/lib/ruby/vendor_ruby/${MAJOR}.${MINOR}.${TEENY}`
|
||||
* `${DESTDIR}${prefix}/lib/ruby/vendor_ruby/${MAJOR}.${MINOR}.${TEENY}/${PLATFORM}`
|
||||
* `${DESTDIR}${prefix}/lib/ruby/gems/${MAJOR}.${MINOR}.${TEENY}`
|
||||
* `${DESTDIR}${prefix}/share/man/man1`
|
||||
* `${DESTDIR}${prefix}/share/ri/${MAJOR}.${MINOR}.${TEENY}/system`
|
||||
|
||||
If Ruby's API version is '*x.y.z*', the `${MAJOR}` is '*x*', the
|
||||
`${MINOR}` is '*y*', and the `${TEENY}` is '*z*'.
|
||||
|
||||
**NOTE**: teeny of the API version may be different from one of Ruby's
|
||||
program version
|
||||
|
||||
You may have to be a super user to install Ruby.
|
||||
|
||||
If you fail to compile Ruby, please send the detailed error report with the
|
||||
error log and machine/OS type, to help others.
|
||||
|
||||
Some extension libraries may not get compiled because of lack of necessary
|
||||
external libraries and/or headers. You will need to run '`make distclean-ext`'
|
||||
to remove old configuration after installing them in such a case.
|
||||
|
||||
## Copying
|
||||
|
||||
See the file [COPYING](rdoc-ref:COPYING).
|
||||
|
||||
## Feedback
|
||||
|
||||
Questions about the Ruby language can be asked on the [Ruby-Talk] mailing list
|
||||
Questions about the Ruby language can be asked on the [Ruby-Talk](https://www.ruby-lang.org/en/community/mailing-lists) mailing list
|
||||
or on websites like https://stackoverflow.com.
|
||||
|
||||
Bugs should be reported at https://bugs.ruby-lang.org. Read [HowToReport] for more information.
|
||||
|
||||
[Ruby-Talk]: https://www.ruby-lang.org/en/community/mailing-lists
|
||||
[HowToReport]: https://bugs.ruby-lang.org/projects/ruby/wiki/HowToReport
|
||||
Bugs should be reported at https://bugs.ruby-lang.org. Read ["Reporting Issues"](https://docs.ruby-lang.org/en/master/reporting_issues_md.html) for more information.
|
||||
|
||||
## Contributing
|
||||
|
||||
See the file [CONTRIBUTING.md](rdoc-ref:CONTRIBUTING)
|
||||
See ["Contributing to Ruby"](https://docs.ruby-lang.org/en/master/contributing_md.html), which includes setup and build instructions.
|
||||
|
||||
## The Author
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
*.md
|
||||
*.rb
|
||||
*.rdoc
|
||||
contributing
|
||||
NEWS
|
||||
syntax
|
||||
optparse
|
||||
|
|
|
|||
10
doc/contributing.md
Normal file
10
doc/contributing.md
Normal file
|
|
@ -0,0 +1,10 @@
|
|||
# Contributing to Ruby
|
||||
|
||||
This guide outlines ways to get started with contributing to Ruby:
|
||||
|
||||
* [Reporting issues](contributing/reporting_issues.md): How to report issues, how to request features, and how backporting works
|
||||
* [Building Ruby](contributing/building_ruby.md): How to build Ruby on your local machine for development
|
||||
* [Testing Ruby](contributing/testing_ruby.md): How to test Ruby on your local machine once you've built it
|
||||
* [Making changes to Ruby](contributing/making_changes_to_ruby.md): How to submit pull requests
|
||||
to change Ruby's documentation, code, test suite, or standard libraries
|
||||
* [Making changes to Ruby documentation](contributing/documentation_guide.md): How to make changes to Ruby documentation
|
||||
|
|
@ -1,402 +0,0 @@
|
|||
= 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}[https://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}[https://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-master/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-master/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 to downstream distributions
|
||||
|
||||
You can report downstream issues for the following distributions via their bug tracker:
|
||||
|
||||
* {debian}[https://bugs.debian.org/cgi-bin/pkgreport.cgi?src=ruby-defaults]
|
||||
* {freebsd}[http://www.freebsd.org/cgi/query-pr-summary.cgi?text=ruby]
|
||||
* {redhat}[https://bugzilla.redhat.com/buglist.cgi?bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=MODIFIED]
|
||||
* {macports}[https://trac.macports.org/query?status=assigned&status=new&status=reopened&port=~ruby]
|
||||
* etc (add your distribution bug tracker here)
|
||||
|
||||
== 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@ruby-lang.org list and the problem will be published after
|
||||
fixes have been released. You can also encrypt the issue using {the PGP public
|
||||
key}[https://www.ruby-lang.org/security.asc] for the list.
|
||||
|
||||
== Reporting Other Issues
|
||||
|
||||
If you're having an issue with the website, or maybe the mailing list, you can
|
||||
contact the webmaster to help resolve the problem.
|
||||
|
||||
The current webmaster is:
|
||||
|
||||
* Hiroshi SHIBATA (hsbt)
|
||||
|
||||
You can also report issues with the ruby-lang.org website on the issue tracker:
|
||||
|
||||
* {issue tracker}[https://github.com/ruby/www.ruby-lang.org/issues]
|
||||
|
||||
== 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 will find a lot 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-master/issues] you will 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
|
||||
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 will 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-master/issues?set_filter=1&tracker_id=2]
|
||||
on ruby-master. 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 a 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 master branch. If it's 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].
|
||||
|
||||
=== Branches
|
||||
|
||||
Status and maintainers of branches are listed 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 git for source control, the {git homepage}[https://git-scm.com/]
|
||||
has installation instructions with links to documentation for learning more
|
||||
about git. There is a mirror of the repository on {github}[https://github.com/ruby/ruby].
|
||||
For other resources see the {ruby-core documentation on
|
||||
ruby-lang.org}[https://www.ruby-lang.org/en/community/ruby-core/].
|
||||
|
||||
Install the prerequisite dependencies for building the CRuby interpreter to
|
||||
run tests.
|
||||
|
||||
* C compiler
|
||||
* autoconf - 2.67 or later, preferably 2.69.
|
||||
* bison - 2.0 or later, preferably 3.4.
|
||||
* gperf - 3.0.3 or later, preferably 3.1.
|
||||
* ruby - Ruby itself is prerequisite in order to build Ruby from source.
|
||||
You should use [a maintained version of Ruby](https://www.ruby-lang.org/en/downloads/).
|
||||
|
||||
You should also have access to development headers for the following
|
||||
libraries, but these are not required:
|
||||
|
||||
* NDBM/QDBM
|
||||
* GDBM
|
||||
* OpenSSL/LibreSSL
|
||||
* readline/editline(libedit)
|
||||
* zlib
|
||||
* libffi
|
||||
* libyaml
|
||||
* libexecinfo (FreeBSD)
|
||||
|
||||
Now let's build CRuby:
|
||||
|
||||
* Checkout the CRuby source code:
|
||||
|
||||
git clone https://github.com/ruby/ruby.git ruby-master
|
||||
|
||||
* Generate the configuration files and build:
|
||||
|
||||
cd ruby-master
|
||||
./autogen.sh
|
||||
mkdir build && cd build # its good practice to build outside of source dir
|
||||
mkdir ~/.rubies # we will install to .rubies/ruby-master in our home dir
|
||||
../configure --prefix="${HOME}/.rubies/ruby-master"
|
||||
make up && 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
|
||||
|
||||
You can run +test+ and +test-all+ at once by +check+ .
|
||||
|
||||
make check
|
||||
|
||||
For older versions of Ruby you will 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 https://github.com/ruby/ruby.git --branch ruby_1_9_3
|
||||
|
||||
Once you checked out the source code, you can update the local copy by:
|
||||
|
||||
make up
|
||||
|
||||
Or, update, build, install and check, by just:
|
||||
|
||||
make love
|
||||
|
||||
== Contributing Documentation
|
||||
|
||||
If you're interested in contributing documentation directly to CRuby there is
|
||||
some information available at
|
||||
{Contributing}[https://github.com/ruby/ruby#contributing].
|
||||
|
||||
There is also the {Ruby Reference
|
||||
Manual}[https://github.com/rurema/doctree/wiki] in Japanese.
|
||||
|
||||
== Contributing A Patch
|
||||
|
||||
=== Deciding what to patch
|
||||
|
||||
Before you submit a patch, there are a few things you should know:
|
||||
|
||||
* Pay attention to the maintenance policy for stable and maintained versions of Ruby.
|
||||
* Released versions in security mode will not merge feature changes.
|
||||
* Search for previous discussions on ruby-core to verify the maintenance policy
|
||||
* Patches must be distributed under Ruby's license.
|
||||
* This license may change in the future, you must join the discussion if you don't agree to the change
|
||||
|
||||
To improve the chance your patch will be accepted please follow these simple rules:
|
||||
|
||||
* Bug fixes should be committed on master first
|
||||
* Format of the patch file must be a unified diff (ie: diff -pu, svn diff, or git diff)
|
||||
* Don't introduce cosmetic changes
|
||||
* Follow the original coding style of the code
|
||||
* Don't mix different changes in one commit
|
||||
|
||||
First thing you should do is check out the code if you haven't already:
|
||||
|
||||
git clone https://github.com/ruby/ruby.git ruby-master
|
||||
|
||||
Now create a dedicated branch:
|
||||
|
||||
cd ruby-master
|
||||
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
|
||||
master, or edge Ruby.
|
||||
|
||||
=== Coding style
|
||||
|
||||
Here are some general rules to follow when writing Ruby and C code for CRuby:
|
||||
|
||||
* Indent 4 spaces for C without tabs (old codes might use tabs for eight-space indentation,
|
||||
but newer codes recommend to use spaces only)
|
||||
* 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
|
||||
|
||||
=== Commit messages
|
||||
|
||||
When you're ready to commit:
|
||||
|
||||
git commit path/to/files
|
||||
|
||||
This will open your editor in which you write your commit message.
|
||||
Use the following style for commit messages:
|
||||
|
||||
* Use a succinct subject line.
|
||||
* Include reasoning behind the change in the commit message, focusing on why
|
||||
the change is being made.
|
||||
* Refer to redmine issue (such as Fixes [Bug #1234] or Implements
|
||||
[Feature #3456]), or discussion on the mailing list
|
||||
(such as [ruby-core:12345]).
|
||||
* For GitHub issues, use [GH-#] (such as [Fixes GH-234]).
|
||||
* Follow the style used by other committers.
|
||||
|
||||
=== Contributing your code
|
||||
|
||||
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.
|
||||
You will only need a github account if you intend to host your repository
|
||||
on github.
|
||||
|
||||
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@github.com: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/master...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.
|
||||
|
||||
Since git is a distributed system, you are welcome to host your git repository
|
||||
on any {publicly accessible hosting
|
||||
site}[https://git.wiki.kernel.org/index.php/GitHosting], including {hosting your
|
||||
own}[https://www.kernel.org/pub/software/scm/git/docs/user-manual.html#public-repositories]
|
||||
You may use the {'git format-patch'}[https://git-scm.com/docs/git-format-patch]
|
||||
command to generate patch files to upload to redmine. You may also use
|
||||
the {'git request-pull'}[https://git-scm.com/docs/git-request-pull] command for
|
||||
formatting pull request messages to redmine.
|
||||
|
||||
=== Updating the official repository
|
||||
|
||||
If you are a committer, you can push changes directly into the official
|
||||
repository:
|
||||
|
||||
git push origin your-branch-name:master
|
||||
|
||||
However, it is likely will have become outdated, and you will have to
|
||||
update it. In that case, run:
|
||||
|
||||
git fetch origin
|
||||
git rebase remotes/origin/master
|
||||
|
||||
and then try pushing your changes again.
|
||||
74
doc/contributing/building_ruby.md
Normal file
74
doc/contributing/building_ruby.md
Normal file
|
|
@ -0,0 +1,74 @@
|
|||
# Building Ruby
|
||||
|
||||
## Quick start guide
|
||||
|
||||
1. Install the prerequisite dependencies for building the CRuby interpreter:
|
||||
|
||||
* C compiler
|
||||
* autoconf - 2.67 or later
|
||||
* bison - 2.0 or later
|
||||
* gperf - 3.0.3 or later
|
||||
* ruby - 2.7 or later
|
||||
|
||||
2. Install optional, recommended dependencies:
|
||||
|
||||
* OpenSSL/LibreSSL
|
||||
* readline/editline (libedit)
|
||||
* zlib
|
||||
* libffi
|
||||
* libyaml
|
||||
* libexecinfo (FreeBSD)
|
||||
|
||||
3. Checkout the CRuby source code:
|
||||
|
||||
```
|
||||
git clone https://github.com/ruby/ruby.git
|
||||
```
|
||||
|
||||
4. Generate the configuration files and build:
|
||||
|
||||
```
|
||||
./autogen.sh
|
||||
mkdir build && cd build # its good practice to build outside of source dir
|
||||
mkdir ~/.rubies # we will install to .rubies/ruby-master in our home dir
|
||||
../configure --prefix="${HOME}/.rubies/ruby-master"
|
||||
make install
|
||||
```
|
||||
|
||||
5. [Run tests](testing_ruby.md) to confirm your build succeeded
|
||||
|
||||
## More details
|
||||
|
||||
If you're interested in continuing development on Ruby, here are more details
|
||||
about Ruby's build to help out.
|
||||
|
||||
### Running make scripts in parallel
|
||||
|
||||
To run make scripts in parallel, pass flag `-j<number of processes>`. For instance,
|
||||
to run tests on 8 processes, use:
|
||||
|
||||
```
|
||||
make test-all -j8
|
||||
```
|
||||
|
||||
### Miniruby vs Ruby
|
||||
|
||||
Miniruby is a version of Ruby which has no external dependencies and lacks certain features.
|
||||
It can be useful in Ruby development because it allows for faster build times. Miniruby is
|
||||
built before Ruby. A functional Miniruby is required to build Ruby. To build Miniruby:
|
||||
|
||||
```
|
||||
make miniruby
|
||||
```
|
||||
|
||||
## Debugging
|
||||
|
||||
You can use either lldb or gdb for debugging. Before debugging, you need to create a `test.rb`
|
||||
with the Ruby script you'd like to run. You can use the following make targets:
|
||||
|
||||
* `make run`: Runs `test.rb` using Miniruby
|
||||
* `make lldb`: Runs `test.rb` using Miniruby in lldb
|
||||
* `make gdb`: Runs `test.rb` using Miniruby in gdb
|
||||
* `make runruby`: Runs `test.rb` using Ruby
|
||||
* `make lldb-runruby`: Runs `test.rb` using Ruby in lldb
|
||||
* `make gdb-runruby`: Runs `test.rb` using Ruby in gdb
|
||||
|
|
@ -1,10 +1,25 @@
|
|||
= Documentation Guide
|
||||
# Documentation Guide
|
||||
|
||||
This guide discusses recommendations for documenting
|
||||
classes, modules, and methods
|
||||
in the Ruby core and in the Ruby standard library.
|
||||
|
||||
== Goal
|
||||
## Generating documentation
|
||||
|
||||
Most Ruby documentation lives in the source files and is written in [RDoc format](https://ruby.github.io/rdoc/RDoc/Markup.html).
|
||||
|
||||
Some pages live under the `doc` folder and can be written in either `.rdoc` or `.md` format, determined by the file extension.
|
||||
|
||||
To generate the output of documentation changes in HTML in the `{build folder}/.ext/html` directory, run the following inside your build directory:
|
||||
|
||||
```
|
||||
make html
|
||||
```
|
||||
|
||||
Then you can preview your changes by opening `{build folder}/.ext/html/index.html` file in your browser.
|
||||
|
||||
|
||||
## Goal
|
||||
|
||||
The goal of Ruby documentation is to impart the most important
|
||||
and relevant in the shortest time.
|
||||
|
|
@ -15,27 +30,26 @@ Providing too little information is bad, but providing unimportant
|
|||
information or unnecessary examples is not good either.
|
||||
Use your judgment about what the user needs to know.
|
||||
|
||||
== General Guidelines
|
||||
## General Guidelines
|
||||
|
||||
- Keep in mind that the reader may not be fluent in \English.
|
||||
- Write short declarative or imperative sentences.
|
||||
- Group sentences into (ideally short) paragraphs,
|
||||
each covering a single topic.
|
||||
- Organize material with {headers}[rdoc-ref:RDoc::Markup@Headers].
|
||||
- Organize material with [headers](rdoc-ref:RDoc::Markup@Headers).
|
||||
- Refer to authoritative and relevant sources using
|
||||
{links}[rdoc-ref:RDoc::Markup@Links].
|
||||
[links](rdoc-ref:RDoc::Markup@Links).
|
||||
- Use simple verb tenses: simple present, simple past, simple future.
|
||||
- Use simple sentence structure, not compound or complex structure.
|
||||
- Avoid:
|
||||
- Excessive comma-separated phrases;
|
||||
consider a [list](rdoc-ref:RDoc::Markup@Simple+Lists).
|
||||
- Idioms and culture-specific references.
|
||||
- Overuse of headers.
|
||||
- Using US-ASCII-incompatible characters in C source files;
|
||||
see [Characters](#label-Characters) below.
|
||||
|
||||
- Excessive comma-separated phrases;
|
||||
consider a {list}[rdoc-ref:RDoc::Markup@Simple+Lists].
|
||||
- Idioms and culture-specific references.
|
||||
- Overuse of headers.
|
||||
- Using US-ASCII-incompatible characters in C source files;
|
||||
see {Characters}[#label-Characters] below.
|
||||
|
||||
=== Characters
|
||||
### Characters
|
||||
|
||||
Use only US-ASCII-compatible characters in a C source file.
|
||||
(If you use other characters, the Ruby CI will gently let you know.)
|
||||
|
|
@ -44,33 +58,36 @@ If want to put ASCII-incompatible characters into the documentation
|
|||
for a C-coded class, module, or method, there are workarounds
|
||||
involving new files <tt>doc/*.rdoc</tt>:
|
||||
|
||||
- For class +Foo+ (defined in file <tt>foo.c</tt>),
|
||||
- For class `Foo` (defined in file <tt>foo.c</tt>),
|
||||
create file <tt>doc/foo.rdoc</tt>, declare <tt>class Foo; end</tt>,
|
||||
and place the class documentation above that declaration:
|
||||
|
||||
# :markup: ruby
|
||||
```ruby
|
||||
# Documentation for class Foo goes here.
|
||||
class Foo; end
|
||||
```
|
||||
|
||||
- Similarly, for module +Bar+ (defined in file <tt>bar.c</tt>,
|
||||
- Similarly, for module `Bar` (defined in file <tt>bar.c</tt>,
|
||||
create file <tt>doc/bar.rdoc</tt>, declare <tt>module Bar; end</tt>,
|
||||
and place the module documentation above that declaration:
|
||||
|
||||
# :markup: ruby
|
||||
```ruby
|
||||
# Documentation for module Bar goes here.
|
||||
module Bar; end
|
||||
```
|
||||
|
||||
- For a method, things are different.
|
||||
Documenting a method as above disables the "click to toggle source" feature
|
||||
in the rendered documentation.
|
||||
|
||||
Therefore it's best to use file inclusion:
|
||||
Therefore it's best to use file inclusion:
|
||||
|
||||
- Retain the call-seq in the C code.
|
||||
- Use file inclusion (`:include:`) to include text from an .rdoc file.
|
||||
|
||||
- Retain the call-seq in the C code.
|
||||
- Use file inclusion (+:include:+) to include text from an .rdoc file.
|
||||
|
||||
Example:
|
||||
Example:
|
||||
|
||||
```c
|
||||
/*
|
||||
* call-seq:
|
||||
* each_byte {|byte| ... } -> self
|
||||
|
|
@ -79,74 +96,77 @@ involving new files <tt>doc/*.rdoc</tt>:
|
|||
* \:include: doc/string/each_byte.rdoc
|
||||
*
|
||||
*/
|
||||
```
|
||||
|
||||
=== \RDoc
|
||||
### \RDoc
|
||||
|
||||
Ruby is documented using RDoc.
|
||||
For information on \RDoc syntax and features, see the
|
||||
{RDoc Markup Reference}[rdoc-ref:RDoc::Markup@RDoc+Markup+Reference].
|
||||
[RDoc Markup Reference](rdoc-ref:RDoc::Markup@RDoc+Markup+Reference).
|
||||
|
||||
=== Output from <tt>irb</tt>
|
||||
### Output from <tt>irb</tt>
|
||||
|
||||
For code examples, consider using interactive Ruby,
|
||||
{irb}[https://ruby-doc.org/stdlib/libdoc/irb/rdoc/IRB.html].
|
||||
[irb](https://ruby-doc.org/stdlib/libdoc/irb/rdoc/IRB.html).
|
||||
|
||||
For a code example that includes +irb+ output,
|
||||
For a code example that includes `irb` output,
|
||||
consider aligning <tt># => ...</tt> in successive lines.
|
||||
Alignment may sometimes aid readability:
|
||||
|
||||
a = [1, 2, 3] #=> [1, 2, 3]
|
||||
a.shuffle! #=> [2, 3, 1]
|
||||
a #=> [2, 3, 1]
|
||||
```ruby
|
||||
a = [1, 2, 3] #=> [1, 2, 3]
|
||||
a.shuffle! #=> [2, 3, 1]
|
||||
a #=> [2, 3, 1]
|
||||
```
|
||||
|
||||
=== Headers
|
||||
### Headers
|
||||
|
||||
Organize a long discussion with {headers}[rdoc-ref:RDoc::Markup@Headers].
|
||||
Organize a long discussion with [headers](rdoc-ref:RDoc::Markup@Headers).
|
||||
|
||||
=== Blank Lines
|
||||
### Blank Lines
|
||||
|
||||
A blank line begins a new paragraph.
|
||||
|
||||
A {code block}[rdoc-ref:RDoc::Markup@Paragraphs+and+Verbatim]
|
||||
or {list}[rdoc-ref:RDoc::Markup@Simple+Lists]
|
||||
A [code block](rdoc-ref:RDoc::Markup@Paragraphs+and+Verbatim)
|
||||
or [list](rdoc-ref:RDoc::Markup@Simple+Lists)
|
||||
should be preceded by and followed by a blank line.
|
||||
This is unnecessary for the HTML output, but helps in the +ri+ output.
|
||||
This is unnecessary for the HTML output, but helps in the `ri` output.
|
||||
|
||||
=== Auto-Linking
|
||||
### Auto-Linking
|
||||
|
||||
In general, \RDoc's auto-linking should not be suppressed.
|
||||
For example, we should write +Array+, not <tt>\Array</tt>.
|
||||
For example, we should write `Array`, not <tt>\Array</tt>.
|
||||
|
||||
We might consider whether to suppress when:
|
||||
|
||||
- The word in question does not refer to a Ruby entity
|
||||
(e.g., some uses of _Class_ or _English_).
|
||||
- The reference is to the current class document
|
||||
(e.g., _Array_ in the documentation for class +Array+).
|
||||
(e.g., _Array_ in the documentation for class `Array`).
|
||||
- The same reference is repeated many times
|
||||
(e.g., _RDoc_ on this page).
|
||||
|
||||
== Documenting Classes and Modules
|
||||
## Documenting Classes and Modules
|
||||
|
||||
The general structure of the class or module documentation should be:
|
||||
|
||||
* Synopsis
|
||||
* Common uses, with examples
|
||||
* "What's Here" summary (optional)
|
||||
- Synopsis
|
||||
- Common uses, with examples
|
||||
- "What's Here" summary (optional)
|
||||
|
||||
=== Synopsis
|
||||
### Synopsis
|
||||
|
||||
The synopsis is a short description of what the class or module does
|
||||
and why the reader might want to use it.
|
||||
Avoid details in the synopsis.
|
||||
|
||||
=== Common Uses
|
||||
### Common Uses
|
||||
|
||||
Show common uses of the class or module.
|
||||
Depending on the class or module, this section may vary greatly
|
||||
in both length and complexity.
|
||||
|
||||
=== What's Here Summary
|
||||
### What's Here Summary
|
||||
|
||||
The documentation for a class or module may include a "What's Here" section.
|
||||
|
||||
|
|
@ -154,54 +174,58 @@ Guidelines:
|
|||
|
||||
- The section title is <tt>What's Here</tt>.
|
||||
- Consider listing the parent class and any included modules; consider
|
||||
{links}[rdoc-ref:RDoc::Markup@Links]
|
||||
[links](rdoc-ref:RDoc::Markup@Links)
|
||||
to their "What's Here" sections if those exist.
|
||||
- List methods as a bullet list:
|
||||
|
||||
- Begin each item with the method name, followed by a colon
|
||||
and a short description.
|
||||
- If the method has aliases, mention them in parentheses before the colon
|
||||
(and do not list the aliases separately).
|
||||
- Check the rendered documentation to determine whether \RDoc has recognized
|
||||
the method and linked to it; if not, manually insert a
|
||||
{link}[rdoc-ref:RDoc::Markup@Links].
|
||||
- Begin each item with the method name, followed by a colon
|
||||
and a short description.
|
||||
- If the method has aliases, mention them in parentheses before the colon
|
||||
(and do not list the aliases separately).
|
||||
- Check the rendered documentation to determine whether \RDoc has recognized
|
||||
the method and linked to it; if not, manually insert a
|
||||
[link](rdoc-ref:RDoc::Markup@Links).
|
||||
|
||||
- If there are numerous entries, consider grouping them into subsections with headers.
|
||||
- If there are more than a few such subsections,
|
||||
consider adding a table of contents just below the main section title.
|
||||
|
||||
== Documenting Methods
|
||||
## Documenting Methods
|
||||
|
||||
=== General Structure
|
||||
### General Structure
|
||||
|
||||
The general structure of the method documentation should be:
|
||||
|
||||
* Calling sequence (for methods written in C).
|
||||
* Synopsis (short description).
|
||||
* Details and examples.
|
||||
* Argument description (if necessary).
|
||||
* Corner cases and exceptions.
|
||||
* Aliases.
|
||||
* Related methods (optional).
|
||||
- Calling sequence (for methods written in C).
|
||||
- Synopsis (short description).
|
||||
- Details and examples.
|
||||
- Argument description (if necessary).
|
||||
- Corner cases and exceptions.
|
||||
- Aliases.
|
||||
- Related methods (optional).
|
||||
|
||||
=== Calling Sequence (for methods written in C)
|
||||
### Calling Sequence (for methods written in C)
|
||||
|
||||
For methods written in Ruby, \RDoc documents the calling sequence automatically.
|
||||
|
||||
For methods written in C, \RDoc cannot determine what arguments
|
||||
the method accepts, so those need to be documented using \RDoc directive
|
||||
{:call-seq:}[rdoc-ref:RDoc::Markup@Method+arguments].
|
||||
[:call-seq:](rdoc-ref:RDoc::Markup@Method+arguments).
|
||||
|
||||
Example:
|
||||
|
||||
* call-seq:
|
||||
* array.count -> integer
|
||||
* array.count(obj) -> integer
|
||||
* array.count {|element| ... } -> integer
|
||||
```
|
||||
* call-seq:
|
||||
* array.count -> integer
|
||||
* array.count(obj) -> integer
|
||||
* array.count {|element| ... } -> integer
|
||||
```
|
||||
|
||||
When creating the <tt>call-seq</tt>, use the form
|
||||
|
||||
receiver_type.method_name(arguments) {|block_arguments|} -> return_type
|
||||
```
|
||||
receiver_type.method_name(arguments) {|block_arguments|} -> return_type
|
||||
```
|
||||
|
||||
Omit the parentheses for cases where the method does not accept arguments,
|
||||
and omit the block for cases where a block is not accepted.
|
||||
|
|
@ -215,12 +239,16 @@ with an optional argument if the method has the same behavior when an argument
|
|||
is omitted as when the argument is passed with the default value. For example,
|
||||
use:
|
||||
|
||||
* obj.respond_to?(symbol, include_all=false) -> true or false
|
||||
```
|
||||
obj.respond_to?(symbol, include_all=false) -> true or false
|
||||
```
|
||||
|
||||
Instead of:
|
||||
|
||||
* obj.respond_to?(symbol) -> true or false
|
||||
* obj.respond_to?(symbol, include_all) -> true or false
|
||||
```
|
||||
obj.respond_to?(symbol) -> true or false
|
||||
obj.respond_to?(symbol, include_all) -> true or false
|
||||
```
|
||||
|
||||
However, as shown above for <tt>Array#count</tt>, use separate lines if the
|
||||
behavior is different if the argument is omitted.
|
||||
|
|
@ -228,15 +256,15 @@ behavior is different if the argument is omitted.
|
|||
Omit aliases from the call-seq, but mention them near the end (see below).
|
||||
|
||||
|
||||
A +call-seq+ block should have <tt>{|x| ... }</tt>, not <tt>{|x| block }</tt> or <tt>{|x| code }</tt>.
|
||||
A `call-seq` block should have <tt>{|x| ... }</tt>, not <tt>{|x| block }</tt> or <tt>{|x| code }</tt>.
|
||||
|
||||
A +call-seq+ output should:
|
||||
A `call-seq` output should:
|
||||
|
||||
- Have +self+, not +receiver+ or +array+.
|
||||
- Begin with +new_+ if and only if the output object is a new instance
|
||||
of the receiver's class, to emphasize that the output object is not +self+.
|
||||
- Have `self`, not `receiver` or `array`.
|
||||
- Begin with `new_` if and only if the output object is a new instance
|
||||
of the receiver's class, to emphasize that the output object is not `self`.
|
||||
|
||||
=== Synopsis
|
||||
### Synopsis
|
||||
|
||||
The synopsis comes next, and is a short description of what the
|
||||
method does and why you would want to use it. Ideally, this
|
||||
|
|
@ -245,13 +273,15 @@ an entire paragraph.
|
|||
|
||||
For <tt>Array#count</tt>, the synopsis is:
|
||||
|
||||
Returns a count of specified elements.
|
||||
```
|
||||
Returns a count of specified elements.
|
||||
```
|
||||
|
||||
This is great as it is short and descriptive. Avoid documenting
|
||||
too much in the synopsis, stick to the most important information
|
||||
for the benefit of the reader.
|
||||
|
||||
=== Details and Examples
|
||||
### Details and Examples
|
||||
|
||||
Most non-trivial methods benefit from examples, as well as details
|
||||
beyond what is given in the synopsis. In the details and examples
|
||||
|
|
@ -261,10 +291,10 @@ section, focus on how to use the method properly, not on how the
|
|||
method handles improper arguments or corner cases.
|
||||
|
||||
Not every behavior of a method requires an example. If the method
|
||||
is documented to return +self+, you don't need to provide an example
|
||||
is documented to return `self`, you don't need to provide an example
|
||||
showing the return value is the same as the receiver. If the method
|
||||
is documented to return +nil+, you don't need to provide an example
|
||||
showing that it returns +nil+. If the details mention that for a
|
||||
is documented to return `nil`, you don't need to provide an example
|
||||
showing that it returns `nil`. If the details mention that for a
|
||||
certain argument type, an empty array is returned, you don't need
|
||||
to provide an example for that.
|
||||
|
||||
|
|
@ -273,7 +303,7 @@ do not add an example if it provides the same information given
|
|||
in the synopsis or details. The purpose of examples is not to prove
|
||||
what the details are stating.
|
||||
|
||||
=== Argument Description (if necessary)
|
||||
### Argument Description (if necessary)
|
||||
|
||||
For methods that require arguments, if not obvious and not explicitly
|
||||
mentioned in the details or implicitly shown in the examples, you can
|
||||
|
|
@ -289,9 +319,9 @@ argument passed if it is not obvious, not explicitly mentioned in the
|
|||
details, and not implicitly shown in the examples.
|
||||
|
||||
If there is more than one argument or block argument, use a
|
||||
{labeled list}[rdoc-ref:RDoc::Markup@Labeled+Lists]}
|
||||
[labeled list](rdoc-ref:RDoc::Markup@Labeled+Lists).
|
||||
|
||||
=== Corner Cases and Exceptions
|
||||
### Corner Cases and Exceptions
|
||||
|
||||
For corner cases of methods, such as atypical usage, briefly mention
|
||||
the behavior, but do not provide any examples.
|
||||
|
|
@ -302,25 +332,27 @@ you do not need to document that a \TypeError is raised if a non-integer
|
|||
is passed. Do not provide examples of exceptions being raised unless
|
||||
that is a common case, such as \Hash#fetch raising a \KeyError.
|
||||
|
||||
=== Aliases
|
||||
### Aliases
|
||||
|
||||
Mention aliases in the form
|
||||
|
||||
Array#find_index is an alias for Array#index.
|
||||
```c
|
||||
// Array#find_index is an alias for Array#index.
|
||||
```
|
||||
|
||||
=== Related Methods (optional)
|
||||
### Related Methods (optional)
|
||||
|
||||
In some cases, it is useful to document which methods are related to
|
||||
the current method. For example, documentation for \Hash#[] might
|
||||
mention \Hash#fetch as a related method, and \Hash#merge might mention
|
||||
\Hash#merge! as a related method. Consider which methods may be related
|
||||
the current method. For example, documentation for `Hash#[]` might
|
||||
mention `Hash#fetch` as a related method, and `Hash#merge` might mention
|
||||
`Hash#merge!` as a related method. Consider which methods may be related
|
||||
to the current method, and if you think the reader would benefit it,
|
||||
at the end of the method documentation, add a line starting with
|
||||
"Related: " (e.g. "Related: #fetch"). Don't list more than three
|
||||
related methods. If you think more than three methods are related,
|
||||
pick the three you think are most important and list those three.
|
||||
|
||||
=== Methods Accepting Multiple Argument Types
|
||||
### Methods Accepting Multiple Argument Types
|
||||
|
||||
For methods that accept multiple argument types, in some cases it can
|
||||
be useful to document the different argument types separately. It's
|
||||
36
doc/contributing/making_changes_to_ruby.md
Normal file
36
doc/contributing/making_changes_to_ruby.md
Normal file
|
|
@ -0,0 +1,36 @@
|
|||
# Contributing a pull request
|
||||
|
||||
## Code style
|
||||
|
||||
Here are some general rules to follow when writing Ruby and C code for CRuby:
|
||||
|
||||
* Do not change code unrelated to your pull request (including style fixes)
|
||||
* Indent 4 spaces for C without tabs (tabs are two levels of indentation, equivalent to 8 spaces)
|
||||
* Indent 2 spaces for Ruby without tabs
|
||||
* ANSI C style for function declarations
|
||||
* Follow C99 Standard
|
||||
* PascalStyle for class/module names
|
||||
* UNDERSCORE_SEPARATED_UPPER_CASE for other constants
|
||||
* Abbreviations should be all upper case
|
||||
|
||||
## Commit messages
|
||||
|
||||
Use the following style for commit messages:
|
||||
|
||||
* Use a succinct subject line
|
||||
* Include reasoning behind the change in the commit message, focusing on why the change is being made
|
||||
* Refer to issue (such as `Fixes [Bug #1234]` or `Implements [Feature #3456]`), or discussion on the mailing list (such as [ruby-core:12345])
|
||||
|
||||
## CI
|
||||
|
||||
GitHub actions will run on each pull request.
|
||||
|
||||
There is [a CI that runs on master](https://rubyci.org/). It has broad coverage of different systems and architectures, such as Solaris SPARC and macOS.
|
||||
|
||||
# Contributing to standard libraries
|
||||
|
||||
Everything in the [lib](https://github.com/ruby/ruby/tree/master/lib) directory is mirrored from a standalone repository into the Ruby repository.
|
||||
If you'd like to make contributions to standard libraries, do so in the standalone repositories, and the
|
||||
changes will be automatically mirrored into the Ruby repository.
|
||||
|
||||
For example, CSV lives in [a separate repository](https://github.com/ruby/csv) and is mirrored into [Ruby](https://github.com/ruby/ruby/tree/master/lib/csv).
|
||||
91
doc/contributing/reporting_issues.md
Normal file
91
doc/contributing/reporting_issues.md
Normal file
|
|
@ -0,0 +1,91 @@
|
|||
# Reporting Issues
|
||||
## Reporting security issues
|
||||
|
||||
If you've found a security vulnerability, please follow
|
||||
[these instructions](https://www.ruby-lang.org/en/security/).
|
||||
|
||||
## Reporting bugs
|
||||
|
||||
If you've encountered a bug in Ruby, please report it to the Redmine issue
|
||||
tracker available at [bugs.ruby-lang.org](https://bugs.ruby-lang.org/), by
|
||||
following these steps:
|
||||
|
||||
* Check if anyone has already reported your issue by
|
||||
searching [the Redmine issue tracker](https://bugs.ruby-lang.org/projects/ruby-master/issues).
|
||||
* If you haven't already,
|
||||
[sign up for an account](https://bugs.ruby-lang.org/account/register) on the
|
||||
Redmine issue tracker.
|
||||
* If you can't find a ticket addressing your issue, please [create a new issue](https://bugs.ruby-lang.org/projects/ruby-master/issues/new). You will need to fill in the subject, description and Ruby version.
|
||||
|
||||
* Ensure the issue exists on Ruby master by trying to replicate your bug on
|
||||
the head of master (see ["making changes to Ruby"](making_changes_to_ruby.md)).
|
||||
* Write a concise subject and briefly describe your problem in the description section. If
|
||||
your issue affects [a released version of Ruby](#label-Backport+requests), please say so.
|
||||
* Fill in the Ruby version you're using when experiencing this issue
|
||||
(the output of running `ruby -v`).
|
||||
* Attach any logs or reproducible programs to provide additional information.
|
||||
Any scripts should be as small as possible.
|
||||
* 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 website issues
|
||||
|
||||
If you're having an issue with the bug tracker or the mailing list, you can
|
||||
contact the webmaster, Hiroshi SHIBATA (hsbt@ruby-lang.org).
|
||||
|
||||
You can report issues with ruby-lang.org on the
|
||||
[repo's issue tracker](https://github.com/ruby/www.ruby-lang.org/issues).
|
||||
|
||||
## Requesting features
|
||||
|
||||
If there's a new feature that you want to see added to Ruby, you will need to
|
||||
write a proposal on [the Redmine issue tracker](https://bugs.ruby-lang.org/projects/ruby-master/issues/new).
|
||||
When you open the issue, select `Feature` in the Tracker dropdown.
|
||||
|
||||
When writing a proposal, be sure to check for previous discussions on the
|
||||
topic and have a solid use case. 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.
|
||||
|
||||
Here is a template you can use for a feature proposal:
|
||||
|
||||
```
|
||||
[Abstract]
|
||||
Briefly summarize your feature
|
||||
[Background]
|
||||
Describe current behavior
|
||||
[Proposal]
|
||||
Describe your feature in detail
|
||||
[Use cases]
|
||||
Give specific example uses of your feature
|
||||
[Discussion]
|
||||
Describe why this feature is necessary and better than using existing features
|
||||
[See also]
|
||||
Link to other related resources (such as implementations in other languages)
|
||||
```
|
||||
|
||||
## Backport requests
|
||||
|
||||
If a bug exists in a released version of Ruby, please report this in the issue.
|
||||
Once this bug is fixed, the fix can be backported if deemed necessary. Only Ruby
|
||||
committers can request backporting, and backporting is done by the backport manager.
|
||||
New patch versions are released at the discretion of the backport manager.
|
||||
|
||||
[Ruby versions](https://www.ruby-lang.org/en/downloads/) can be in one of three maintenance states:
|
||||
|
||||
* Stable releases: backport any bug fixes
|
||||
* Security maintenance: only backport security fixes
|
||||
* End of life: no backports, please upgrade your Ruby version
|
||||
|
||||
## Add context to existing issues
|
||||
|
||||
There are several ways you can help with a bug that aren't directly
|
||||
resolving it. These include:
|
||||
|
||||
* Verifying or reproducing the existing issue and reporting it
|
||||
* Adding more specific reproduction instructions
|
||||
* Contributing a failing test as a patch (see ["making changes to Ruby"](making_changes_to_ruby.md))
|
||||
* Testing patches that others have submitted (see ["making changes to Ruby"](making_changes_to_ruby.md))
|
||||
100
doc/contributing/testing_ruby.md
Normal file
100
doc/contributing/testing_ruby.md
Normal file
|
|
@ -0,0 +1,100 @@
|
|||
# Testing Ruby
|
||||
|
||||
## Test suites
|
||||
|
||||
There are several test suites in the Ruby codebase:
|
||||
|
||||
We can run any of the make scripts [in parallel](building_ruby.md#label-Running+make+scripts+in+parallel) to speed them up.
|
||||
|
||||
1. [bootstraptest/](https://github.com/ruby/ruby/tree/master/bootstraptest)
|
||||
|
||||
This is a small test suite that runs on Miniruby (see [building Ruby](building_ruby.md#label-Miniruby+vs+Ruby)). We can run it with:
|
||||
|
||||
```
|
||||
make btest
|
||||
```
|
||||
|
||||
To run it with logs, we can use:
|
||||
|
||||
```
|
||||
make btest OPTS=-v
|
||||
```
|
||||
|
||||
If we want to run the bootstrap test suite on Ruby (not Miniruby), we can use:
|
||||
|
||||
```
|
||||
make test
|
||||
```
|
||||
|
||||
To run it with logs, we can use:
|
||||
|
||||
```
|
||||
make test OPTS=-v
|
||||
```
|
||||
|
||||
2. [test/](https://github.com/ruby/ruby/tree/master/test)
|
||||
|
||||
This is a more comprehensive test suite that runs on Ruby. We can run it with:
|
||||
|
||||
```
|
||||
make test-all
|
||||
```
|
||||
|
||||
We can run a specific test file in this suite using the `TESTS` environment variable, for example:
|
||||
|
||||
```
|
||||
make test-all TESTS=test/ruby/test_array.rb
|
||||
```
|
||||
|
||||
We can run a specific test in this suite using the `TESTS` environment variable, specifying
|
||||
first the file name, and then the test name, prefixed with `--name`. For example:
|
||||
|
||||
```
|
||||
make test-all TESTS="../test/ruby/test_alias.rb --name=/test_aias_with_zsuper_method/"
|
||||
```
|
||||
|
||||
To run these specs with logs, we can use:
|
||||
|
||||
```
|
||||
make test-all TESTS=-v
|
||||
```
|
||||
|
||||
If we would like to run both the `test/` and `bootstraptest/` test suites, we can run
|
||||
|
||||
```
|
||||
make check
|
||||
```
|
||||
|
||||
3. [spec/ruby](https://github.com/ruby/ruby/tree/master/spec/ruby)
|
||||
|
||||
This is a test suite that exists in [the Ruby spec repository](https://github.com/ruby/spec) and is mirrored into the `spec/ruby` directory in the Ruby repository. It tests the behavior of the Ruby programming language. We can run this using:
|
||||
|
||||
```
|
||||
make test-spec
|
||||
```
|
||||
|
||||
To run a specific file, we can use `MSPECOPT` to specify the file:
|
||||
|
||||
```
|
||||
make test-spec MSPECOPT=spec/ruby/core/array/any_spec.rb
|
||||
```
|
||||
|
||||
To run a specific test, we can use the `--example` flag to match against the test name:
|
||||
|
||||
```
|
||||
make test-spec MSPECOPT="../spec/ruby/core/array/any_spec.rb --example='is false if the array is empty'"
|
||||
```
|
||||
|
||||
To run these specs with logs, we can use:
|
||||
|
||||
```
|
||||
make test-spec MSPECOPT=-Vfs
|
||||
```
|
||||
|
||||
4. [spec/bundler](https://github.com/ruby/ruby/tree/master/spec/bundler)
|
||||
|
||||
The bundler test suite exists in [the RubyGems repository](https://github.com/rubygems/rubygems/tree/master/bundler/spec) and is mirrored into the `spec/bundler` directory in the Ruby repository. We can run this using:
|
||||
|
||||
```
|
||||
make test-bundler
|
||||
```
|
||||
104
doc/hacking.md
104
doc/hacking.md
|
|
@ -1,104 +0,0 @@
|
|||
# Ruby Hacking Guide
|
||||
|
||||
This document gives some helpful instructions which should make your
|
||||
experience as a Ruby core developer easier.
|
||||
|
||||
## Setup
|
||||
|
||||
### Make
|
||||
|
||||
It's common to want to compile things as quickly as possible. Ensuring
|
||||
`make` has the right `--jobs` flag will ensure all processors are
|
||||
utilized when building software projects To do this effectively, you
|
||||
can set `MAKEFLAGS` in your shell configuration/profile:
|
||||
|
||||
``` shell
|
||||
# On macOS with Fish shell:
|
||||
export MAKEFLAGS="--jobs "(sysctl -n hw.ncpu)
|
||||
|
||||
# On macOS with Bash/ZSH shell:
|
||||
export MAKEFLAGS="--jobs $(sysctl -n hw.ncpu)"
|
||||
|
||||
# On Linux with Fish shell:
|
||||
export MAKEFLAGS="--jobs "(nproc)
|
||||
|
||||
# On Linux with Bash/ZSH shell:
|
||||
export MAKEFLAGS="--jobs $(nproc)"
|
||||
```
|
||||
|
||||
## Configure Ruby
|
||||
|
||||
It's generally advisable to use a build directory.
|
||||
|
||||
``` shell
|
||||
./autogen.sh
|
||||
mkdir build
|
||||
cd build
|
||||
../configure --prefix $HOME/.rubies/ruby-head
|
||||
make install
|
||||
```
|
||||
|
||||
### Without Documentation
|
||||
|
||||
If you are frequently building Ruby, this will reduce the time it
|
||||
takes to `make install`.
|
||||
|
||||
``` shell
|
||||
../configure --disable-install-doc
|
||||
```
|
||||
|
||||
## Running Ruby
|
||||
|
||||
### Run Local Test Script
|
||||
|
||||
You can create a file in the Ruby source root called `test.rb`. You
|
||||
can build `miniruby` and execute this script:
|
||||
|
||||
``` shell
|
||||
make run
|
||||
```
|
||||
|
||||
If you want more of the standard library, you can use `runruby`
|
||||
instead of `run`.
|
||||
|
||||
## Running Tests
|
||||
|
||||
You can run the following tests at once:
|
||||
|
||||
``` shell
|
||||
make check
|
||||
```
|
||||
|
||||
### Run Bootstrap Tests
|
||||
|
||||
There are a set of tests in `bootstraptest/` which cover most basic
|
||||
features of the core Ruby language.
|
||||
|
||||
``` shell
|
||||
make test
|
||||
```
|
||||
|
||||
### Run Extensive Tests
|
||||
|
||||
There are extensive tests in `test/` which cover a wide range of
|
||||
features of the Ruby core language.
|
||||
|
||||
``` shell
|
||||
make test-all
|
||||
```
|
||||
|
||||
You can run specific tests by specifying their path:
|
||||
|
||||
``` shell
|
||||
make test-all TESTS=../test/fiber/test_io.rb
|
||||
```
|
||||
|
||||
### Run Ruby Spec Suite Tests
|
||||
|
||||
The [Ruby Spec Suite](https://github.com/ruby/spec/) is a test suite
|
||||
that aims to provide an executable description for the behavior of the
|
||||
language.
|
||||
|
||||
``` shell
|
||||
make test-spec
|
||||
```
|
||||
|
|
@ -1,124 +0,0 @@
|
|||
# How to use "configure" and "make" commands for Ruby
|
||||
|
||||
This is for developers of Ruby.
|
||||
If you are a user of Ruby, please see README.md.
|
||||
|
||||
## In-place build
|
||||
|
||||
```
|
||||
$ ./autogen.sh
|
||||
$ ./configure --prefix=$PWD/local
|
||||
$ make
|
||||
$ make install
|
||||
$ ./local/bin/ruby -e 'puts "Hello"'
|
||||
Hello
|
||||
```
|
||||
|
||||
## Out-of-place build
|
||||
|
||||
```
|
||||
$ ./autogen.sh
|
||||
$ mkdir ../ruby-build
|
||||
$ cd ../ruby-build
|
||||
$ ../ruby-src/configure --prefix=$PWD/local
|
||||
$ make
|
||||
$ make install
|
||||
$ ./local/bin/ruby -e 'puts "Hello"'
|
||||
Hello
|
||||
```
|
||||
|
||||
## How to run the whole test suite
|
||||
|
||||
```
|
||||
$ make check
|
||||
```
|
||||
|
||||
It runs (about) four test suites:
|
||||
|
||||
* `make test` (a test suite for the interpreter core)
|
||||
* `make test-all` (for all builtin classes and libraries)
|
||||
* `make test-spec` (a conformance test suite for Ruby implementations)
|
||||
* `make test-bundler` (a test suite for the bundler examples)
|
||||
|
||||
## How to run the test suite with log
|
||||
|
||||
```
|
||||
$ make test OPTS=-v
|
||||
|
||||
$ make test-all TESTS=-v
|
||||
|
||||
$ make test-spec MSPECOPT=-Vfs
|
||||
```
|
||||
|
||||
## How to run a part of the test suite
|
||||
|
||||
### Runs a directory
|
||||
```
|
||||
$ make test-all TESTS=test/rubygems
|
||||
$ make test-all TESTS=rubygems
|
||||
```
|
||||
|
||||
### Runs a file
|
||||
```
|
||||
$ make test-all TESTS=test/ruby/test_foo.rb
|
||||
$ make test-all TESTS=ruby/foo
|
||||
```
|
||||
|
||||
### Runs a test whose name includes test_bar
|
||||
```
|
||||
$ make test-all TESTS="test/ruby/test_foo.rb -n /test_bar/"
|
||||
```
|
||||
|
||||
### Runs a file or directory with GNU make
|
||||
```
|
||||
$ make test/ruby/test_foo.rb
|
||||
$ make test/ruby/test_foo.rb TESTOPTS="-n /test_bar/"
|
||||
```
|
||||
|
||||
### Runs a ruby-spec directory
|
||||
```
|
||||
$ make test-spec MSPECOPT=spec/ruby/core/foo
|
||||
```
|
||||
|
||||
### Runs a ruby-spec file
|
||||
```
|
||||
$ make test-spec MSPECOPT=spec/ruby/core/foo/bar_spec.rb
|
||||
```
|
||||
|
||||
### Runs a ruby-spec file or directory with GNU make
|
||||
```
|
||||
$ make spec/ruby/core/foo/bar_spec.rb
|
||||
```
|
||||
|
||||
### Runs a bundler spec file
|
||||
```
|
||||
$ make test-bundler BUNDLER_SPECS=commands/exec_spec.rb:58
|
||||
```
|
||||
|
||||
## How to measure coverage of C and Ruby code
|
||||
|
||||
You need to be able to use gcc (gcov) and lcov visualizer.
|
||||
|
||||
```
|
||||
$ ./autogen.sh
|
||||
$ ./configure --enable-gcov
|
||||
$ make
|
||||
$ make update-coverage
|
||||
$ rm -f test-coverage.dat
|
||||
$ make test-all COVERAGE=true
|
||||
$ make lcov
|
||||
$ open lcov-out/index.html
|
||||
```
|
||||
|
||||
If you need only C code coverage, you can remove `COVERAGE=true` from the above process.
|
||||
You can also use `gcov` command directly to get per-file coverage.
|
||||
|
||||
If you need only Ruby code coverage, you can remove `--enable-gcov`.
|
||||
Note that `test-coverage.dat` accumulates all runs of `make test-all`.
|
||||
Make sure that you remove the file if you want to measure one test run.
|
||||
|
||||
You can see the coverage result of CI: https://rubyci.org/coverage
|
||||
|
||||
## How to benchmark
|
||||
|
||||
see https://github.com/ruby/ruby/tree/master/benchmark#make-benchmark
|
||||
Loading…
Reference in a new issue