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:
- email the Decko Sharks Google Group
- add issues to GitHub’s Issue Tracker
- sign up and contribute at Decko.org
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:
- email the Decko Monkeys Google Group
- make pull requests to the card-mods repo.
- join us on Slack (just request an invite in the Google Group)
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.
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
First, you will need a copy of the decko repo:
git clone --recurse-submodules firstname.lastname@example.org:decko-commons/decko.git
Then you will need to install a platypus deck (somewhere else – not inside the repo):
decko new MY_DECK --platypus
--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.
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.
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.
Similar to rspec run
bundle exec decko cucumber in your platypus deck directory.
Start the server for your platypus deck with
RAILS_ENV=cypress bundle exec decko s -p
5002 and then in the gem in
yarn run cypress open to open the
cypress interface. Cypress upgrades can be installed in that same directory via npm.
Some special configuration is required for Jasmine testing, which is currently very limited.
See the Jasmine README for more information.
yard. You can run your own documentation server by calling this from the repo
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:
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 Cardis 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.