-
Notifications
You must be signed in to change notification settings - Fork 5
Contributor Documentation
This documentation is intended to provide contributors and potential contributors with information about the internals of Rambo. For a high-level explanation of what Rambo does and how to use it, please refer to the README. If you notice any discrepancies between the documentation and the actual structure or function of the app (either here or in the README), please fork the repo and make a pull request! This would be a great way for beginning contributors to get involved in an open source project.
Rambo is written in Ruby. It is packaged using Rubygems. Those who have not used Ruby before but have used other languages may be familiar with an analogous form of packaging, such as Python eggs. Documentation for the Ruby language is available at http://ruby-doc.org.
If you haven't used Ruby before, you will first need to install Ruby. I recommend using a version manager like RVM, rbenv, chruby, or ruby-build. Which one to use comes down to personal preference. Personally, I use RVM and may be able to provide some guidance as to how to install and use it if necessary. Be warned that installing Ruby version managing tools can be a bit of a pain, even for experienced developers, so you'll want to block out some time to do this.
Currently, Rambo supports Ruby versions 2.1.8 and newest. In our continuous integration builds, it is tested against versions 2.1.8, 2.2.2, and 2.3.0. (2.3.0 will be incremented in CI when a new version is released, so for example, when version 2.3.1 is released, CI will be configured to test 2.1.8, 2.2.2, and 2.3.1.) New contributors are encouraged to use the latest Ruby version in development, while being mindful of backwards compatibility, since the older versions will eventually be deprecated as new versions are released. The maintainers are happy to answer any questions you may have about versioning and compatibility.
For more information about continuous integration, please see below.
Rambo is packaged using Rubygems, and versioned using semantic versioning (often referred to as semver). In general, I will handle packaging and releases, so there is no need for contributors to worry about any of this. The exception would be if your contribution adds executable files. In general, please open an issue before doing this, since it would necessarily result in a significant change to the API. Beginning contributors in particular should work closely with maintainers on any such changes. We are here to help!
Rambo is tested using RSpec (for unit testing) and Cucumber for functional testing. If you haven't used these tools before, I recommend The RSpec Book and The Cucumber Book. The Rspec Book contains a lot of good information about both RSpec and Cucumber.
Any pull requests that change any Rambo API should be accompanied by passing unit tests in RSpec. Pull requests that change usage or output should include passing Cucumber features as well. When you make your pull request, Rambo's continuous integration will run your tests against the three most recent minor Ruby releases. If your tests don't pass, or your pull request causes existing tests to fail in any of these builds, changes will need to be made before the pull request is merged.
Rambo uses Travis CI to run tests automatically when changes are pushed to master. The tests also run against any pull requests before they will be merged. Travis runs tests against three Ruby versions, currently 2.1.8, 2.2.2, and 2.3.0. All builds are expected to pass before any changes will be merged to master. I am happy to answer any questions you may have about Travis or about continuous integration in general.
The easiest place to start contributing is with any changes you notice need to be made, no matter how small. Examples include:
- Corrections to spelling and grammar
- Updating documentation
- Refactoring app code
- Refactoring tests
- Changing the directory structure to be neater or more logical
- Updating dependencies
Additionally, you're encouraged to contribute any new features or API changes you'd like to see. Before doing so, please open an issue to make sure the change will be accepted and to get suggestions for implementation.
If you don't have specific ideas, please - please - look at the issue reports. I use Github issues extensively to track non-trivial issues that I cannot immediately take care of. Unless otherwise noted, contributions that resolve any of these issues - fully or partially - are much appreciated. Although most of the issues reported will require some work, I'll try to tag simpler issues with the beginners tag to give those just starting out an idea of which issues they can tackle. I'm available to help with any of the issues and encourage you to leave questions in the comments attached to the particular issue.
If you're an experienced developer, code reviews are also very helpful. I review pull requests from other contributors, but feedback on my own PRs is much appreciated. Additionally, I would often find pairing very helpful.
If you still can't think of what to contribute and would like to help out, please consider contributing to the JSON Test Data generator gem. That gem contains a lot of the business logic Rambo relies on to generate data for the tests it creates. The JSON Test Data gem also has open issues you can draw on for inspiration.
Rambo currently has two dependencies whose limited functionality is blocking its development:
I am a maintainer of both of these projects and am happy to discuss what kind of contributions would be most beneficial. Alternatively, I encourage you to take a look at the issue reports and see what's going on for yourself!
Before making your pull request, please fork the repo and make your changes on a logically named branch in the fork. You are welcome to make a pull request before your changes are finished if you would like help or feedback earlier in the process. As noted above, please file an issue before submitting any larger changes to make sure those changes are consistent with the overall direction of the project.
The bulk of Rambo's app code lives in the lib directory (although the main executable file is in bin). The spec directory mirrors the rest of the directory structure, so specs for lib code go in /spec/lib, and so on. Within the lib directory, major modules (such as Rambo::RSpec) have their own subdirectories.
Rambo is comprised of several classes, all namespaced under the Rambo module. These classes take care of Rambo's templating functions, which constitute a majority of the app. The biggest submodule is the Rambo::RSpec module, which lives in the /lib/rspec directory.