diff options
Diffstat (limited to 'doc/contributing')
| -rw-r--r-- | doc/contributing/building_ruby.md | 227 | ||||
| -rw-r--r-- | doc/contributing/documentation_guide.md | 505 | ||||
| -rw-r--r-- | doc/contributing/glossary.md | 41 | ||||
| -rw-r--r-- | doc/contributing/making_changes_to_ruby.md | 28 | ||||
| -rw-r--r-- | doc/contributing/making_changes_to_stdlibs.md | 49 | ||||
| -rw-r--r-- | doc/contributing/reporting_issues.md | 91 | ||||
| -rw-r--r-- | doc/contributing/testing_ruby.md | 156 |
7 files changed, 1097 insertions, 0 deletions
diff --git a/doc/contributing/building_ruby.md b/doc/contributing/building_ruby.md new file mode 100644 index 0000000000..96cee40cb4 --- /dev/null +++ b/doc/contributing/building_ruby.md @@ -0,0 +1,227 @@ +# Building Ruby + +## Dependencies + +1. Install the prerequisite dependencies for building the CRuby interpreter: + + * C compiler + + For RubyGems, you will also need: + + * OpenSSL 1.1.x or 3.0.x / LibreSSL + * libyaml 0.1.7 or later + * zlib + + If you want to build from the git repository, you will also need: + + * autoconf - 2.67 or later + * gperf - 3.1 or later + * Usually unneeded; only if you edit some source files using gperf + * ruby - 3.0 or later + * We can upgrade this version to system ruby version of the latest Ubuntu LTS. + +2. Install optional, recommended dependencies: + + * libffi (to build fiddle) + * gmp (if you with to accelerate Bignum operations) + * libexecinfo (FreeBSD) + * rustc - 1.58.0 or later, if you wish to build + [YJIT](https://docs.ruby-lang.org/en/master/RubyVM/YJIT.html). + + If you installed the libraries needed for extensions (openssl, readline, libyaml, zlib) into other than the OS default place, + typically using Homebrew on macOS, add `--with-EXTLIB-dir` options to `CONFIGURE_ARGS` environment variable. + + ``` shell + export CONFIGURE_ARGS="" + for ext in openssl readline libyaml zlib; do + CONFIGURE_ARGS="${CONFIGURE_ARGS} --with-$ext-dir=$(brew --prefix $ext)" + done + ``` + +## Quick start guide + +1. Download ruby source code: + + Select one of the below. + + 1. Build from the tarball: + + Download the latest tarball from [ruby-lang.org](https://www.ruby-lang.org/en/downloads/) and + extract it. Example for Ruby 3.0.2: + + ``` shell + tar -xzf ruby-3.0.2.tar.gz + cd ruby-3.0.2 + ``` + + 2. Build from the git repository: + + Checkout the CRuby source code: + + ``` shell + git clone https://github.com/ruby/ruby.git + cd ruby + ``` + + Generate the configure file: + + ``` shell + ./autogen.sh + ``` + +2. Create a `build` directory separate from the source directory: + + ``` shell + mkdir build && cd build + ``` + + While it's not necessary to build in a separate directory, it's good practice to do so. + +3. We'll install Ruby in `~/.rubies/ruby-master`, so create the directory: + + ``` shell + mkdir ~/.rubies + ``` + +4. Run configure: + + ``` shell + ../configure --prefix="${HOME}/.rubies/ruby-master" + ``` + + - Also `-C` (or `--config-cache`) would reduce time to configure from the next time. + +5. Build Ruby: + + ``` shell + make + ``` + +6. [Run tests](testing_ruby.md) to confirm your build succeeded. + +7. Install Ruby: + + ``` shell + make install + ``` + + - If you need to run `make install` with `sudo` and want to avoid document generation with different permissions, you can use + `make SUDO=sudo install`. + +### Unexplainable Build Errors + +If you are having unexplainable build errors, after saving all your work, try running `git clean -xfd` in the source root to remove all git ignored local files. If you are working from a source directory that's been updated several times, you may have temporary build artifacts from previous releases which can cause build failures. + +## Building on Windows + +The documentation for building on Windows can be found [here](../windows.md). + +## 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 + +In GNU make and BSD make implementations, to run a specific make script in parallel, pass the flag `-j<number of processes>`. For instance, +to run tests on 8 processes, use: + +``` shell +make test-all -j8 +``` + +We can also set `MAKEFLAGS` to run _all_ `make` commands in parallel. + +Having 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)" +``` + +### 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: + +``` shell +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-ruby`: Runs `test.rb` using Ruby in lldb +* `make gdb-ruby`: Runs `test.rb` using Ruby in gdb + +### Compiling for Debugging + +You should configure Ruby without optimization and other flags that may interfere with debugging: + +``` shell +./configure --enable-debug-env optflags="-O0 -fno-omit-frame-pointer" +``` + +### Building with Address Sanitizer + +Using the address sanitizer (ASAN) is a great way to detect memory issues. It can detect memory safety issues in Ruby itself, and also in any C extensions compiled with and loaded into a Ruby compiled with ASAN. + +``` shell +./autogen.sh +mkdir build && cd build +../configure CC=clang cflags="-fsanitize=address -fno-omit-frame-pointer -DUSE_MN_THREADS=0" # and any other options you might like +make +``` +The compiled Ruby will now automatically crash with a report and a backtrace if ASAN detects a memory safety issue. To run Ruby's test suite under ASAN, issue the following command. Note that this will take quite a long time (over two hours on my laptop); the `RUBY_TEST_TIMEOUT_SCALE` and `SYNTAX_SUGEST_TIMEOUT` variables are required to make sure tests don't spuriously fail with timeouts when in fact they're just slow. + +``` shell +RUBY_TEST_TIMEOUT_SCALE=5 SYNTAX_SUGGEST_TIMEOUT=600 make check +``` + +Please note, however, the following caveats! + +* ASAN will not work properly on any currently released version of Ruby; the necessary support is currently only present on Ruby's master branch (and the whole test suite passes only as of commit [9d0a5148ae062a0481a4a18fbeb9cfd01dc10428](https://bugs.ruby-lang.org/projects/ruby-master/repository/git/revisions/9d0a5148ae062a0481a4a18fbeb9cfd01dc10428)) +* Due to [this bug](https://bugs.ruby-lang.org/issues/20243), Clang generates code for threadlocal variables which doesn't work with M:N threading. Thus, it's necessary to disable M:N threading support at build time for now (with the `-DUSE_MN_THREADS=0` configure argument). +* Currently, ASAN will only work correctly when using a recent head build of LLVM/Clang - it requires [this bugfix](https://github.com/llvm/llvm-project/pull/75290) related to multithreaded `fork`, which is not yet in any released version. See [here](https://llvm.org/docs/CMake.html) for instructions on how to build LLVM/Clang from source (note you will need at least the `clang` and `compiler-rt` projects enabled). Then, you will need to replace `CC=clang` in the instructions with an explicit path to your built Clang binary. +* ASAN has only been tested so far with Clang on Linux. It may or may not work with other compilers or on other platforms - please file an issue on [https://bugs.ruby-lang.org](https://bugs.ruby-lang.org) if you run into problems with such configurations (or, to report that they actually work properly!) +* In particular, although I have not yet tried it, I have reason to believe ASAN will _not_ work properly on macOS yet - the fix for the multithreaded fork issue was actually reverted for macOS (see [here](https://github.com/llvm/llvm-project/commit/2a03854e4ce9bb1bcd79a211063bc63c4657f92c)). Please open an issue on [https://bugs.ruby-lang.org](https://bugs.ruby-lang.org) if this is a problem for you. + +## How to measure coverage of C and Ruby code + +You need to be able to use gcc (gcov) and lcov visualizer. + +``` shell +./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 diff --git a/doc/contributing/documentation_guide.md b/doc/contributing/documentation_guide.md new file mode 100644 index 0000000000..59953d0d52 --- /dev/null +++ b/doc/contributing/documentation_guide.md @@ -0,0 +1,505 @@ +# Documentation Guide + +This guide discusses recommendations for documenting +classes, modules, and methods +in the Ruby core and in the Ruby standard library. + +## Generating documentation + +Most Ruby documentation lives in the source files and is written in +[RDoc format](rdoc-ref:RDoc::Markup). + +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: + +```sh +make html +``` + +If you don't have a build directory, follow the [quick start +guide](building_ruby.md#label-Quick+start+guide) up to step 4. + +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 information in the shortest time. +The reader should be able to quickly understand the usefulness +of the subject code and how to use it. + +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 + +- 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 + [headings](rdoc-ref:RDoc::MarkupReference@Headings). +- Refer to authoritative and relevant sources using + [links](rdoc-ref:RDoc::MarkupReference@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::MarkupReference@Lists). + - Idioms and culture-specific references. + - Overuse of headings. + - 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. +(If you use other characters, the Ruby CI will gently let you know.) + +If want to put ASCII-incompatible characters into the documentation +for a C-coded class, module, or method, there are workarounds +involving new files `doc/*.rdoc`: + +- For class `Foo` (defined in file `foo.c`), + create file `doc/foo.rdoc`, declare `class Foo; end`, + and place the class documentation above that declaration: + + ```ruby + # Documentation for class Foo goes here. + class Foo; end + ``` + +- Similarly, for module `Bar` (defined in file `bar.c`, + create file `doc/bar.rdoc`, declare `module Bar; end`, + and place the module documentation above that declaration: + + ```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: + + - Retain the `call-seq` in the C code. + - Use file inclusion (`:include:`) to include text from an .rdoc file. + + Example: + + ``` + /* + * call-seq: + * each_byte {|byte| ... } -> self + * each_byte -> enumerator + * + * :include: doc/string/each_byte.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). + +### Output from `irb` + +For code examples, consider using interactive Ruby, +[irb](https://ruby-doc.org/stdlib/libdoc/irb/rdoc/IRB.html). + +For a code example that includes `irb` output, +consider aligning `# => ...` in successive lines. +Alignment may sometimes aid readability: + +```ruby +a = [1, 2, 3] #=> [1, 2, 3] +a.shuffle! #=> [2, 3, 1] +a #=> [2, 3, 1] +``` + +### Headings + +Organize a long discussion for a class or module with [headings](rdoc-ref:RDoc::MarkupReference@Headings). + +Do not use formal headings in the documentation for a method or constant. + +In the rare case where heading-like structures are needed +within the documentation for a method or constant, use +[bold text](rdoc-ref:RDoc::MarkupReference@Bold) +as pseudo-headings. + +### Blank Lines + +A blank line begins a new paragraph. + +A [code block](rdoc-ref:RDoc::MarkupReference@Code+Blocks) +or [list](rdoc-ref:RDoc::MarkupReference@Lists) +should be preceded by and followed by a blank line. +This is unnecessary for the HTML output, but helps in the `ri` output. + +### \Method Names + +For a method name in text: + +- For a method in the current class or module, + use a double-colon for a singleton method, + or a hash mark for an instance method: + <tt>::bar</tt>, <tt>#baz</tt>. +- Otherwise, include the class or module name + and use a dot for a singleton method, + or a hash mark for an instance method: + <tt>Foo.bar</tt>, <tt>Foo#baz</tt>. + +### Embedded Code and Commands + +Code or commands embedded in running text (i.e., not in a code block) +should marked up as +[monofont](rdoc-ref:RDoc::MarkupReference@Monofont). + +Code that is a simple string should include the quote marks. + +### Auto-Linking + +In general, \RDoc's auto-linking should not be suppressed. +For example, we should write `Array`, not `\Array`. + +However, suppress when the word in question: + +- Does not refer to a Ruby entity + (e.g., some uses of _Class_ or _English_). +- Refers to the current document + (e.g., _Array_ in the documentation for class `Array`); + in that case, the word should be forced to + [monofont](rdoc-ref:RDoc::MarkupReference@Monofont). + +Most often, the name of a class, module, or method +will be auto-linked: + +- Array. +- Enumerable. +- File.new +- File#read. + +If not, or if you suppress autolinking, consider forcing +[monofont](rdoc-ref:RDoc::MarkupReference@Monofont). + +### Explicit Links + +When writing an explicit link, follow these guidelines. + +#### +rdoc-ref+ Scheme + +Use the +rdoc-ref+ scheme for: + +- A link in core documentation to other core documentation. +- A link in core documentation to documentation in a standard library package. +- A link in a standard library package to other documentation in that same + standard library package. + +See section "+rdoc-ref+ Scheme" in {Links}[rdoc-ref:RDoc::MarkupReference@Links]. + +#### URL-Based Link + +Use a full URL-based link for: + +- A link in standard library documentation to documentation in the core. +- A link in standard library documentation to documentation in a different + standard library package. + +Doing so ensures that the link will valid even when the package documentation +is built independently (separately from the core documentation). + +The link should lead to a target in https://docs.ruby-lang.org/en/master/. + +Also use a full URL-based link for a link to an off-site document. + +### Variable Names + +The name of a variable (as specified in its call-seq) should be marked up as +[monofont](rdoc-ref:RDoc::MarkupReference@Monofont). + +Also, use monofont text for the name of a transient variable +(i.e., one defined and used only in the discussion, such as +n+). + +### HTML Tags + +In general, avoid using HTML tags (even in formats where it's allowed) +because `ri` (the Ruby Interactive reference tool) +may not render them properly. + +### Tables + +In particular, avoid building tables with HTML tags +(<tt><table></tt>, etc.). + +Alternatives: + +- A {verbatim text block}[rdoc-ref:RDoc::MarkupReference@Verbatim+Text+Blocks], + using spaces and punctuation to format the text; + note that {text markup}[rdoc-ref:RDoc::MarkupReference@Text+Markup] + will not be honored: + + - Example {source}[https://github.com/ruby/ruby/blob/34d802f32f00df1ac0220b62f72605827c16bad8/file.c#L6570-L6596]. + - Corresponding {output}[rdoc-ref:File@Read-2FWrite+Mode]. + +- (Markdown format only): A {Github Flavored Markdown (GFM) table}[https://github.github.com/gfm/#tables-extension-], + using special formatting for the text: + + - Example {source}[https://github.com/ruby/ruby/blob/34d802f32f00df1ac0220b62f72605827c16bad8/doc/contributing/glossary.md?plain=1]. + - Corresponding {output}[https://docs.ruby-lang.org/en/master/contributing/glossary_md.html]. + +## 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 + +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 + +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 + +The documentation for a class or module may include a "What's Here" section. + +Guidelines: + +- The section title is `What's Here`. +- Consider listing the parent class and any included modules; consider + [links](rdoc-ref:RDoc::MarkupReference@Links) + to their "What's Here" sections if those exist. +- All methods mentioned in the left-pane table of contents + should be listed (including any methods extended from another class). +- Attributes (which are not included in the TOC) may also be listed. +- Display methods as items in one or more bullet lists: + + - 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::MarkupReference@Links). + +- If there are numerous entries, consider grouping them into subsections with headings. +- If there are more than a few such subsections, + consider adding a table of contents just below the main section title. + +## Documenting Methods + +### 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. +- Related methods (optional). + +### 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::MarkupReference@Directives+for+Method+Documentation). + +For a singleton method, use the form: + +``` +class_name.method_name(method_args) {|block_args| ... } -> return_type +``` + +Example: + +``` +* call-seq: +* Hash.new(default_value = nil) -> new_hash +* Hash.new {|hash, key| ... } -> new_hash +``` + +For an instance method, use the form +(omitting any prefix, just as RDoc does for a Ruby-coded method): + +``` +method_name(method_args) {|block_args| ... } -> return_type +``` +For example, in Array, use: + +``` +* call-seq: +* count -> integer +* count(obj) -> integer +* count {|element| ... } -> integer +``` + +``` +* call-seq: +* <=> other -> -1, 0, 1, or nil +``` + +Arguments: + +- If the method does not accept arguments, omit the parentheses. +- If the method accepts optional arguments: + + - Separate each argument name and its default value with ` = ` + (equal-sign with surrounding spaces). + - If the method has the same behavior with either an omitted + or an explicit argument, use a `call-seq` with optional arguments. + For example, use: + + ``` + respond_to?(symbol, include_all = false) -> true or false + ``` + + - If the behavior is different with an omitted or an explicit argument, + use a `call-seq` with separate lines. + For example, in Enumerable, use: + + ``` + * max -> element + * max(n) -> array + ``` + +Block: + +- If the method does not accept a block, omit the block. +- If the method accepts a block, the `call-seq` should have `{|args| ... }`, + not `{|args| block }` or `{|args| code }`. + +Return types: + +- If the method can return multiple different types, + separate the types with "or" and, if necessary, commas. +- If the method can return multiple types, use +object+. +- If the method returns the receiver, use +self+. +- If the method returns an object of the same class, + prefix `new_` if an only if the object is not +self+; + example: `new_array`. + +Aliases: + +- Omit aliases from the `call-seq`, unless the alias is an + operator method. If listing both a regular method and an + operator method in the `call-seq`, explain in the details and + examples section when it is recommended to use the regular method + and when it is recommended to use the operator method. + +### 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 +is a single sentence, but for more complex methods it may require +an entire paragraph. + +For `Array#count`, the synopsis is: + +``` +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 + +Most non-trivial methods benefit from examples, as well as details +beyond what is given in the synopsis. In the details and examples +section, you can document how the method handles different types +of arguments, and provides examples on proper usage. In this +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 +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 +certain argument type, an empty array is returned, you don't need +to provide an example for that. + +Only add an example if it provides the user additional information, +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) + +For methods that require arguments, if not obvious and not explicitly +mentioned in the details or implicitly shown in the examples, you can +provide details about the types of arguments supported. When discussing +the types of arguments, use simple language even if less-precise, such +as "level must be an integer", not "level must be an Integer-convertible +object". The vast majority of use will be with the expected type, not an +argument that is explicitly convertible to the expected type, and +documenting the difference is not important. + +For methods that take blocks, it can be useful to document the type of +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::MarkupReference@Labeled+Lists). + +### Corner Cases and Exceptions + +For corner cases of methods, such as atypical usage, briefly mention +the behavior, but do not provide any examples. + +Only document exceptions raised if they are not obvious. For example, +if you have stated earlier than an argument type must be an integer, +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`. + +### 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 + 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, + list the three you think are most important. +- Consider adding: + + - A phrase suggesting how the related method is similar to, + or different from,the current method. + See an example at Time#getutc. + - Example code that illustrates the similarities and differences. + See examples at Time#ctime, Time#inspect, Time#to_s. + +### 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 +best to use a separate paragraph for each case you are discussing. diff --git a/doc/contributing/glossary.md b/doc/contributing/glossary.md new file mode 100644 index 0000000000..86c6671fbd --- /dev/null +++ b/doc/contributing/glossary.md @@ -0,0 +1,41 @@ +# Ruby Internals Glossary + +Just a list of acronyms I've run across in the Ruby source code and their meanings. + +| Term | Definition | +| --- | -----------| +| `BIN` | Basic Instruction Name. Used as a macro to reference the YARV instruction. Converts pop into YARVINSN_pop. | +| `bop` | Basic Operator. Relates to methods like `Integer` plus and minus which can be optimized as long as they haven't been redefined. | +| `cc` | Call Cache. An inline cache structure for the call site. Stored in the `cd` | +| `cd` | Call Data. A data structure that points at the `ci` and the `cc`. `iseq` objects points at the `cd`, and access call information and call caches via this structure | +| `cfp`| Control Frame Pointer. Represents a Ruby stack frame. Calling a method pushes a new frame (cfp), returning pops a frame. Points at the `pc`, `sp`, `ep`, and the corresponding `iseq`| +| `ci` | Call Information. Refers to an `rb_callinfo` struct. Contains call information about the call site, including number of parameters to be passed, whether it they are keyword arguments or not, etc. Used in conjunction with the `cc` and `cd`. | +| `cref` | Class reference. A structure pointing to the class reference where `klass_or_self`, visibility scope, and refinements are stored. It also stores a pointer to the next class in the hierarchy referenced by `rb_cref_struct * next`. The Class reference is lexically scoped. | +| CRuby | Implementation of Ruby written in C | +| `cvar` | Class Variable. Refers to a Ruby class variable like `@@foo` | +| `dvar` | Dynamic Variable. Used by the parser to refer to local variables that are defined outside of the current lexical scope. For example `def foo; bar = 1; -> { p bar }; end` the "bar" inside the block is a `dvar` | +| `ec` | Execution Context. The top level VM context, points at the current `cfp` | +| `ep` | Environment Pointer. Local variables, including method parameters are stored in the `ep` array. The `ep` is pointed to by the `cfp` | +| GC | Garbage Collector | +| `gvar` | Global Variable. Refers to a Ruby global variable like `$$`, etc | +| `ICLASS` | Internal Class. When a module is included, the target class gets a new superclass which is an instance of an `ICLASS`. The `ICLASS` represents the module in the inheritance chain. | +| `ifunc` | Internal FUNCtion. A block implemented in C. | +| `iseq` | Instruction Sequence. Usually "iseq" in the C code will refer to an `rb_iseq_t` object that holds a reference to the actual instruction sequences which are executed by the VM. The object also holds information about the code, like the method name associated with the code. | +| `insn` | Instruction. Refers to a YARV instruction. | +| `insns` | Instructions. Usually an array of YARV instructions. | +| `ivar` | Instance Variable. Refers to a Ruby instance variable like `@foo` | +| `imemo` | Internal Memo. A tagged struct whose memory is managed by Ruby's GC, but contains internal information and isn't meant to be exposed to Ruby programs. Contains various information depending on the type. See the `imemo_type` enum for different types. | +| JIT | Just In Time compiler | +| `lep` | Local Environment Pointer. An `ep` which is tagged `VM_ENV_FLAG_LOCAL`. Usually this is the `ep` of a method (rather than a block, whose `ep` isn't "local") | +| `local` | Local. Refers to a local variable. | +| `me` | Method Entry. Refers to an `rb_method_entry_t` struct, the internal representation of a Ruby method. +| MRI | Matz's Ruby Implementation | +| `pc` | Program Counter. Usually the instruction that will be executed _next_ by the VM. Pointed to by the `cfp` and incremented by the VM | +| `sp` | Stack Pointer. The top of the stack. The VM executes instructions in the `iseq` and instructions will push and pop values on the stack. The VM updates the `sp` on the `cfp` to point at the top of the stack| +| `svar` | Special Variable. Refers to special local variables like `$~` and `$_`. See the `getspecial` instruction in `insns.def` | +| `VALUE` | VALUE is a pointer to a ruby object from the Ruby C code. | +| VM | Virtual Machine. In MRI's case YARV (Yet Another Ruby VM) +| WB | Write Barrier. To do with GC write barriers | +| WC | Wild Card. As seen in instructions like `getlocal_WC_0`. It means this instruction takes a "wild card" for the parameter (in this case an index for a local) | +| YARV | Yet Another Ruby VM. The virtual machine that CRuby uses | +| ZOMBIE | A zombie object. An object that has a finalizer which hasn't been executed yet. The object has been collected, so is "dead", but the finalizer hasn't run yet so it's still somewhat alive. | diff --git a/doc/contributing/making_changes_to_ruby.md b/doc/contributing/making_changes_to_ruby.md new file mode 100644 index 0000000000..260fadb7e3 --- /dev/null +++ b/doc/contributing/making_changes_to_ruby.md @@ -0,0 +1,28 @@ +# 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. diff --git a/doc/contributing/making_changes_to_stdlibs.md b/doc/contributing/making_changes_to_stdlibs.md new file mode 100644 index 0000000000..3b33092fea --- /dev/null +++ b/doc/contributing/making_changes_to_stdlibs.md @@ -0,0 +1,49 @@ +# Making Changes 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). + +## Maintainers + +You can find the list of maintainers [here](https://docs.ruby-lang.org/en/master/maintainers_md.html#label-Maintainers). + +## Build + +First, install its dependencies using: + +``` +bundle install +``` + +### Libraries with C-extension + +If the library has a `/ext` directory, it has C files that you need to compile with: + +``` +bundle exec rake compile +``` + +## Running tests + +All standard libraries use [test-unit](https://github.com/test-unit/test-unit) as the test framework. + +To run all tests: + +``` +bundle exec rake test +``` + +To run a single test file: + +``` +bundle exec rake test TEST="test/test_foo.rb" +``` + +To run a single test case: + +``` +bundle exec rake test TEST="test/test_foo.rb" TESTOPS="--name=/test_mytest/" +``` diff --git a/doc/contributing/reporting_issues.md b/doc/contributing/reporting_issues.md new file mode 100644 index 0000000000..25516ffc6b --- /dev/null +++ b/doc/contributing/reporting_issues.md @@ -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)) diff --git a/doc/contributing/testing_ruby.md b/doc/contributing/testing_ruby.md new file mode 100644 index 0000000000..dfb7fb3a65 --- /dev/null +++ b/doc/contributing/testing_ruby.md @@ -0,0 +1,156 @@ +# 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 + ``` + + To run individual bootstrap tests, we can either specify a list of filenames or use the `--sets` flag in the variable `BTESTS`: + + ``` + make btest BTESTS="bootstraptest/test_fork.rb bootstraptest/tes_gc.rb" + make btest BTESTS="--sets=fork,gc" + ``` + + 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 + ``` + + To run a file or directory with GNU make, we can use: + + ``` + make test/ruby/test_foo.rb + make test/ruby/test_foo.rb TESTOPTS="-n /test_bar/" + ``` + +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 directory in this suite using the `TESTS` option, for example: + + ``` + make test-all TESTS=test/rubygems + ``` + + We can run a specific test file in this suite by also using the `TESTS` option, for example: + + ``` + make test-all TESTS=test/ruby/test_array.rb + ``` + + We can run a specific test in this suite using the `TESTS` option, 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=TestAlias#test_alias_with_zsuper_method" + ``` + + To run these specs with logs, we can use: + + ``` + make test-all TESTS=-v + ``` + + We can display the help of the `TESTS` option: + + ``` + make test-all TESTS=--help + ``` + + If we would like to run the `test/`, `bootstraptest/` and `spec/` test suites (the `spec/` is explained in a later section), 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 directory, we can use `SPECOPTS` to specify the directory: + + ``` + make test-spec SPECOPTS=spec/ruby/core/array + ``` + + To run a specific file, we can also use `SPECOPTS` to specify the file: + + ``` + make test-spec SPECOPTS=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 SPECOPTS="../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 SPECOPTS=-Vfs + ``` + + To run a ruby-spec file or directory with GNU make, we can use + + ``` + make spec/ruby/core/foo/bar_spec.rb + ``` + +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 + ``` + + To run a specific bundler spec file, we can use `BUNDLER_SPECS` as follows: + + ``` + make test-bundler BUNDLER_SPECS=commands/exec_spec.rb + ``` + +## Troubleshooting + +### Running test suites on s390x CPU Architecture + +If we see failing tests related to the zlib library on s390x CPU architecture, we can run the test suites with `DFLTCC=0` to pass: + +``` +DFLTCC=0 make check +``` + +The failures can happen with the zlib library applying the patch [madler/zlib#410](https://github.com/madler/zlib/pull/410) to enable the deflate algorithm producing a different compressed byte stream. We manage this issue at [[ruby-core:114942][Bug #19909]](https://bugs.ruby-lang.org/issues/19909). |