Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Burlington Ruby: Contributing to Ruby

Burlington Ruby: Contributing to Ruby

Newcomer or seasoned veteran looking to get involved with Ruby documentation? We’ll show you it’s not as scary as it may seem, and there’s plenty of ways to help. It’s important to give back to the open source community and improve things for future developers.

This talk will teach you the value of open-source, the benefits of contributing, and a little bit about how ruby-core works. You will learn what to look for when spotting documentation bugs in the MRI source code. We will cover the guidelines to writing MRI documentation, and how to submit a patch. Including helpful tricks using ri and rdoc.


Zachary Scott

January 30, 2013

More Decks by Zachary Scott

Other Decks in Programming


  1. Contributing to Ruby

  2. Zachary Scott Ruby MRI Committer and Freelance Web Developer github.com/zzak

  3. Vermonter Family Hard work

  4. None
  5. None
  6. Open Source is good

  7. “Ask not what your code can do for you –

    ask what you can do for your code” – John F. Kennedy
  8. None
  9. It can be scary at first, we want you to

  10. What kind of developer are you?

  11. Have you submitted any patches before? What about ruby-core?

  12. The path to eternal gratification

  13. Millions of people use Open Source software every day.

  14. OSS is about freedom and community

  15. Human driven development

  16. The Bystander effect

  17. +1 As A Service

  18. Cynicism An attitude characterized by a general distrust of others'

    apparent motives or ambitions, or a general lack of faith or hope in individuals with desires, hopes, opinions, that a cynic perceives as unrealistic or inappropriate, therefore deserving of ridicule or admonishment.
  19. Assume Responsibility

  20. Bizarre and arcane projects

  21. Open source lets you read code and get feedback from

    some of the most gifted and experienced engineers in the industry.
  22. Don't be afraid to make mistakes

  23. Bad code is better than no code

  24. Employers want to see your code

  25. So why contribute to Ruby's documentation?

  26. Ruby gets a bad rap for poor docs

  27. “X is a ghetto” Ghetto implies neglected.

  28. Debating it doesn't resolve anything.

  29. MRI is only about 70% covered by documentation. Existing docs

    can be improved. Writing docs is a gentle introduction to open source.
  30. Documentation solidifies fundamentals and code reading skills.

  31. Where do I start?

  32. First you need to know ruby-core SOP That's short for

    standard operating procedure.
  33. MRI is developed on subversion

  34. bugs.ruby-lang.org Bug reports Feature requests Language discussion Backport requests

  35. Have you used redmine before?

  36. Assign doc reports or patches to me and use “DOC”

    category Bugs and features go to maintainer https://bugs.ruby-lang.org/projects/ruby/wiki/Maintainers Documentation counts as a bug
  37. Discussion takes place on ruby-core mailing list Issue tracker accompanies

    the mailing list Low signal to noise ratio
  38. Confused yet?

  39. Who doesn't use github? Apparently, ruby-core doesn't.

  40. Pull requests can be submitted to github Good luck with

    that, seriously.
  41. For anything but documentation, you should be using bugs.ruby-lang.org

  42. Enter the Ruby Documentation project

  43. We provide a fork of ruby on github Like docrails,

    without public write Low noise to signal ratio, very welcoming community.
  44. Any questions can be directed to the mailing list or

    IRC documenting.ruby@librelist.org and #ruby-core on freenode.net
  45. How else can I help?

  46. Try out new features Review open tickets Reproduce bug reports

    against trunk Write tests for new features https://bugs.ruby-lang.org/projects/ruby/wiki/HowToReport
  47. Most importantly... Test your app or library against trunk and

    latest preview releases. Many libraries can benefit from this.
  48. What do I need to get started?

  49. A github account and git installed http://github.com/ https://help.github.com/articles/set-up-git Subscribe to

    documenting.ruby@librelist.org http://librelist.com/help.html System ruby installed http://www.ruby-lang.org/en/downloads/
  50. Latest version of rdoc $ gem install rdoc –pre A

    fork of documenting-ruby https://github.com/documenting-ruby/ruby https://help.github.com/articles/fork-a-repo A copy of the MRI source $ git clone git://github.com/documenting-ruby/ruby.git
  51. Text editor of your choice “ .vimrc config for ruby-core

    indent C coding style au FileType c setl ts=8 sw=4 softtabstop=4 noexpandtab set autoindent
  52. More fantastic info on the wiki https://bugs.ruby-lang.org/projects/ruby/wiki/DeveloperHowto If you get

    stuck, don't hesitate to ask!
  53. “What's in a patch? That which we call a patch

    By any other name would merge as clean.” – William Shakespeare
  54. Use the latest code One kind of modification per patch

  55. Existing documentation needs polish typos, examples, grammar, style

  56. Writing new documentation Undocumented areas and examples of good documentation

    http://documenting-ruby.org/undocumented-areas.html Documenting new features Requires some research
  57. Let's learn the basics of RDoc

  58. Writing documentation for our imaginary ruby library. ## # Here

    we would put our class overview class Foo ## # Here we document a class method ::new def initialize(bar) # … do something with bar End end
  59. To generate the html now: $ rdoc -o tmp foo.rb

  60. Now for some RDoc markup http://rdoc.rubyforge.org/RDoc/Markup.html#label-RDoc+Markup+Reference

  61. === Headers * simple * lists [labeled] lists or definition

    lists [need] the label in square brackets you:: can also use two colons instead:: of brackets
  62. When you have individual words, you can wrap the word

    in the following: *'s for bold, _'s for emphasis or +'s for code
  63. If you have more than one word, you need to

    use the following: <b>'s for bold, <em>'s for emphasis, or <tt>'s for code
  64. Links single_word_label[url] {multi word label}[url] mailto:user@example.com

  65. Rules of thumb and putting it together http://bugs.ruby-lang.org/projects/ruby/wiki/DocumenterHowTo

  66. All top-level classes and modules should have an overview. Explain

    why you would want to use this library. Include small examples showing the major features of the library.
  67. Internal classes should contain an overview of the library of

    its specific use in the library. An example of this is IRB::XMP, which is an example printer that comes with irb.
  68. For implementation specific classes, providing documentation for future maintainers is

    acceptable. The :nodoc: directive can be used to hide this class from the generated developer documentation.
  69. RDoc will ignore private and protected methods when generating HTML

    documentation, however ri will include these. Be sure to document all methods, or mark them as :nodoc:
  70. For method arguments use the :arg: or :args: directives. Block

    parameters can be documented with the :yields: directive.
  71. :call-seq: is used throughout MRI documentation as the goto way

    to provide method description. ## # :call-seq: # some_method(string, separator, limit) → string some_method(str, sep, l)
  72. Using :call-seq: is a great way to provide more obvious

    parameter names. The new parameter names can be used within the documentation of the method and should be surrounded by +'s to allow rdoc to find undocumented method parameters.
  73. Avoid placing class names and method names in any markup,

    like +, <code> or <tt>. This allows rdoc to create cross-references between various pages of documentation.
  74. You can link to class methods within the same scope

    using the double-colon (::) prefix. ## # See also ::new
  75. In order to link to instance methods, you must use

    the # prefix. ## # Same as #gsub except substitution # occurs in place.
  76. When documenting C files, look for the :Document-class: directive. Also,

    rb_define_class and rb_define_method which are usually at the bottom will reference the C functions you should document.
  77. RDoc comes with a handful of directives for documenting C

    level classes, modules, methods, etc http://rdoc.rubyforge.org/RDoc/Parser/C.html
  78. So you're ready to generate the docs?

  79. $ rdoc -r -o tmp lib/mylib.rb lib/mylib/*

  80. $ ri -d tmp MyLib

  81. Ready to commit?

  82. First remove any generated files during testing $ rm -rf

    tmp documentation_coverage.txt
  83. Add the files you changed, commit and then push the

    changes to your fork: $ git add . $ git commit -m “add documentation for WHAT_YOU_CHANGED” $ git push
  84. Submit a pull request to the documenting-ruby fork. https://help.github.com/articles/using-pull-requests

  85. Here's a few helpful tricks

  86. Generate a coverage report for a specific module: $ rdoc

    -C lib/mylib.rb lib/mylib/*
  87. Hide an entire block from RDoc by using the :stopdoc:

    and :startdoc: directives. You can also use the “--” and “++” directives. ## # :startdoc: # This is parsed. # -- # FIXME: I will be ignored. # ++ # This will also get parsed. # :stopdoc: # Everything here on out will be ignored.
  88. You can link to headings inside of documentation by following

    the destination class or method name by an @ and the heading name. ## # See also RDOC::Markup@Links Will be a link and look something like this: “Links at RDoc::Markup”.
  89. Testing your RDoc from the command-line $ echo “some rdoc

    markup” | rdoc --pipe
  90. RDoc supports other markup types, such as markdown. It can

    use the file extension for the included file. Or you can specify the markup type inline: ## # :markup: markdown # Your markdown comments go here.. class MyClass # ...
  91. Thank you!