CONTRIBUTING.md

Snowdrift Beginning Contributor's Guide

To contribute to Snowdrift, you don't have to be tech savvy. This guide is written to work for even novice programmers. Advanced readers may adapt the instructions as they see fit.

In this guide, we will cover pretty much all you need to do to get Snowdrift running locally and to start making and submitting updates.

Get in touch!

Our recommended approach to getting started includes asking questions, getting mentored, and otherwise having real human engagement with others in the community. Please don't hesitate to speak up, and don't worry about taking people's time. We always welcome questions. For efficiency, we will point you to resources or pair you with others.

Licensing note

When you contribute patches to this repository, such as via a merge request, you retain the copyright to your contributions. Of course, given unchanged license notices in your copy of the repository, you automatically release your work under the same licenses we use (GNU AGPLv3+ primarily with non-code text and graphics also under CC BY-SA 4.0 International, as specified in the README).

Prerequisites to contributing

To work with Snowdrift, you should have a reasonably new laptop or desktop computer system (less than 10 years old generally) and know how to open a terminal and enter commands.

Generally, everything works smoothly with GNU/Linux, *BSD systems, and OS X.

We do not support Windows at this time, so we suggest Windows users switch systems or run a virtual machine. We encourage Windows users to switch to a free/libre/open system anyway, but if you really want to help test Snowdrift on Windows, our Build guide has some notes about that.

Command-line beginner's basics

In general, when you see a list of commands to enter, we recommend entering them in one-at-a-time exactly as you see them. However, it should work to copy and paste a collection of commands all at once.

NB: in most cases, you must use Ctrl-Shift-V to paste into the terminal (for historic reasons, Ctrl-V does something else usually).

We also highly recommend use of tab-completion. See the wikibook "A Quick Introduction to Unix" in the resources at the end of this file for more command-line basics.

Installing

Follow the BUILD.md instructions to get Snowdrift going on your computer.

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

All systems should come with a code-appropriate text-editor (or two), e.g. Gedit, Kate, Pluma, Scratch, etc. Any of those will work for now, but we recommend installing an editor with stronger Haskell and Yesod support. See TEXTEDITORS.md for our specific recommendations and settings.

Working with Git

Short version for experienced Git users:

We suggest keeping your local master matched to the main project master. Work only on other git branches. Use as many branches as needed to separate all work that functions independently (and avoid clutter by deleting branches once no longer needed).

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

Basic Git setup for collaboration

Forking at the host platform

We collaborate on the code via the FLO (Free/Libre/Open) site git.gnu.io. We also mirror on the popular but proprietary site GitHub, which you may use if you already have an account there. As we encourage everyone to use FLO tools, the instructions below assume git.gnu.io.

To contribute changes to the project, first create an account on git.gnu.io (or sign in if you already have an account).

Once signed in, go to https://git.gnu.io/snowdrift/snowdrift, and click the "Fork" link on the top right.

After choosing your account for the fork, you should be at the page for your fork of the project. To check, see that the header at the top of the page has has your account name followed by "/Snowdrift".

Adding your fork as a remote

At the top of the main page, below the header, you'll see a box with an address. By default, the SSH option is selected, and we recommend SSH ideally. However, SSH setup is kind of tricky, especially for those new to SSH. To stick with the easier option for now, click "HTTPS" and use that address which will look like: "https://git.gnu.io/YOURNAME/snowdrift.git"

Where YOURNAME is your git.gnu.io username.

Copy that address to your clipboard.

In your snowdrift directory, paste the address into your terminal as part of the following command:

git remote add my-snow https://git.gnu.io/YOURNAME/snowdrift.git

If you have not used Git before, run these additional Git setup commands, replacing YOUR NAME and YOUR EMAIL with your actual name and email.

git config --global user.name "YOUR NAME"
git config --global user.email "YOUR EMAIL"

Optional: specify a particular text editor for commit messages (replace nano with the command for whatever editor you prefer):

git config --global core.editor "nano"

Updating your local code to snowdrift master

Whenever you begin new work, you should first get the latest master code from the Snowdrift project.

The following assumes you originally cloned the code from one of our main hosts (as described in the BUILD guide), so you will have the main snowdrift code as your "origin" (verify this with git remote -v).

To download the latest updates of the snowdrift code:

• Go to your snowdrift directory, if not there already
• if not already on your master branch, run git checkout master
• run git pull

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

