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
|
||||||
COPYING.ja
|
COPYING.ja
|
||||||
CONTRIBUTING.md
|
|
||||||
|
|
||||||
LEGAL
|
LEGAL
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1 @@
|
||||||
Please see the [official issue tracker], [doc/contributing.rdoc] and wiki [HowToContribute].
|
See ["Contributing to Ruby"](https://docs.ruby-lang.org/en/master/contributing_md.html), which includes setup and build instructions.
|
||||||
|
|
||||||
[official issue tracker]: https://bugs.ruby-lang.org
|
|
||||||
[doc/contributing.rdoc]: contributing.rdoc
|
|
||||||
[HowToContribute]: https://bugs.ruby-lang.org/projects/ruby/wiki/HowToContribute
|
|
||||||
|
|
|
||||||
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
|
[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
|
## Copying
|
||||||
|
|
||||||
See the file [COPYING](rdoc-ref:COPYING).
|
See the file [COPYING](rdoc-ref:COPYING).
|
||||||
|
|
||||||
## Feedback
|
## 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.
|
or on websites like https://stackoverflow.com.
|
||||||
|
|
||||||
Bugs should be reported at https://bugs.ruby-lang.org. Read [HowToReport] for more information.
|
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.
|
||||||
|
|
||||||
[Ruby-Talk]: https://www.ruby-lang.org/en/community/mailing-lists
|
|
||||||
[HowToReport]: https://bugs.ruby-lang.org/projects/ruby/wiki/HowToReport
|
|
||||||
|
|
||||||
## Contributing
|
## 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
|
## The Author
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,6 +1,7 @@
|
||||||
*.md
|
*.md
|
||||||
*.rb
|
*.rb
|
||||||
*.rdoc
|
*.rdoc
|
||||||
|
contributing
|
||||||
NEWS
|
NEWS
|
||||||
syntax
|
syntax
|
||||||
optparse
|
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
|
This guide discusses recommendations for documenting
|
||||||
classes, modules, and methods
|
classes, modules, and methods
|
||||||
in the Ruby core and in the Ruby standard library.
|
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
|
The goal of Ruby documentation is to impart the most important
|
||||||
and relevant in the shortest time.
|
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.
|
information or unnecessary examples is not good either.
|
||||||
Use your judgment about what the user needs to know.
|
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.
|
- Keep in mind that the reader may not be fluent in \English.
|
||||||
- Write short declarative or imperative sentences.
|
- Write short declarative or imperative sentences.
|
||||||
- Group sentences into (ideally short) paragraphs,
|
- Group sentences into (ideally short) paragraphs,
|
||||||
each covering a single topic.
|
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
|
- 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 verb tenses: simple present, simple past, simple future.
|
||||||
- Use simple sentence structure, not compound or complex structure.
|
- Use simple sentence structure, not compound or complex structure.
|
||||||
- Avoid:
|
- 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;
|
### Characters
|
||||||
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
|
|
||||||
|
|
||||||
Use only US-ASCII-compatible characters in a C source file.
|
Use only US-ASCII-compatible characters in a C source file.
|
||||||
(If you use other characters, the Ruby CI will gently let you know.)
|
(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
|
for a C-coded class, module, or method, there are workarounds
|
||||||
involving new files <tt>doc/*.rdoc</tt>:
|
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>,
|
create file <tt>doc/foo.rdoc</tt>, declare <tt>class Foo; end</tt>,
|
||||||
and place the class documentation above that declaration:
|
and place the class documentation above that declaration:
|
||||||
|
|
||||||
# :markup: ruby
|
```ruby
|
||||||
# Documentation for class Foo goes here.
|
# Documentation for class Foo goes here.
|
||||||
class Foo; end
|
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>,
|
create file <tt>doc/bar.rdoc</tt>, declare <tt>module Bar; end</tt>,
|
||||||
and place the module documentation above that declaration:
|
and place the module documentation above that declaration:
|
||||||
|
|
||||||
# :markup: ruby
|
```ruby
|
||||||
# Documentation for module Bar goes here.
|
# Documentation for module Bar goes here.
|
||||||
module Bar; end
|
module Bar; end
|
||||||
|
```
|
||||||
|
|
||||||
- For a method, things are different.
|
- For a method, things are different.
|
||||||
Documenting a method as above disables the "click to toggle source" feature
|
Documenting a method as above disables the "click to toggle source" feature
|
||||||
in the rendered documentation.
|
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.
|
Example:
|
||||||
- Use file inclusion (+:include:+) to include text from an .rdoc file.
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
|
```c
|
||||||
/*
|
/*
|
||||||
* call-seq:
|
* call-seq:
|
||||||
* each_byte {|byte| ... } -> self
|
* each_byte {|byte| ... } -> self
|
||||||
|
|
@ -79,74 +96,77 @@ involving new files <tt>doc/*.rdoc</tt>:
|
||||||
* \:include: doc/string/each_byte.rdoc
|
* \:include: doc/string/each_byte.rdoc
|
||||||
*
|
*
|
||||||
*/
|
*/
|
||||||
|
```
|
||||||
|
|
||||||
=== \RDoc
|
### \RDoc
|
||||||
|
|
||||||
Ruby is documented using RDoc.
|
Ruby is documented using RDoc.
|
||||||
For information on \RDoc syntax and features, see the
|
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,
|
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.
|
consider aligning <tt># => ...</tt> in successive lines.
|
||||||
Alignment may sometimes aid readability:
|
Alignment may sometimes aid readability:
|
||||||
|
|
||||||
a = [1, 2, 3] #=> [1, 2, 3]
|
```ruby
|
||||||
a.shuffle! #=> [2, 3, 1]
|
a = [1, 2, 3] #=> [1, 2, 3]
|
||||||
a #=> [2, 3, 1]
|
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 blank line begins a new paragraph.
|
||||||
|
|
||||||
A {code block}[rdoc-ref:RDoc::Markup@Paragraphs+and+Verbatim]
|
A [code block](rdoc-ref:RDoc::Markup@Paragraphs+and+Verbatim)
|
||||||
or {list}[rdoc-ref:RDoc::Markup@Simple+Lists]
|
or [list](rdoc-ref:RDoc::Markup@Simple+Lists)
|
||||||
should be preceded by and followed by a blank line.
|
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.
|
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:
|
We might consider whether to suppress when:
|
||||||
|
|
||||||
- The word in question does not refer to a Ruby entity
|
- The word in question does not refer to a Ruby entity
|
||||||
(e.g., some uses of _Class_ or _English_).
|
(e.g., some uses of _Class_ or _English_).
|
||||||
- The reference is to the current class document
|
- 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
|
- The same reference is repeated many times
|
||||||
(e.g., _RDoc_ on this page).
|
(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:
|
The general structure of the class or module documentation should be:
|
||||||
|
|
||||||
* Synopsis
|
- Synopsis
|
||||||
* Common uses, with examples
|
- Common uses, with examples
|
||||||
* "What's Here" summary (optional)
|
- "What's Here" summary (optional)
|
||||||
|
|
||||||
=== Synopsis
|
### Synopsis
|
||||||
|
|
||||||
The synopsis is a short description of what the class or module does
|
The synopsis is a short description of what the class or module does
|
||||||
and why the reader might want to use it.
|
and why the reader might want to use it.
|
||||||
Avoid details in the synopsis.
|
Avoid details in the synopsis.
|
||||||
|
|
||||||
=== Common Uses
|
### Common Uses
|
||||||
|
|
||||||
Show common uses of the class or module.
|
Show common uses of the class or module.
|
||||||
Depending on the class or module, this section may vary greatly
|
Depending on the class or module, this section may vary greatly
|
||||||
in both length and complexity.
|
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.
|
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>.
|
- The section title is <tt>What's Here</tt>.
|
||||||
- Consider listing the parent class and any included modules; consider
|
- 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.
|
to their "What's Here" sections if those exist.
|
||||||
- List methods as a bullet list:
|
- List methods as a bullet list:
|
||||||
|
|
||||||
- Begin each item with the method name, followed by a colon
|
- Begin each item with the method name, followed by a colon
|
||||||
and a short description.
|
and a short description.
|
||||||
- If the method has aliases, mention them in parentheses before the colon
|
- If the method has aliases, mention them in parentheses before the colon
|
||||||
(and do not list the aliases separately).
|
(and do not list the aliases separately).
|
||||||
- Check the rendered documentation to determine whether \RDoc has recognized
|
- Check the rendered documentation to determine whether \RDoc has recognized
|
||||||
the method and linked to it; if not, manually insert a
|
the method and linked to it; if not, manually insert a
|
||||||
{link}[rdoc-ref:RDoc::Markup@Links].
|
[link](rdoc-ref:RDoc::Markup@Links).
|
||||||
|
|
||||||
- If there are numerous entries, consider grouping them into subsections with headers.
|
- If there are numerous entries, consider grouping them into subsections with headers.
|
||||||
- If there are more than a few such subsections,
|
- If there are more than a few such subsections,
|
||||||
consider adding a table of contents just below the main section title.
|
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:
|
The general structure of the method documentation should be:
|
||||||
|
|
||||||
* Calling sequence (for methods written in C).
|
- Calling sequence (for methods written in C).
|
||||||
* Synopsis (short description).
|
- Synopsis (short description).
|
||||||
* Details and examples.
|
- Details and examples.
|
||||||
* Argument description (if necessary).
|
- Argument description (if necessary).
|
||||||
* Corner cases and exceptions.
|
- Corner cases and exceptions.
|
||||||
* Aliases.
|
- Aliases.
|
||||||
* Related methods (optional).
|
- 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 Ruby, \RDoc documents the calling sequence automatically.
|
||||||
|
|
||||||
For methods written in C, \RDoc cannot determine what arguments
|
For methods written in C, \RDoc cannot determine what arguments
|
||||||
the method accepts, so those need to be documented using \RDoc directive
|
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:
|
Example:
|
||||||
|
|
||||||
* call-seq:
|
```
|
||||||
* array.count -> integer
|
* call-seq:
|
||||||
* array.count(obj) -> integer
|
* array.count -> integer
|
||||||
* array.count {|element| ... } -> integer
|
* array.count(obj) -> integer
|
||||||
|
* array.count {|element| ... } -> integer
|
||||||
|
```
|
||||||
|
|
||||||
When creating the <tt>call-seq</tt>, use the form
|
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,
|
Omit the parentheses for cases where the method does not accept arguments,
|
||||||
and omit the block for cases where a block is not accepted.
|
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,
|
is omitted as when the argument is passed with the default value. For example,
|
||||||
use:
|
use:
|
||||||
|
|
||||||
* obj.respond_to?(symbol, include_all=false) -> true or false
|
```
|
||||||
|
obj.respond_to?(symbol, include_all=false) -> true or false
|
||||||
|
```
|
||||||
|
|
||||||
Instead of:
|
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
|
However, as shown above for <tt>Array#count</tt>, use separate lines if the
|
||||||
behavior is different if the argument is omitted.
|
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).
|
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+.
|
- Have `self`, not `receiver` or `array`.
|
||||||
- Begin with +new_+ if and only if the output object is a new instance
|
- 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+.
|
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
|
The synopsis comes next, and is a short description of what the
|
||||||
method does and why you would want to use it. Ideally, this
|
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:
|
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
|
This is great as it is short and descriptive. Avoid documenting
|
||||||
too much in the synopsis, stick to the most important information
|
too much in the synopsis, stick to the most important information
|
||||||
for the benefit of the reader.
|
for the benefit of the reader.
|
||||||
|
|
||||||
=== Details and Examples
|
### Details and Examples
|
||||||
|
|
||||||
Most non-trivial methods benefit from examples, as well as details
|
Most non-trivial methods benefit from examples, as well as details
|
||||||
beyond what is given in the synopsis. In the details and examples
|
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.
|
method handles improper arguments or corner cases.
|
||||||
|
|
||||||
Not every behavior of a method requires an example. If the method
|
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
|
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
|
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
|
showing that it returns `nil`. If the details mention that for a
|
||||||
certain argument type, an empty array is returned, you don't need
|
certain argument type, an empty array is returned, you don't need
|
||||||
to provide an example for that.
|
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
|
in the synopsis or details. The purpose of examples is not to prove
|
||||||
what the details are stating.
|
what the details are stating.
|
||||||
|
|
||||||
=== Argument Description (if necessary)
|
### Argument Description (if necessary)
|
||||||
|
|
||||||
For methods that require arguments, if not obvious and not explicitly
|
For methods that require arguments, if not obvious and not explicitly
|
||||||
mentioned in the details or implicitly shown in the examples, you can
|
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.
|
details, and not implicitly shown in the examples.
|
||||||
|
|
||||||
If there is more than one argument or block argument, use a
|
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
|
For corner cases of methods, such as atypical usage, briefly mention
|
||||||
the behavior, but do not provide any examples.
|
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
|
is passed. Do not provide examples of exceptions being raised unless
|
||||||
that is a common case, such as \Hash#fetch raising a \KeyError.
|
that is a common case, such as \Hash#fetch raising a \KeyError.
|
||||||
|
|
||||||
=== Aliases
|
### Aliases
|
||||||
|
|
||||||
Mention aliases in the form
|
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
|
In some cases, it is useful to document which methods are related to
|
||||||
the current method. For example, documentation for \Hash#[] might
|
the current method. For example, documentation for `Hash#[]` might
|
||||||
mention \Hash#fetch as a related method, and \Hash#merge might mention
|
mention `Hash#fetch` as a related method, and `Hash#merge` might mention
|
||||||
\Hash#merge! as a related method. Consider which methods may be related
|
`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,
|
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
|
at the end of the method documentation, add a line starting with
|
||||||
"Related: " (e.g. "Related: #fetch"). Don't list more than three
|
"Related: " (e.g. "Related: #fetch"). Don't list more than three
|
||||||
related methods. If you think more than three methods are related,
|
related methods. If you think more than three methods are related,
|
||||||
pick the three you think are most important and list those three.
|
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
|
For methods that accept multiple argument types, in some cases it can
|
||||||
be useful to document the different argument types separately. It's
|
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