diff options
author | eregon <eregon@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2017-05-07 12:04:49 +0000 |
---|---|---|
committer | eregon <eregon@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2017-05-07 12:04:49 +0000 |
commit | 95e8c48dd3348503a8c7db5d0498894a1b676395 (patch) | |
tree | 9eef7f720314ebaff56845a74e203770e62284e4 /spec/rubyspec/CONTRIBUTING.md | |
parent | ed7d803500de38186c74bce94d233e85ef51e503 (diff) | |
download | ruby-95e8c48dd3348503a8c7db5d0498894a1b676395.tar.gz |
Add in-tree mspec and ruby/spec
* For easier modifications of ruby/spec by MRI developers.
* .gitignore: track changes under spec.
* spec/mspec, spec/rubyspec: add in-tree mspec and ruby/spec.
These files can therefore be updated like any other file in MRI.
Instructions are provided in spec/README.
[Feature #13156] [ruby-core:79246]
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@58595 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'spec/rubyspec/CONTRIBUTING.md')
-rw-r--r-- | spec/rubyspec/CONTRIBUTING.md | 64 |
1 files changed, 64 insertions, 0 deletions
diff --git a/spec/rubyspec/CONTRIBUTING.md b/spec/rubyspec/CONTRIBUTING.md new file mode 100644 index 0000000000..e675a61afa --- /dev/null +++ b/spec/rubyspec/CONTRIBUTING.md @@ -0,0 +1,64 @@ +Contributions are much appreciated. +Please open a pull request or add an issue to discuss what you intend to work on. +If the pull requests passes the CI and conforms to the existing style of specs, it will be merged. + +### File organization + +Spec are grouped in 5 separate top-level groups: + +* `command_line`: for the ruby executable command-line flags (`-v`, `-e`, etc) +* `language`: for the language keywords and syntax constructs (`if`, `def`, `A::B`, etc) +* `core`: for the core methods (`Fixnum#+`, `String#upcase`, no need to require anything) +* `library`: for the standard libraries methods (`CSV.new`, `YAML.parse`, need to require the stdlib) +* `optional/capi`: for functions available to the Ruby C-extension API + +The exact file for methods is decided by the `#owner` of a method, for instance for `#group_by`: +```ruby +> [].method(:group_by) +=> #<Method: Array(Enumerable)#group_by> +> [].method(:group_by).owner +=> Enumerable +``` +Which should therefore be specified in `core/enumerable/group_by_spec.rb`. + +### MkSpec - a tool to generate the spec structure + +If you want to create new specs, you should use `mkspec`, part of [MSpec](http://github.com/ruby/mspec). + + $ ../mspec/bin/mkspec -h + +#### Creating files for unspecified modules or classes + +For instance, to create specs for `forwardable`: + + $ ../mspec/bin/mkspec -b library -rforwardable -c Forwardable + +Specify `core` or `library` as the `base`. + +#### Finding unspecified core methods + +This is very easy, just run the command below in your `spec` directory. +`ruby` must be a recent version of MRI. + + $ ruby --disable-gem ../mspec/bin/mkspec + +You might also want to search for: + + it "needs to be reviewed for spec completeness" + +which indicates the file was generated but the method unspecified. + +### Guards + +Different guards are available as defined by mspec. +In general, the usage of guards should be minimized as possible. + +There are no guards to define implementation-specific behavior because +the Ruby Spec Suite defines common behavior and not implementation details. +Use the implementation test suite for these. + +If an implementation does not support some feature, simply tag the related specs as failing instead. + +### Style + +Do not leave any trailing space and respect the existing style. |