CONTRIBUTING.md 14.3 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 59 60
We collaborate via the FLO (Free/Libre/Open) site [git.snowdrift.coop] (running
GitLab CE). We also mirror on the popular but proprietary site [GitHub], but we
encourage everyone to use FLO tools, and so the instructions below assume
61
git.snowdrift.coop.
62

63 64 65 66 67
1. Locally clone the project from the main Snowdrift repo to your computer as
   described in the BUILD guide
2. Fork the project at git.snowdrift.coop
    * sign in or create an account on [git.snowdrift.coop](https://git.snowdrift.coop/users/sign_in)
    * go to the [project repository]
68
    * click the "Fork" link (toward the top of the page)
69
    * choose your account for the fork
70 71
    * 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")
72 73 74 75 76 77 78 79 80 81 82
3. Add your git.snowdrift.coop fork as a remote for your local clone
    * 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
      of your fork at git.snowdrift.coop
    * copy the address (which looks like
      `https://git.snowdrift.coop/YOURNAME/snowdrift.git` where `YOURNAME` is
      your git.snowdrift.coop username).
    * using the correct address, enter a modified version of this command in the
        directory of your local clone:
        `git remote add my-snow https://git.snowdrift.coop/YOURNAME/snowdrift.git`
83 84 85

#### Updating your local code to snowdrift master

86
Whenever you begin new work, you should first get the latest master code from
87
the Snowdrift project:
88

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

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

98
#### Starting a new branch
99

100
From the master branch, having pulled the latest updates, create a new branch:
101

102
    git checkout -b some-branch
103

104 105 106
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`.
107

108 109 110 111 112 113 114
#### 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.
115

116
#### Building your updates
117

118
To check your work and see the results on the running site, follow the
119
instructions in the [Build guide] for running the site.
120 121 122

#### Running the tests

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

125
    ./build.sh test
126 127 128 129

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.

130
#### Committing your changes
131 132

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

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

    git commit -a

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

145
#### Getting your changes merged
146

147
When you are ready to share your work (one or more commits all relevant to the
148 149 150
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.
Bryan's avatar
Bryan committed
151

Bryan's avatar
Bryan committed
152
Next, send your changes to your git.snowdrift.coop account with:
153

154
    git push -u my-snow some-branch
155

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

Bryan's avatar
Bryan committed
158
To notify the snowdrift team about your work, visit the git.snowdrift.coop page
159 160 161 162
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.
163

164 165
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).
166 167 168

## Choosing what to work on

169
Several ways to get started contributing and/or to learn more overall:
170

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

174 175 176 177
* 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.
178

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

Aaron Wolf's avatar
Aaron Wolf committed
181 182 183 184 185 186
    * 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.
187
        * For CSS, we use [Sass]
Aaron Wolf's avatar
Aaron Wolf committed
188

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

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

* 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

204
We have a separate [design] repo for design tasks, our design guide and so on.
205 206 207

### Code style

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

211
* Sentence-case, 50-column Git commit headers (but no ending period)
212 213 214 215 216 217 218 219 220 221 222 223 224
    * 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's avatar
Bryan committed
225
* Imports should be grouped into three paragraphs: "Prelude" or "Import" for
226 227
  those modules that need them, then external modules, and then internal
  modules.
228

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

231 232 233 234
    ```
    stack install hlint
    hlint -XQuasiQuotes -XTemplateHaskell $FILE
    ```
235

236 237
### Code review

238 239
As a best practice, we want adequate code review for every merge before it goes
into the master code.
240

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

### Use of JavaScript

248 249 250
**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's avatar
Bryan committed
251
[Unobtrusive JavaScript]. Use of NoScript should never cause a broken
252
experience. All our JavaScript should be recognized by the FSF's [LibreJS plugin].
253

254 255 256 257
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.
258 259 260 261

## Learning resources and helpful tools

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

264 265 266
*   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!
267

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

285 286
*   Git resources:

287
    * [Git for Ages 4 and Up](https://www.youtube.com/watch?v=1ffBJ4sVUb4&ab)
288 289 290 291 292
      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.

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

296
    * The [Git Docs](https://git-scm.com/doc/) page includes many links, an
297 298 299 300
      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.

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

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

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

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

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

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