Starting a new branch

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

git checkout -b some-branch

Replace some-branch with a one- or two-word (with hyphens, not spaces) description of your planned changes. For example, when fixing a problem in the header, a good branch name would be header-fix.

Now, you can edit files, save work as you go, etc.

Building your updates

To check your work and see the results on the running site, follow the instructions in the BUILD.md guide for running the site.

Running the tests

When you are happy with your worki, it compiles, and looks right, run the tests:

stack build && stack test --pedantic

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.

Committing your changes

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

If you are new to Git, we urge you to learn about the process of staging with git add before committing and about review tools like git status and git diff. See the links at the end of this file for learning resources.

For now, though it isn't best practice, you can quickly commit all your changes with the command:

git commit -a

An editor will show asking you to summarize your changes. For the first line, write a short commit title that will be meaningful to people skimming all the commits in the future. If you want to add further comments about the work, do that on additional lines below the title. Then save and close the editor.

Getting your changes merged

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

Next, send your changes to your git.gnu.io account with:

git push -u my-snow some_branch

Change some_branch to the name of the branch where you made the commit(s).

NB: if you make additional changes to the same branch before a maintainer merges it into master, you can push those new updates with just git push.

To notify the snowdrift team about your work, visit the git.gnu.io page with your fork. You should see a button "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.

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

Choosing what to work on

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

• Visit the tickets and filter to the "newbie-friendly" tag and see what looks interesting and/or doable. Consider exploring other tickets based on your skills or interests. If you decide to work on a specific ticket, you can "claim" it once you have logged into the main site with a fully-established user.

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

• Explore the code files and see if you can figure out what does what and how things fit together.

  • For non-Haskell work, the files in the /templates directory are comparable to basic HTML, CSS, and JavaScript. Beginners can quickly learn how to make changes to those files. Basically, Hamlet=HTML and Cassius=CSS but with concise syntax that uses indentation instead of closing tags. Julius files are effectively just containers for JavaScript. For more details, see the documentation on Shakespearean Templates.

  • For those familiar with Haskell, consider exploring our files, and updating any code that doesn't match our code style.

• Read our coding wiki page, the related discussion board, and other pages throughout the Snowdrift.coop site.

• 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

We have separate wiki and discussion pages on the site for our specific design guide and general design-related issues.

Code style

When making edits, follow our code style guide.

Use of JavaScript

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 Unobtrusive JavaScript. Use of NoScript should never cause a broken experience. All our JavaScript should be recognized by the FSF's LibreJS plugin.

Although we haven't used them as of January 2016, 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.

Learning resources and helpful tools

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

• 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!

  • Haskell Wikibook — one of the few featured Wikibooks, the Haskell Wikibook is exceptionally high quality and among the best overall introductions to Haskell.
  • A Quick Introduction to Unix is a practical overview of command-line and Unix basics.
  • SQL Wikibook is a good general overview
  • Git Wikibook is an incomplete book but has some useful bits.
  • HTML Wikibook is a workable but dated intro (of course, countless HTML guides exist)
  • CSS Wikibook is pretty thorough though needs updating.
  • JavaScript Wikibook is incomplete, but seems a decent intro.

• Git resources:

  • Git for Ages 4 and Up 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.

  • Git Magic is a fully-FLO book written in a more narrative style.

  • The Git Docs page includes many links, an 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.

• Web browsers today have built-in developer tools which enable testing and experimenting with live websites. The Firebug plugin offers some additional functions as well.

• CanIUse.com is a reference website to check that all web features you use are compatible with various browsers and standards. The CanIUse data is fully FLO under a CC-BY license.

• The Yesod Book is the primary resource for learning about Yesod, the web framework we use to develop Snowdrift.

• The School of Haskell includes basic and advanced topics including some Yesod sections.

• At Stack Overflow (which uses FLO licensing for content), see tags for yesod and haskell (and, of course, other topics like HTML, CSS, Git, and so on)

• Alongside #snowdrift on freenode.net, check out #yesod , #haskell , and #haskell-beginners (among many other relevant channels).

• A useful development tool is stack ghci — a command that loads ghci in a mode connected to the project. Using that, you can easily import files from the code and explore the functions.

• Add hlint with stack install hlint, and then you can run hlint followed by a .hs filepath to get suggestions for improving the Haskell code style.