-
Notifications
You must be signed in to change notification settings - Fork 2.5k
New to Ruby?
Ruby's home page contains links to a variety of resources for those new to the language:
https://www.ruby-lang.org/documentation.
Active Merchant's maintainers also recommend The Odin Project as a resource for anyone learning Ruby.
There are multiple ways to install Ruby and manage Ruby versions on your machine. If you are new to Ruby, Active Merchant's maintainers recommend using asdf and following the process listed below under Setting up your environment with asdf.
For a list of other ways to install Ruby, including using third-party tools like rbenv, rvm, or RubyInstaller, see:
https://www.ruby-lang.org/en/downloads/
Contributions to Active Merchant should follow standard Ruby style. Ruby is a very flexible language that often provides more than one way to do things, but there are still many conventions the community has agreed upon that constitute standard Ruby style. For example, Class names should appear in camel case:
Class MyNewGateway
while all variable and method names should appear in snake case:
def my_important_method
end
You may use the existing Active Merchant codebase as a reference for writing standard Ruby style, but a more detailed reference for Ruby conventions is the community-supported Ruby Style Guide.
Active Merchant uses RuboCop to enforce formatting rules. Any submission to the Active Merchant library must pass all RuboCop tests. RuboCop tests run when you run the command bundle exec rake test:local, but you may also run rubocop directly by running bundle exec rake rubocop from your Active Merchant directory.
Note that Active Merchant currently requires Ruby version >= 2.5 and also specifies RuboCop version 0.60.x. Unfortunately, this version of rubocop has compatibility issues with Ruby 2.6+, so in order to successfully run rake rubocop Active Merchant's maintainers recommend using Ruby 2.5.7 in your Active Merchant development environment.
There are multiple ways to manage Ruby installation and versioning on your machine. This section provides a guide for using asdf. If you are already using a different tool for managing Ruby versions, like rbenv, then you should skip to the Forking Active Merchant section below.
First install asdf. On Mac, using Homebrew:
brew install asdf
or on Linux, clone the asdf repository into ~/.asdf and then checkout the most recent branch:
git clone https://github.com/asdf-vm/asdf.git ~/.asdf
cd ~/.asdf
git checkout "$(git describe --abbrev=0 --tags)"
Next, add asdf to your shell configuration file. On macOS Catalina or newer, add this line:
. /usr/local/opt/asdf/asdf.sh
...to the bottom of ~/.zshrc (notice the . and space at the beginning of the line). For macOS Mojave or earlier add the line to ./bash_profile.
If you are on Linux and used Git to install asdf, add this line to your shell configuration file (usually ~./bashrc):
. $HOME/.asdf/asdf.sh
(Don't forget to restart your Terminal so the above changes take effect.)
At this point you should be able to run asdf info and see output that includes your shell version, your asdf version, and the ASDF_DIR variable that contains the path to your asdf installation.
Note that adding asdf to your shell can vary depending on your system and where asdf is installed in your file tree. Please consult asdf's documentation for help troubleshooting your installation.
In addition to managing your Ruby installation with a tool like asdf or rbenv, you will need to establish a local copy of Active Merchant that will be synced to the Active Merchant repository through a fork. This allows you to make changes to Active Merchant on your machine without affecting the original project.
To do this, use the fork button on GitHub to fork Active Merchant.
Next, clone the fork you created onto your machine. Do this by navigating to the directory where you want the project to live and then running this command, replacing YOUR-GITHUB-USERNAME with your GitHub username:
git clone https://github.com/YOUR-GITHUB-USERNAME/active_merchant
Finally, set an upstream remote in order to sync your fork with the original Active Record repository. Do this by cd'ing into the directory where you cloned Active Merchant and running this command:
git remote add upstream https://github.com/activemerchant/active_merchant.git
At this point you should be able to run git remote -v in your Active Merchant directory and see the following output:
origin https://github.com/YOUR-GITHUB-USERNAME/active_merchant.git (fetch)
origin https://github.com/YOUR-GITHUB-USERNAME/active_merchant.git (push)
upstream https://github.com/activemerchant/active_merchant.git (fetch)
upstream https://github.com/activemerchant/active_merchant.git (push)
...showing that your upstream remote is the original Active Merchant repository.
A more detailed guide to forking and syncing repositories can be found here.
At this point you will be able to keep your local copy of Active Merchant up to date with the official project by running the following from your Active Merchant directory:
git checkout master
git pull upstream master
Please see the Contribution Guide for directions on submitting PRs to Active Merchant.
At this point you have established your local copy of Active Merchant. If you followed along with the Installing asdf section it is time to use asdf to install the preferred Ruby version for use with Active Merchant. If you are not using asdf, you need to use your preferred tool to install the version of Ruby you wish to use with Active Merchant (2.5.7 is recommended). If you are using Windows, the recommended tool is RubyInstaller.
First, in your home directory run:
asdf plugin add ruby
Next, tell asdf to look for .ruby-version files:
echo 'legacy_version_file = yes' >> ~/.asdfrc
Next, navigate to the directory where you cloned Active Merchant and run:
echo '2.5.7' > .ruby-version
This will create a hidden file called ruby-version in your Active Merchant project, which we just told asdf to look for when managing installations.
Finally, in the same directory where your copy of Active Merchant lives, run:
asdf install
asdf reshim
You should be able to verify that you have installed Ruby version 2.5.7 and are using it for your Active Merchant project by running asdf current in your Active Merchant directory and seeing ruby 2.5.7 in the output.
Congratulations! At this point you have a local copy of Active Merchant that is synced to the official repository, you have installed Ruby 2.5.7, and you have specified that 2.5.7 is the Ruby version you would like Active Merchant to use.
You can test that everything is set up properly by using bundler to install Active Merchant's dependencies and then running tests. To do this, navigate to your Active Merchant directory and run:
gem install bundler
bundle install
bundle exec rake test:local
This will run Active Merchant's unit tests as well as RuboCop. If everything is set up properly, you should see a successful run of tests. At this point you are ready to contribute to Active Merchant by following our contribution guide. If you intend to add a new gateway to Active Merchant, please visit our Gateway Contributing Wiki.