CONTRIBUTING.md 14 KB
Newer Older
1
# Snowdrift Beginning Contributor's Guide
2

3 4
This guide is written to work for even novice programmers. Advanced readers may
adapt the instructions as they see fit.
5

6 7
## Get in touch!

8
Reading this guide is *not* a prerequisite to contacting us. Feel free to
9 10
connect and engage with real people in the community right away, if only to let
us know about your interest in contributing. See our [contact options].
11

12 13 14
## Licensing note

When you contribute patches to this repository, such as via a merge request, you
15 16 17 18
retain the copyright to your contributions. In doing so, you agree that the
patches are under under the same licenses we use (GNU AGPLv3+ for program code
and non-program text and graphics under CC BY-SA 4.0 International, as specified
in the [README]). Other compatible licensing can work with special notice.
19 20

## Prerequisites to contributing
21

22
* Decently powerful computer (probably less than 10 years old, ideally 4GB+ RAM)
23
* GNU/Linux, \*BSD, or macOS
24
    * We do not support Windows at this time. We suggest Windows users switch
25 26
      systems overall or use a virtual machine. If you really want to help test
      Snowdrift on Windows, our [Build guide] has some notes about that.
27
* Basic ability to use terminal command-line-interface (CLI)
28

29 30
## Installing

31
**Follow the [Build guide]** to get Snowdrift going on your computer.
32 33 34 35 36 37 38 39

## Working on the code

**All the following assumes you have done the initial clone and install
according to the instructions linked above.**

### Text-editors and settings

40 41 42
Any code-appropriate text-editor will work, but we recommend those with stronger
Haskell and Yesod support. See [TEXTEDITORS.md] for our specific recommendations
and settings.
43 44 45

### Working with Git

46
Recommended workflow:
47

48 49
* Keep local master synced to the upstream main project master
* Do all work on new branches
50
* Use separate branches for independent work
51
* Once branches have been published and merge-requests opened, please retain the
52
  full list of commits and only rebase when requested.
53

54 55
#### Basic Git setup for collaboration

56
The following covers the bare minimum process for those new to Git.
57

58
We collaborate on code using [GitLab]. We also mirror on the popular but proprietary site [GitHub] but do not use that regulary.
59

60 61
1. Locally clone the project from the main Snowdrift repo to your computer as
   described in the BUILD guide
