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.
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.