We are no longer offering accounts on this server. Consider https://gitlab.freedesktop.org/ as a place to host projects.

Assassinate this repo

parent a77b8658
((haskell-mode . ((haskell-indentation-layout-offset . 4)
(haskell-indentation-starter-offset . 1)
(haskell-indentation-left-offset . 4)
(haskell-indentation-ifte-offset . 4)
(haskell-indentation-where-pre-offset . 2)
(haskell-indentation-where-post-offset . 2)
(evil-shift-width . 2)
(haskell-tags-on-save . t)))
(hamlet-mode . ((hamlet/basic-offset . 4))))
# Intellij IDEA:
# EclipseFP:
[submodule "publications"]
path = publications
url = git@git.snowdrift.coop:sd/publications.git
<?xml version="1.0" encoding="UTF-8"?>
# Building and Running Snowdrift
Snowdrift has been built successfully on GNU/Linux distributions of all sorts
and on OpenBSD and OS X.
Windows is not currently supported, but we will assist any efforts to add
such support. See below for partial setup instructions.
## Install System Dependencies
[Git], [PostgreSQL], and [Stack] are the only dependencies needed at the system
level. Stack takes care of finding or installing the correct GHC version. Some
systems need a few additional libraries to support the core dependencies.
**Follow the details for your system, then skip to the "Get the Snowdrift Code"
### Debian, Ubuntu, and any related derivatives
Install Git and PostgreSQL with needed libraries:
sudo apt-get update
sudo apt-get install git postgresql postgresql-client libgmp-dev zlib1g-dev libpq-dev libtinfo-dev
Then follow the
[Debian Stack install](https://github.com/commercialhaskell/stack/blob/master/doc/install_and_upgrade.md#debian)
[Ubuntu Stack install](https://github.com/commercialhaskell/stack/blob/master/doc/install_and_upgrade.md#ubuntu)
instructions as appropriate.
### CentOS/RHEL and Fedora
Install Git and needed libraries:
sudo yum update
sudo yum install ncurses-devel gmp-devel zlib-devel git
For newer versions of Fedora, replace the `yum` commands with `dnf`. Install the
following libraries if you don't already have them:
sudo dnf install libstdc++-static gcc-c++
You'll also need PostgreSQL >= 9.3:
sudo yum install postgres-server postgres-devel
If the version in the base repositories is too old, follow the [instructions on the
PostgreSQL wiki](https://wiki.postgresql.org/wiki/YUM_Installation) to install from
their repositories. Get the postgresXX-server and postgresXX-devel packages, where
XX is the version number.
So that the Snowdrift database cluster tool sees the pgsql executables at
`/usr/pgsql-X.X/bin` on your PATH, either add that route (with the correct numbers
instead of X.X) to your PATH (e.g. in `~/.bash_profile`, `~/.bashrc` or
`~/.profile`) or create symlinks somewhere already on your PATH.
Then follow the [Stack install instructions](https://github.com/commercialhaskell/stack/blob/master/doc/install_and_upgrade.md) for your distribution.
### Arch Linux
Install Git and PostgreSQL by running this command as `root`:
pacman -S git postgresql
Finally, install the
package from the AUR.
### NixOS
Install Git as usual under NixOS.
Then, follow the [NixOS Stack install instructions](https://github.com/commercialhaskell/stack/blob/master/doc/install_and_upgrade.md#nixos).
For PostgreSQL, add these lines to `/etc/nixos/configuration.nix`:
services.postgresql.enable = true;
services.postgresql.package = pkgs.postgresql94;
Then install PostgreSQL with:
sudo nixos-rebuild switch
Afterwards, you may need to create the postgres user, like so:
sudo -su root
createuser -s -r postgres
#### Building Snowdrift and GHC with NixOS
Stack can fetch and build the required version of GHC, but this
doesn't work well on NixOS due to an unusual filesystem hierarchy,
among other things. Instead, just use `nix-shell` to get into an
environment with the right compiler version:
nix-shell -p haskell.compiler.ghc7102
You can now attempt to build Snowdrift via the general instructions below. Stack
will likely complain about some missing items (like zlib). To continue, install
listed items manually via `nix-env` or `nox`, then specify their location like
stack build --extra-include-dirs ~/.nix-profile/include \
--extra-lib-dirs ~/.nix-profile/lib
### \*BSD
*Any knowledgeable reader: please help us document any important notes about
installing the Git, PostgreSQL, and Stack dependencies on \*BSD.*
### OS X
If you don't have [brew](http://brew.sh/) yet, install it with:
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
With brew, install the core dependencies:
brew install git
brew install postgres
brew install haskell-stack
### Windows
*Status:* We do not officially support Windows, but we welcome testing. From
reports so far, SnowdriftEmailDaemon won't build on Windows, so `stack test`
will fail. Our database management utility (sdb.hs) is also untested on
Install [Git] per instructions on the website.
Install PostgreSQL 32-bit version from
Add the PostgreSQL bin directory to the path
`C:\Program Files (x86)\PostgreSQL\9.4\bin`
Follow the instructions to
[install Stack for Windows](https://github.com/commercialhaskell/stack/blob/master/doc/install_and_upgrade.md#windows)
## Get the Snowdrift code
NB: We primarily use a completely FLO (Free/Libre/Open) host for our code:
[git.snowdrift.coop/sd/snowdrift], and our instructions assume that repository.
For convenience and redundancy, we also mirror at [GitHub], a popular but
proprietary platform.
From within your preferred directory, get the code with:
git clone https://git.snowdrift.coop/sd/snowdrift.git
## Initial Build
### Compile the code
Change to the new snowdrift directory:
cd snowdrift
Then, fetch all Haskell dependencies and build everything:
stack setup
stack build
NB: this will take a while!
### Set up the database
We have a simple tool that creates a private database cluster local to the
project. On GNU/Linux, BSD, or OS X, initialize databases by running:
./sdb.hs init
NB: The sdb.hs tool won't work on Windows because it uses UNIX sockets. We
welcome any patches, feedback, or Postgres-on-Windows help to get an alternative
NB: To see sdb commands for other operations, run `./sdb.hs --help`
### Run initial tests
Run the tests to compile the test dependencies:
stack test
## Running the site
### Starting the database
If you just initialized, the database cluster should already be running.
However, it will stop under various circumstances such as rebooting your
computer. If you try to run the site when the cluster is stopped, you will get
an error stating "Snowdrift: libpq: failed (could not connect to server: No such
file or directory". To make sure the database is running, enter:
./sdb.hs start
### Option 1: run via `Snowdrift Development`
From the snowdrift project directory, run the site in development mode via:
stack exec Snowdrift Development
(to stop the site, use ctrl-C)
### Option 2: run via `yesod devel`
NB: `yesod devel` provides automatic rebuilding and rerunning of the site
whenever it detects changes to the code, but it requires extra compile processes
the first time you use it. It also uses some minor extra drive space and
additional resources to run the file-watching process, and yesod devel is
currently incompatible with the optional ghc-mod tool mentioned in
To set up `yesod devel`, run:
stack build cabal-install yesod-bin
From now on, you may run the site in development mode via:
stack exec yesod devel
NB: The first run will take a long time.
(To stop yesod devel, type `quit` in terminal and then press Enter)
## Using the local site
### View in your browser
Access the site in your browser at <http://localhost:3000>
### Log-in options
The development database comes with three default users (with username and
passphrase the same):
* admin
* established
* guest
### Testing
Run the test suite with:
stack build && stack test --pedantic
NB: we include `stack build` because our current cabal setup does not fully
recognize test dependencies on executables such as SnowdriftProcessPayments.
### Manual rebuild
To rebuild the site, run:
stack build
NB: As mentioned above, if you run the site with `Snowdrift Development`, then
to see any changes, you must stop the site, manually rebuild, then restart the
site. If you use `yesod devel`, the site will rebuild and restart automatically
for most changes. However, **manual rebuild is always required whenever you:**
* add new dependencies (i.e. edit the `build-depends` in `Snowdrift.cabal`)
* update any extra binaries such as the payment processing script or the
email daemon.
NB: In rare cases, you may need to run `stack clean` if building fails to
recognize a change.
#### Updating static files
To make builds recognize changes to the static directory, run:
touch src/Settings/StaticFiles.hs
### Exploring the code via REPL
To start the REPL where you can run code from the site in an interpreter, use:
stack ghci
## Database notes
See [DATABASE-MANAGEMENT.md] for instructions on resetting the database and
## Getting help, learning, contributing etc.
We welcome any and all feedback on these build instructions, on the site itself,
etc. We will happily help you with any questions. See the [README](README.md)
for further general links, and the [Contributing Guide](CONTRIBUTING.md) for
more thorough resources about technical development.
[Git]: http://www.git-scm.com/downloads
[git.snowdrift.coop/sd/snowdrift]: https://git.snowdrift.coop/sd/snowdrift
[GitHub]: https://github.com/snowdriftcoop/snowdrift
[PostgreSQL]: http://www.postgresql.org/download/
[Stack]: https://github.com/commercialhaskell/stack#the-haskell-tool-stack
# 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
## 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](BUILD.md) 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](BUILD.md) instructions** to get Snowdrift going on your
## 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](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).
To make it easier to follow changes, please retain the full list of commits
when pushing branch updates, and only rebase when requested.
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
We also mirror on the popular but proprietary site
which you may use if you already have an account there. As we encourage
everyone to use FLO tools, the instructions below assume git.snowdrift.coop.
To contribute changes to the project, first
[create an account on git.snowdrift.coop](https://git.snowdrift.coop/users/sign_in)
(or sign in if you already have an account).
Once signed in, go to <https://git.snowdrift.coop/sd/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](https://git.snowdrift.coop/help/ssh/README) 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:
Where `YOURNAME` is your git.snowdrift.coop 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.snowdrift.coop/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](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
Next, send your changes to your git.snowdrift.coop 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.snowdrift.coop 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](https://snowdrift.coop/p/snowdrift/t) 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](http://www.yesodweb.com/book/shakespearean-templates).