decko-docs/file.CONTRIBUTING.html at main · decko-commons/decko-docs · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>
  File: Contributing as a Shark, Monkey, or Platypus

    &mdash; Documentation by YARD 0.9.37

</title>

  <link rel="stylesheet" href="css/style.css" type="text/css" />

  <link rel="stylesheet" href="css/common.css" type="text/css" />

<script type="text/javascript">
  pathId = "CONTRIBUTING";
  relpath = '';
</script>


  <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>

  <script type="text/javascript" charset="utf-8" src="js/app.js"></script>


  </head>
  <body>
    <div class="nav_wrap">
      <iframe id="nav" src="file_list.html?1"></iframe>
      <div id="resizer"></div>
    </div>

    <div id="main" tabindex="-1">
      <div id="header">
        <div id="menu">

    <a href="_index.html">Index</a> &raquo;
    <span class="title">File: Contributing as a Shark, Monkey, or Platypus</span>

</div>

        <div id="search">

    <a class="full_list_link" id="class_list_link"
        href="class_list.html">

        <svg width="24" height="24">
          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
        </svg>
    </a>

</div>
        <div class="clear"></div>
      </div>

      <div id="content"><div id='filecontents'><h1 id="thinking-about-contributing-to-decko">Thinking about contributing to Decko?</h1>
<p>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.</p>

<p>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!)</p>

<h2 id="sharks---masters-of-cards">Sharks - Masters of Cards</h2>
<p>Decko is built around the <em>card</em> 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.</p>

<p>Because Sharks live not in the land of code but in the sea of websites, we
maintain information that pertains to them – <strong>including installation troubleshooting,
mod lists, and deck configuration</strong> – on <a href="https://decko.org">Decko.org</a>.</p>

<p>Sharks are invited to:</p>

<ul>
  <li>email the <a href="https://groups.google.com/g/decko-sharks">Decko Sharks Google Group</a></li>
  <li>add issues to <a href="https://github.com/decko-commons/decko/issues">GitHub’s Issue Tracker</a></li>
  <li>sign up and contribute at <a href="https://decko.org">Decko.org</a></li>
</ul>

<h2 id="monkeys---makers-of-mods">Monkeys - Makers of Mods</h2>
<p>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 <em>Monkeys</em>!</p>

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

<p>In addition to the Shark invitations above, Monkeys are invited to:</p>

<ul>
  <li>email the <a href="https://groups.google.com/g/decko-monkeys">Decko Monkeys Google Group</a></li>
  <li>make <a href="https://help.github.com/articles/using-pull-requests">pull requests</a> to the <a href="https://github.com/decko-commons/card-mods/">card-mods</a> repo.</li>
  <li>join us on Slack (just request an invite in the Google Group)</li>
</ul>

<h2 id="platypuses---weirdos-building-the-platform">Platypuses - Weirdos Building the Platform</h2>

<p>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 <em>core</em>.</p>

<h3 id="pull-requests">Pull Requests</h3>
<p>The Decko team makes heavy use of <a href="https://help.github.com/articles/using-pull-requests">GitHub’s pull request system</a>.
If you’re not familiar with pull requests, that’s the best place to start.</p>

<p>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</p>

<h3 id="development-environment">Development Environment</h3>

<p>First, you will need a copy of the decko repo:</p>

<pre class="code ruby"><code class="ruby">git clone --recurse-submodules [email protected]:decko-commons/decko.git
</code></pre>

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

<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_decko'>decko</span> <span class='id identifier rubyid_new'>new</span> <span class='const'>MY_DECK</span> <span class='op'>-</span><span class='op'>-</span><span class='id identifier rubyid_platypus'>platypus</span>
</code></pre>

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

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

<h3 id="testing">Testing</h3>
<p>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.</p>

<h4 id="rspec">Rspec</h4>
<p>To run the whole rspec test suite execute <code>bundle exec decko rspec</code> in your
platypus deck directory.
If you want to run only a single spec file use
<code>bundle exec decko rspec -- &lt;path_to_spec_file&gt;</code>.
For more options run <code>bundle exec decko rspec --help</code>.</p>

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

<h4 id="javascript-changes">JavaScript changes</h4>

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

<p><code>RAILS_ENV=test rake card:seed:update</code></p>

<p>and commit the updated <code>file.js</code> and yml files.</p>

<h3 id="documentation">Documentation</h3>

<p>We use <code>yard</code>. You can run your own documentation server by calling this from the repo
root:</p>

<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_yard'>yard</span> <span class='id identifier rubyid_server'>server</span> <span class='op'>-</span><span class='op'>-</span><span class='id identifier rubyid_reload'>reload</span>
</code></pre>

<p>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:</p>

<pre class="code ruby"><code class="ruby">rake decko:docs:update
</code></pre>

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

<p>A few notes on yard documentation:</p>

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

</div></div>

      <div id="footer">
  Generated on Tue Sep 16 17:44:20 2025 by
  <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
  0.9.37 (ruby-3.2.2).
</div>

    </div>
  </body>
</html>