Thinking about contributing to Decko?

Nice! There’s tons to do involving lots of different skillsets, and we welcome the help. We want to make contributing to Decko as rewarding an experience as possible. Please jump in, and ask away for help.

For starters, it’s helpful to be clear whether you’re interested in helping as a Shark, a Monkey, or a Platypus. (Or as more than one of these!)

Sharks - Masters of Cards

Decko is built around the card concept, so we call advanced users who create, structure, organize, and maintain Decko websites “Card Sharks.” There are many things Sharks can do to contribute to the project: design, community support, documentation, outreach, or even just the occasional kind word.

Because Sharks live not in the land of code but in the sea of websites, we maintain information that pertains to them – including installation troubleshooting, mod lists, and deck configuration – on Decko.org.

Sharks are invited to:

Monkeys - Makers of Mods

Mods (short for modules, modifications, modicum, whatever…) are the main mechanism for extending Decko behavior, and they’re the ideal place for coders new to Decko to start contributing. As Monkeys!

There are endless possibilities for mods, and many much-needed mods can be built as relatively minor variations of existing mods.

In addition to the Shark invitations above, Monkeys are invited to:

Platypuses - Weirdos Building the Platform

The rest of this document is for the more traditional audience of CONTRIBUTING files: folks who want to help develop the code in this repository, which we often call the core.

Pull Requests

The Decko team makes heavy use of GitHub’s pull request system. If you’re not familiar with pull requests, that’s the best place to start.

A great pull request is: * small - so the team can review changes incrementally * tested - including automatic tests that would fail without its changes * explained - with a clear title and comments

Development Environment

First, you will need a copy of the decko repo:

git clone --recurse-submodules git@github.com:decko-commons/decko.git

Then you will need to install a platypus deck (somewhere else – not inside the repo):

decko new MY_DECK --platypus

The --platypus flag will make several key configuration alterations for you and make it easy to run tests from the repo.

You will be prompted to give the path to your repo. Alternatively you can use the --repo-path flag or a DECKO_REPO_PATH environmental variable.

Testing

There are three different types of core tests. Unit tests are in rspec, integration/end-to-end tests exists as cucumber features and cypress tests.

Rspec

To run the whole rspec test suite execute bundle exec decko rspec in your platypus deck directory. If you want to run only a single spec file use bundle exec decko rspec -- <path_to_spec_file>. For more options run bundle exec decko rspec --help.

Cypress

Start the server for your platypus deck with RAILS_ENV=cypress bundle exec decko s -p 5002 and then in the gem in decko/spec run yarn run cypress open to open the cypress interface. Cypress upgrades can be installed in that same directory via npm.

JavaScript changes

If you made JavaScript/CoffeeScript changes, you have to update the test fixtures with

RAILS_ENV=test rake card:seed:update

and commit the updated file.js and yml files.

Documentation

We use yard. You can run your own documentation server by calling this from the repo root:

yard server --reload

By default, the yard server will detect changes to normal ruby modules and update the docs accordingly. But currently set modules only work if we regenerate tmpfiles after changing code. To do that you can run the following from the development deck root:

rake decko:docs:update

BUT: only do this if you’re both (a) in development mode and (b) using a decko gem from within a copy of the repo.

A few notes on yard documentation:

  • It’s important to document classes and modules only once. If, for example, class Card is preceeded by a comment in multiple files, only one will be used, which often means the intended documentation may get overridden.
  • If comments are broken by uncommented lines, the comments before or after the break (depending on context) may be lost.
  • It’s always great to check yardoc links in comments after refactoring to make sure the changes didn’t break them.