Contributing to RBCli is the same as most open source projects:
That’s all there is to it! We’ve also kept our acceptance criteria pretty simple, as you’ll see below. Feel free to submit a pull request even if you don’t meet it if you would like your code or feature to be reviewed first; we do want to be mindful of your time and will review submissions before they are polished.
To allow for easy deveopment, Rbcli has a development mode which allows a project to include rbcli from a local folder instead of the default gem path. To use it, add the following to your shell’s profile (typically ~/.bash_profile or ~/.profile):
export RBCLI_ENV='development'
export RBCLI_DEVPATH='/path/to/rbcli/lib/rbcli'
alias rbcli='/path/to/rbcli/exe/rbcli'
Please, and thanks. We all like to use different indentation levels and styles, and this will keep us consistent between editors.
For filetypes where tabs are not supported (such as YAML), please stick to using two (2) spaces.
For any modification that alters the way RBCli is used – we’re talking additional features, options, keyword changes, major behavioral changes, and the like – the documentation will need to be updated as well. You’ll be happy to know we designed it to make the process relatively painless.
RBCli’s documentation is essentially a collection of markdown files that have been compiled into a static site using MkDocs. If you already have python and pip on your system, you can install it by running:
pip install mkdocs mkdocs-material
You can find the source markdown files in the docs-src/docs folder, and the menu organization in docs-src/mkdocs.yml. To preview your changes on a live site, run:
mkdocs serve
Also, don’t forget to update the Quick Reference Guide in the README.md file (the main project one) with information about your changes.
Once you’ve completed your edits, run the makesite.sh command to build the actual HTML pages automatically in the docs folder, from where they will be served when live.
If a feature needs to be deprecated, RBCli has a built-in deprecation message feature. You can leverage it by calling the following code when a deprecated command is called:
Rbcli::DeprecationWarning.new deprecated_command, message, version_when_code_will_be_removed
So, for example:
Rbcli::DeprecationWarning.new 'Rbcli::Configurate.me--first_run', 'Please use `RBCli::Configurate.hooks` as the parent block instead.', '0.3.0'
will display the following message to the user, in red, any any time the application is run:
DEPRECATION WRNING: The feature `Rbcli::Configurate.me--post_hook` has been deprecated. Please use `RBCli::Configurate.hooks` as the parent block instead. This feature will be removed in version 0.3.0.
Additionally, it will place the same line in the logs using Rbcli.logger.warn if logging is enabled.
If a deprecation warning has been added, please remember to mention it in the pull request so that others can update it later.
To install this gem onto your local machine from source, run bundle exec rake install.
To release a new version, follow theese steps:
version.rbbundle exec rake install, which will update gemfile.lock with the correct version and all dependency changesdocs-src/makesite.sh, which re-compiles the documentation and pulls in the changelog and quick reference automaticallybundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.