62 63
2. Fork the project at GitLab.com
    * sign in or create an account on [GitLab.com](https://gitlab.com/users/sign_in)
64
    * go to the [project repository]
65
    * click the "Fork" link (toward the top of the page)
66
    * choose your account for the fork
67 68
    * you should end up at your fork (to check, see that the header at the top
      of the page has your account name followed by "/Snowdrift")
69
3. Add your GitLab fork as a remote for your local clone
70 71 72
    * While we recommend SSH, those not comfortable with the full [SSH setup]
      can use HTTPS instead.
    * For HTTPS, choose that instead of SSH from the dropdown menu on the page
73
      of your fork at GitLab
74
    * copy the address (which looks like
75 76
      `https://gitlab.com/YOURNAME/snowdrift.git` where `YOURNAME` is
      your GitLab username).
77 78
    * using the correct address, enter a modified version of this command in the
        directory of your local clone:
79
        `git remote add my-snow https://gitlab.com/YOURNAME/snowdrift.git`
80 81 82

#### Updating your local code to snowdrift master

83
Whenever you begin new work, you should first get the latest master code from
84
the Snowdrift project:
85

86
* In your local snowdrift project directory,
87 88 89
* assuming you have the main snowdrift code as your "origin" (verify with
  `git remote -v`),
* with the master branch checked out (`git checkout master`),
90 91 92
* run `git pull`

You should have no conflicts because this is the only situation where you
93
should ever change your local master. **Work should be done on other branches.**
94

95
#### Starting a new branch
96

97
From the master branch, having pulled the latest updates, create a new branch:
98

99
    git checkout -b some-branch
100

101 102 103
Replace `some-branch` with a short descriptive name (with hyphens, not spaces)
for your planned changes. For example, when fixing a problem in the header, a
good branch name could be `header-fix`.
104

105 106 107 108 109 110 111
#### Working on the code

On a working branch, you can make your edits/additions etc. to the code files.

To review the status and save important points in your progress, learn about the
staging process and commands like `git add`, `git status`, and `git diff`. See
the links at the end of this file for learning resources.
112

113
#### Building your updates
114

115
To check your work and see the results on the running site, follow the
116
instructions in the [Build guide] for running the site.
117 118 119

#### Running the tests

Iko's avatar
Iko committed
120
When you are happy with your work, it compiles, and looks right, run the tests:
121

122
    ./build.sh test
123 124 125 126

If there are any failures either when compiling or testing, and you don't know
how to fix the issue or don't understand the error, contact us for help.

127
#### Committing your changes
128 129

When your updates all compile, tests pass, and you are ready to submit to the
130
main Snowdrift project, *commit* your changes.
131

132 133
Though it isn't best practice, the simplest command for beginners to commit all
changes (though any *new* files need `git add` first) is:
134 135 136

    git commit -a

137
An editor will show asking you to summarize your changes. On the first line,
138
write a short commit title that will be meaningful to people skimming all the
139 140
commits in the future. Add any further comments about the work on additional
lines below the title. Then save and close the editor.
141

142
#### Getting your changes merged
143

144
When you are ready to share your work (one or more commits all relevant to the
145 146 147
same overall update), you have confirmed that everything works as intended, and
all tests pass, run `git status` to make sure no work is missing and all new
files were committed.
148

149
Next, send your changes to your GitLab account with:
150

151
    git push -u my-snow some-branch
152

153
Changing `some-branch` to the name of the branch where you made the commit(s).
154

155
To notify the snowdrift team about your work, visit the GitLab page
156 157 158 159
with your fork. You should see a button called **"Create Merge Request"**. Click
that to bring up a form where you can add further notes about your work
(especially useful if you are merging multiple commits). You may ignore "Assign
to", "Milestone", and "Labels" at this point.
160

161 162
After you submit the merge request, someone should comment on your submission
soon (hopefully within a few hours, maybe a day or two depending on timing).
163 164 165

## Choosing what to work on

166
Several ways to get started contributing and/or to learn more overall:
167

168 169
* See the "newcomer-friendly" tag in our [issues] and consider working on any
  item not already assigned to someone and with no "blocked" tag.
170

171 172 173 174
* Play around with the site locally. See if you can understand what does what.
  You may find bits that seem incomplete or confusing, and you can explore them
  and/or check with others about the status, such as whether the issue is known
  or tickets exist already.
175

176
* Explore the code files and see if you can figure out how things fit together.
177

Aaron Wolf's avatar
Aaron Wolf committed
178 179 180 181 182 183
    * For non-Haskell work:
        * The .hamlet files in the /website/templates directory are comparable
          to basic HTML using white-space to avoid the need for closing tags
          (plus some other logic that connects to the Haskell). For more
          details, see the documentation on [Shakespearean Templates].
        * Any .julius files are containers for JavaScript.
184
        * For CSS, we use [Sass]
Aaron Wolf's avatar
Aaron Wolf committed
185

186 187
    * For those familiar with Haskell, one starting option: explore our files
      and update any code that doesn't match our code style described below.
188

189
* Read the code documentation in this repo and related pages on our [wiki].
190 191 192 193 194 195 196 197 198 199 200

* Read on below and check out links to learn more about the overall ecosystem,
  our development practices, and the tools we use.

## Development guidelines and notes

Overall, we strive to follow universal standards, be fully accessible,
and avoid browser-specific code.

### Design considerations

201
We have a separate [design] repo for design tasks, our design guide and so on.
202 203 204

### Code style

205 206
We suggest using [brittany](https://hackage.haskell.org/package/brittany) as a
code formatter. Besides that, consider:
Bryan Richter's avatar
Bryan Richter committed
207

208
* Sentence-case, 50-column Git commit headers (but no ending period)
209 210 211 212 213 214 215 216 217 218 219 220 221
    * include bits like "fixes SD-#" as appropriate when fixing a ticket
    * consider adding extra comments below commit titles
* Haskell-standard camelCaseNames (not C-standard underscore_names)
* Group qualified imports separate from unqualified imports, like:

    ```
    import System.IO (hFlush, stdout, stderr)
    import System.Log.FastLogger (toLogStr, fromLogStr)
    import Yesod.Default.Config (withYamlEnvironment, DefaultEnv (..))
    import qualified Control.Exception.Lifted as Exception
    import qualified Data.ByteString.Char8 as Char8
    ```

Bryan Richter's avatar
Bryan Richter committed
222
* Imports should be grouped into three paragraphs: "Prelude" or "Import" for
223 224
  those modules that need them, then external modules, and then internal
  modules.
225

226
* Additionally, you can use hlint to get suggestions for improving code style:
Bryan Richter's avatar
Bryan Richter committed
227

228 229 230 231
    ```
    stack install hlint
    hlint -XQuasiQuotes -XTemplateHaskell $FILE
    ```
232

233 234
### Code review

235 236
As a best practice, we want adequate code review for every merge before it goes
into the master code.
237

238
To help with code review, please choose to *watch* the code repository at
239
[] (and perhaps also the [GitHub] mirror if you use GitHub).
240 241
Then, you can make general and in-line comments about new code as it is
committed and before it goes into the master repository.
242 243 244

### Use of JavaScript

245 246 247
**We generally build with *progressive enhancement* in mind.** The site should
work with just HTML/CSS along with Yesod/Haskell server-side functions. Given
that basis, we can add JavaScript as appropriate for enhancement, considering
Bryan Richter's avatar
Bryan Richter committed
248
[Unobtrusive JavaScript]. Use of NoScript should never cause a broken
249
experience. All our JavaScript should be recognized by the FSF's [LibreJS plugin].
250

251 252 253 254
Although we haven't used them as of May 2018, we have considered [GHCJS] and
[PureScript] as options for more Haskell-connected ways to generate JavaScript.
If contributors want to work with either of those, we would happily accept that.
[Yesod JavaScript Options] explains further about those or other possibilities.
255 256 257 258

## Learning resources and helpful tools

For deeper understanding of various elements in our development,
259
here are some resources (nearly all fully-FLO):
260

261 262 263
*   The following WikiBooks are fully FLO (Free/Libre/Open) and include links to
    further resources as well. As they are wikis, you can and should *improve*
    them yourself as you read!
264

265
    * [Haskell Wikibook](https://en.wikibooks.org/wiki/Haskell)
266 267 268
      — one of the few *featured* Wikibooks, the Haskell Wikibook is
      *exceptionally* high quality and among the best overall introductions to
      Haskell.
269
    * [A Quick Introduction to Unix](https://en.wikibooks.org/wiki/A_Quick_Introduction_to_Unix)
270
      is a practical overview of command-line and Unix basics.
271
    * [SQL Wikibook](https://en.wikibooks.org/wiki/Structured_Query_Language)
272
      is a good general overview
273
    * [Git Wikibook](https://en.wikibooks.org/wiki/Git)
274
      is an incomplete book but has some useful bits.
275
    * [HTML Wikibook](https://en.wikibooks.org/wiki/HyperText_Markup_Language)
276
      is a workable but dated intro (of course, countless HTML guides exist)
277
    * [CSS Wikibook](https://en.wikibooks.org/wiki/Cascading_Style_Sheets)
278
      is pretty thorough though needs updating.
279
    * [JavaScript Wikibook](https://en.wikibooks.org/wiki/JavaScript)
280 281
      is incomplete, but seems a decent intro.

282 283
*   Git resources:

284
    * [Git for Ages 4 and Up](https://www.youtube.com/watch?v=1ffBJ4sVUb4&ab)
285 286 287 288 289
      is an excellent video introduction to the core commands and concepts of
      Git. Consider making a new folder like `git-test` in your `Home` directory
      and following along with the commands in the video if you really want to
      accelerate your proficiency with Git.

290
    * [Git Magic](http://www-cs-students.stanford.edu/~blynn/gitmagic/)
291 292
      is a fully-FLO book written in a more narrative style.

293
    * The [Git Docs](https://git-scm.com/doc/) page includes many links, an
294 295 296 297
      online version of the core Git manuals, and the full Pro Git book which
      uses the CC-BY-NC-SA license, so it is shareable but not fully FLO,
      unfortunately.

298
*   [CanIUse.com](https://caniuse.com/) is a reference website to check that all
299 300 301
    web features you use are compatible with various browsers and standards.
    The CanIUse data is fully FLO under a CC-BY license.

302
*   [The Yesod Book](https://www.yesodweb.com/book/) is the primary resource
303 304
    for learning about Yesod, the web framework we use to develop Snowdrift.

305
*   The [School of Haskell](https://www.schoolofhaskell.com) includes
306 307 308
    basic and advanced topics including some Yesod sections.

*   At Stack Overflow (which uses FLO licensing for content), see tags for
309 310
    [yesod](https://stackoverflow.com/questions/tagged/yesod) and
    [haskell](https://stackoverflow.com/questions/tagged/yesod)
311
    (and, of course, other topics like HTML, CSS, Sass, Git, and so on)
312

313
*   Alongside #snowdrift on freenode.net IRC, check out #yesod , #haskell ,
314
    and #haskell-beginners (among many other relevant channels).
315

316
[Build guide]: BUILD.md
317
[contact options]: https://snowdrift.coop/contact
318 319
[design]: https://gitlab.com/snowdrift/design
[GitLab]: https://gitlab.com/snowdrift/snowdrift
320 321
[GHCJS]: https://github.com/ghcjs/ghcjs
[GitHub]: https://github.com/snowdriftcoop/snowdrift
322
[issues]: https://gitlab.com/snowdrift/snowdrift/issues?label_name%5B%5D=newcomer-friendly
323
[LibreJS plugin]: https://www.gnu.org/software/librejs/
324
[project repository]: https://gitlab.com/snowdrift/snowdrift
325 326
[PureScript]: http://www.purescript.org/
[README]: README.md
327
[Sass]: https://sass-lang.com
328
[Shakespearean Templates]: https://www.yesodweb.com/book/shakespearean-templates
329
[SSH setup]: https://gitlab.com/help/ssh/README
330
[TEXTEDITORS.md]: TEXTEDITORS.md
331
[Unobtrusive JavaScript]: https://en.wikipedia.org/wiki/Unobtrusive_JavaScript
332 333
[wiki]: https://wiki.snowdrift.coop/
[Yesod JavaScript Options]: https://github.com/yesodweb/yesod/wiki/JavaScript-Options