~hristoast/mousikofidi

ref: mousikofidi.info mousikofidi/site/devel.html -rw-r--r-- 7.9 KiB
d1c22b44Hristos N. Triantafillou Clean out old info, update config reference (#139) 11 days ago
                                                                                
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
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
<h1>
  Developer's Guide
</h1>

<p>
  The MousikóFídi developer's guide!
</p>

<div id="toc"></div>

<h2>Contributing</h2>

<p>
  All development should be done on the <code>dev</code> branch.  To contribute a patch to MousikóFídi:
</p>

<ol>
  <li>
    Fork the main repository, check out the <code>dev</code> branch.
  </li>
  <li>
    Create a branch named loosely after the work being done (e.g. <code>my-cool-feature</code>, but don't get too crazy)
  </li>
  <li>
    Make changes, run tests (see below for more information about creating and running tests)
    <ul>
      <li>
        Wiki content lives on <a href="https://git.sr.ht/%7Ehristoast/mousikofidi/tree/wiki">the <code>wiki</code> branch</a>.
      </li>
    </ul>
  </li>
  <li>
    Write tests as needed, run tests
  </li>
  <li>
    Commit your changes
  </li>
  <li>
    <a href="https://git.sr.ht/%7Ehristoast/mousikofidi/send-email">Send in your patch!</a>
  </li>
</ol>

<p>
  Subscribe and post to the MousikóFídi mailing list <a href="https://lists.sr.ht/%7Ehristoast/mousikofidi">here</a>, and you can hop onto the IRC channel from any instance's <a href="https://demo.mousikofidi.info/about"><code>/about</code> page</a> or by directly joining <code>#mousikofidi</code> on <code>irc.freenode.net</code>.
</p>

<h2>Setup</h2>

<p>
  To get set up for development, first install the required dependencies:
</p>

<pre><code>cd /path/to/mousikofidi
# Optionally use the --user flag if desired
pip3 install -r requirements.txt
pip3 install -r dev-requirements.txt</code></pre>

<p>
  Run the tests once just to be sure you're in a good spot:
</p>

<pre><code>cd /path/to/mousikofidi
make tests  # tests-quiet or tests-verbose are also available
</code></pre>

<p>
  Then hack away!  You can run the dev server like this:
</p>

<pre><code>make dev-server
</code></pre>

<p>
  This is of course useful when working on the codebase.
</p>

<h2>pre-commit hook</h2>

<p>
  The <a href="https://git.sr.ht/%7Ehristoast/mousikofidi/tree/3d9e1a3f0c32c7f731b00330e0a8b8c4ce696250/pre-commit.sh"><code>pre-commit.sh</code></a> script within this repo is meant to function as a pre-commit hook.
</p>

<p>
  It can be installed via <code>make githooks</code>, but this also happens automatically when <code>make dev-requirements</code> and <code>make test</code> (and variants) are ran.
</p>

<p>
  Installation can also be done by manually invoking the script:
</p>

<pre><code>/path/to/pre-commit.sh --install
</code></pre>

<p>
  Having this hook installed ensures that commits will not break tests and is essential for working with the MousikóFídi codebase.
</p>

<h2>Creating A New CSS Theme</h2>

<p>
  Adding a new CSS theme to MousikóFídi is a relatively simple process:
</p>

<ol>
  <li>
    Create the <code>.css</code> file that will represent your theme's styling in the <a href="https://git.sr.ht/~hristoast/mousikofidi/tree/0349b2c34108638fcaad79a445d4ae7df5eaf58c/mousikofidi/static/css"><code>mousikofidi/static/css</code></a> directory of the MousikóFídi code repository.  Give it a distinct name that represents the theme well.
  </li>
  <li>
    Then, add your theme to the <code>THEMES</code> dict <a href="https://git.sr.ht/~hristoast/mousikofidi/tree/0349b2c34108638fcaad79a445d4ae7df5eaf58c/mousikofidi/mousikofidi.py#L129-136">in the main MousikóFídi python file</a>.  Follow the format of the existing themes; give your theme's name and the path to the file minus the extension.
  </li>
</ol>

<h2>Creating A New Holiday Logo</h2>

<p>
  To add a new date-based "holiday" logo to MousikóFídi:
</p>

<ol>
  <li>
    Create the logo file and place it into the <a href="https://git.sr.ht/%7Ehristoast/mousikofidi/tree/d4ec0804c26a164123c17278d961796acc9abdad/mousikofidi/static"><code>mousikofidi/static</code></a> directory of the MousikóFídi code repository.  Give it a distinct name that represents the holiday or idea behind it well.  Whatever you want, really.
  </li>
  <li>
    Add the logo to the <code>LOGOS</code> dict <a href="https://git.sr.ht/%7Ehristoast/mousikofidi/tree/d4ec0804c26a164123c17278d961796acc9abdad/mousikofidi/mousikofidi.py#L44">in the main MousikóFídi python file</a>.
    <ul>
      <li>
        The format is: <code>"date conditional": "file-name.png"</code>
      </li>
      <li>
        The <code>date_conditional</code> can me a specific <code>month-day</code> string, such as <code>05-01</code>
      </li>
      <li>
        Or, it can be a specific day or month: <code>day:01</code>, <code>month:05</code>
      </li>
      <li>
        A full example: <code>"05-01": "file-name.png"</code>
      </li>
    </ul>
  </li>
</ol>

<h2>Tests</h2>

<p>
  Tests should accompany any new features or fixes as needed.
</p>

<p>
  Please always run tests before making a commit.
</p>

<h3>Style</h3>

<p>
  Python code should be formatted with <a href="https://black.readthedocs.io/en/stable/">Python Black</a>.  This is checked as part of the test process when any one of <code>make test</code>, <code>make test-quiet</code>, or <code>make test-verbose</code> are ran.
</p>

<p>
  Also available are the <code>make test-black</code>, <code>make test-black-quiet</code>, and <code>make test-black-verbose</code> targets.
</p>

<h3>Flake 8</h3>

<p>
  Also ran with tests are <a href="http://flake8.pycqa.org/en/latest/"><code>flake8</code></a> checks.  The <code>flake8</code> package is installed as part of the dev setup process above.
</p>

<p>
  Before tests can pass, a <code>~/.config/flake8</code> file must exist on your system and it must include <a href="https://git.sr.ht/%7Ehristoast/mousikofidi/tree/7b1d2b8eb0e3cf359e9f35c4659f1d210dac6376/.builds/debian.yml#L23">the below lines at minimum</a>:
</p>

<pre><code>[flake8]
ignore = E501, E402, W503
max-line-length = 160
</code></pre>

<h3>Pytest</h3>

<p>
  All tests for the Python code in MousikóFídi are driven by <a href="https://pytest.org/en/latest/"><code>pytest</code></a>.  The <code>pytest</code> package is installed as part of the dev setup process above.
</p>

<p>
  All tests against Python and HTML code are done here.
</p>

<h3>Javascript</h3>

<p>
  The MousikóFídi project aims to only use vanilla Javascript.
</p>

<p>
  Additionally, any Javascript code should have tests.  All Javascript tests are executed on the <a href="https://git.sr.ht/%7Ehristoast/mousikofidi/tree/dev/templates/test_js.html"><code>test_js.html</code></a> template, which is viewable at <a href="https://demo.mousikofidi.info/test-js">the <code>/test-js</code> route</a> on any instance (note, the tests only work if the <a href="https://git.sr.ht/~hristoast/mousikofidi/tree/0349b2c34108638fcaad79a445d4ae7df5eaf58c/mousikofidi/example"><code>example</code> dir</a> is found.)
</p>

<p>
  As of right now, there's no automated process for running these tests, so be sure to check whem when working with the Javascript portion of the codebase.
</p>

<h2>Publishing A Release</h2>

<p>
  A release artifact is published to PyPI via a sourcehut build when a git tag is pushed.  This is handled by the <a href="https://git.sr.ht/%7Ehristoast/mousikofidi/tree/dev/pypi-upload.sh"><code>pypi-upload.sh</code></a> script included in the base of the MousikóFídi code repo.
</p>

<p>
  Note that any tag containing the string <code>beta</code> will not be published.
</p>

<h2>Documentation Website</h2>

<p>
  The Documentation Website, <a href="https://mousikofidi.info/">https://mousikofidi.info/</a>, exists on the <a href="https://git.sr.ht/%7Ehristoast/mousikofidi/tree/mousikofidi.info"><code>mousikofidi.info</code> branch</a> and is automatically updated any time that branch is updated.
</p>

<p>
  Building requires <a href="https://soupault.neocities.org/">soupault</a> 2.0.0 or higher, simply switch to the <code>mousikofidi.info</code> branch and run <code>make</code> from the root of the repository. The built website will be placed into a directory called <code>build/</code>.
</p>

<p>
  Once you've built the site, you can run <code>make serve</code> to start a python-based simple HTTP server for viewing your local website.
</p>