Commit d02ed568 authored by Bryan Richter's avatar Bryan Richter

Merge branch 'release-0.1.2' into production

parents e9790e57 354e62ee
......@@ -61,6 +61,7 @@ import Handler.RepoFeed
import Handler.ResetPassword
import Handler.SnowdriftEvent
import Handler.ToU
import Handler.Trademarks
import Handler.User
import Handler.User.Comment
import Handler.Volunteer
......
......@@ -195,8 +195,8 @@ instance Yesod App where
.
$nothing
You are not logged in, and this page is not publicly visible. #
<a href="@{AuthR LoginR}">Log in or create an account #
or return to our #
<a href="@{AuthR LoginR}">Log in or create an account
\ or return to our #
<a href="@{HomeR}">main page
.
|]
......@@ -280,8 +280,8 @@ authBrowserIdFixed =
toWidget [hamlet|
$newline never
<figure>
<a href="javascript:persona_login()">
<img src="https://browserid.org/i/persona_sign_in_blue.png">
<a href="javascript:persona_login()">
<img src="https://browserid.org/i/persona_sign_in_blue.png">
|]
in (authBrowserId def) { apLogin = login }
......@@ -293,10 +293,13 @@ snowdriftAuthBrowserId =
let parentLogin = apLogin auth toMaster
[whamlet|
<div .text-center>
<strong>We support Mozilla Persona &mdash; a universal, secure log-in that doesn't track you!
<strong>
We support Mozilla Persona — a universal,
secure log-in that doesn't track you!
^{parentLogin}
<p>
The Persona sign-in button works for both new and existing accounts.
The Persona sign-in button works for
both new and existing accounts.
|]
in auth { apLogin = login }
......@@ -306,29 +309,43 @@ snowdriftAuthHashDB =
loginRoute = PluginR "hashdb" ["login"]
login toMaster =
[whamlet|
<div id="login">
<div .text-center>
<strong>We also offer a built-in system
<br>
<a href="@{UserCreateR}">
<button>click here to create a new account
<p> or log-in below:
<form .form-horizontal method="post" action="@{toMaster loginRoute}">
<div .form-group>
<label .col-sm-4 .control-label>
Handle:
<div .col-sm-8>
<input .form-control id="x" name="username" autofocus="" required>
<div .form-group>
<label .col-sm-4 .control-label>
Passphrase:
<div .col-sm-8>
<input .form-control type="password" name="password" required>
<div .form-group>
<div .col-sm-offset-4 .col-sm-8>
<input type="submit" value="Log in">
<a href="@{ResetPasswordR}" .text-nowrap>
forgot your password?
<div #login>
<div .text-center>
<strong>
We also offer a built-in system
<div #new-account-button>
<a href=@{UserCreateR}>
<button>click here to create a new account
<p> or log-in below:
<form .form-horizontal
method=post
action=@{toMaster loginRoute}>
<div .form-group>
<label .col-sm-4 .control-label
for=handle>
Handle:
<div .col-sm-8>
<input .form-control
id=handle
name=username
autofocus
required>
<div .form-group>
<label .col-sm-4 .control-label
for=password>
Passphrase:
<div .col-sm-8>
<input .form-control
id=password
type=password
name=password
required>
<div .form-group .text-center>
<div #login-button>
<button type=submit>
Log in
<a href=@{ResetPasswordR}>
forgot your password?
|]
in auth { apLogin = login }
......@@ -373,7 +390,7 @@ createUser ident passwd name email avatar nick = do
case uid_maybe of
Just user_id -> do
-- TODO refactor back to insertSelect when quoting issue is resolved
-- TODO: refactor back to insertSelect when quoting issue is resolved
--
-- insertSelect $ from $ \ p -> return $ TagColor <# (p ^. DefaultTagColorTag) <&> val user_id <&> (p ^. DefaultTagColorColor)
--
......@@ -392,7 +409,7 @@ createUser ident passwd name email avatar nick = do
"), and let us know any questions."
]
-- TODO: change snowdrift_id to the generated site-project id
-- TODO(mitchell): This notification doesn't get sent to the event channel. Is that okay?
-- TODO: This notification doesn't get sent to the event channel. Is that okay?
insert_ $ Notification now NotifWelcome user_id (Just snowdrift_id) notif_text False
return $ Just user_id
Nothing -> do
......@@ -452,7 +469,7 @@ addAlertEm level msg em = do
#{msg}
|] render
-- TODO(mitchell): don't export this
-- TODO: don't export this
addAlert :: Text -> Text -> Handler ()
addAlert level msg = do
render <- getUrlRenderParams
......
Snowdrift.coop
==============
This guide covers the [Snowdrift.coop](https://snowdrift.coop) codebase and development process.
This guide covers the [Snowdrift.coop](https://snowdrift.coop) codebase
and development process.
Step-by-step instructions require no more than beginning-level programming or web designer experience.
Step-by-step instructions require no more than beginning-level programming
or web designer experience.
This guide assumes you are running a GNU/Linux system and have at least a *basic* understanding of command-line operations.
If you are on a different system or need *any* other help, come say "hi" at our freenode.net IRC channel [#snowdrift](https://snowdrift.coop/p/snowdrift/w/irc).
This guide assumes you are running a GNU/Linux system and have at least a
*basic* understanding of command-line operations.
If you are on a different system or need *any* other help,
come say "hi" at our freenode.net IRC channel
[#snowdrift](https://snowdrift.coop/p/snowdrift/w/irc).
We are always happy to assist and answer *any* questions!
......@@ -14,77 +20,102 @@ About the frameworks and tools we use
=====================================
Snowdrift.coop uses the **[Yesod web framework](http://www.yesodweb.com/)**.
Like the software itself, the associated book and documentation are all Free/Libre/Open (FLO) and quite thorough.
Like the software itself, the associated book and documentation are all
Free/Libre/Open (FLO) and quite thorough.
Yesod uses the Haskell programming language alongside its
[Shakespearean Templates](http://www.yesodweb.com/book/shakespearean-templates).
With some minor variations (such as indentation instead of closing tags or bracketing),
With some minor variations (mainly use of indentation instead of closing tags),
these templates use standard HTML, CSS, and JavaScript.
Our front-end uses **[Twitter Bootstrap](http://getbootstrap.com/)** for layout and styles,
Our front-end uses **[Twitter Bootstrap](http://getbootstrap.com/)**,
although we use our own custom CSS in many cases.
A suggestion for beginners: Firefox's built-in developer tools
and the [Firebug](https://getfirebug.com) plugin both offer great (and complementary) functions
for testing and experimenting with the live site.
and the [Firebug](https://getfirebug.com) plugin both offer great
(and complementary) functions for testing and experimenting with the live site.
Learning Haskell
----------------
Because everything is integrated, some familiarity with Haskell syntax is helpful
even if you stay mostly with front-end development.
Because everything is integrated, some familiarity with Haskell syntax
is helpful even if you stay mostly with front-end development.
At any rate, Haskell is a powerful and enjoyable language worth learning
for anyone interested in programming.
To learn Haskell, we recommend these FLO resources:
* The [Haskell Wikibook](https://en.wikibooks.org/wiki/Haskell) offers a superb introductory overview and includes links to many additional resources.
* At Stack Overflow, see the tags for [yesod](http://stackoverflow.com/questions/tagged/yesod) and [haskell](http://stackoverflow.com/questions/tagged/yesod)
* Alongside #snowdrift on freenode.net, check out the channels #yesod #haskell and #haskell-beginners
* A useful development tool is "cabal repl" — a command that loads [ghci](https://en.wikibooks.org/wiki/Haskell/Using_GHCi_effectively) in a mode connected to the project. Using that, you can easily import files from the code and explore the functions.
* To help write clean Haskell code and learn conventions, run hlint on your files to get suggestions for possible improvements.
* Given a working Haskell installation, add hlint with the command "cabal install hlint"
* The [Haskell Wikibook](https://en.wikibooks.org/wiki/Haskell) offers a superb
introductory overview and includes links to many additional resources.
* At Stack Overflow, see the tags for
[yesod](http://stackoverflow.com/questions/tagged/yesod) and
[haskell](http://stackoverflow.com/questions/tagged/yesod)
* Alongside #snowdrift on freenode.net, check out #yesod #haskell
and #haskell-beginners
* A useful development tool is "cabal repl" — a command that loads
[ghci](https://en.wikibooks.org/wiki/Haskell/Using_GHCi_effectively)
in a mode connected to the project. Using that, you can easily import
files from the code and explore the functions.
* To help write clean Haskell code and learn conventions, run hlint on your
files to get suggestions for possible improvements.
* Given a working Haskell installation,
add hlint with the command "cabal install hlint"
Text-editor settings
--------------------
We recommend setting your text editor to have the TAB key do indentation of four spaces.
We recommend setting your text editor to have the TAB key do indentation of
four spaces generally. However, we use 2-space indentation for .hamlet files.
We also use 80-character maximum line widths.
### vim
For vim users, your config file .vimrc should include these three lines:
For vim users, your config file .vimrc should include these four lines:
set textwidth=80
set expandtab
set shiftwidth=4
set tabstop=4
au FileType hamlet setl sw=2 sts=2 et
You should also install
[Shakespearean Syntax Highlighting for vim](https://github.com/pbrisbin/vim-syntax-shakespeare)
[vim Shakespearean Highlighting](https://github.com/pbrisbin/vim-syntax-shakespeare)
Some other optional vim plugins to consider (among many available):
[Haskell-Vim extra syntax](https://github.com/raichoo/haskell-vim) and
[Haskell-Vim extra syntax](https://github.com/raichoo/haskell-vim)
and
[vim2hs](https://github.com/dag/vim2hs)
### Emacs
Emacs users should use a package manager (preferably Marmalade) to install
[Haskell Mode](https://github.com/haskell/haskell-mode) and [Hamlet Mode](https://github.com/lightquake/hamlet-mode).
[Haskell Mode](https://github.com/haskell/haskell-mode)
and
[Hamlet Mode](https://github.com/lightquake/hamlet-mode).
Our included [`.dir-locals.el`](https://www.gnu.org/software/emacs/manual/html_node/emacs/Directory-Variables.html) file
makes Emacs use the recommended indentation.
makes Emacs use the recommended 4-space indentation.
Development guidelines and notes
================================
Overall, we strive to follow universal standards, be fully accessible, and avoid browser-specific code.
Overall, we strive to follow universal standards, be fully accessible,
and avoid browser-specific code.
We generally build with *progressive enhancement* in mind.
Content and functions should work with simple HTML/CSS along with Yesod/Haskell server-side functions.
Content and functions should work with simple HTML/CSS
along with Yesod/Haskell server-side functions.
Later, we add JavaScript as appropriate for enhancement.
Consider the ideas of [Unobtrusive JavaScript](http://en.wikipedia.org/wiki/Unobtrusive_JavaScript).
Consider the ideas of
[Unobtrusive JavaScript](http://en.wikipedia.org/wiki/Unobtrusive_JavaScript).
Use of NoScript should never causes a broken experience.
We also make sure all our JavaScript is recognized
by the FSF's [LibreJS plugin](https://www.gnu.org/software/librejs/).
......@@ -92,58 +123,69 @@ by the FSF's [LibreJS plugin](https://www.gnu.org/software/librejs/).
We have separate wiki and discussion pages on the site
for [web-design issues](https://snowdrift.coop/p/snowdrift/w/site-design)
and [coding issues](https://snowdrift.coop/p/snowdrift/w/coding).
We also have a complete [list of tickets](https://snowdrift.coop/p/snowdrift/t) in all categories.
Please consider adding concise comments to your code explaining to others anything you think may be unclear.
Ideally, follow the syntax for
[Haddock Haskell documentation](http://www.haskell.org/haddock/doc/html/markup.html).
The [complete list of Snowdrift tickets](https://snowdrift.coop/p/snowdrift/t)
shows all items from all discussion pages associated with the project.
Consider adding concise comments to your code following the syntax for
[Haddock documentation](http://www.haskell.org/haddock/doc/html/markup.html).
Working on the code
===================
See the main [Git documentation](http://git-scm.com/documentation) if you are new to Git.
You only need rudimentary understanding of Git to start contributing to our code.
It will help to understand basic branching so that you can segregate work on different features.
See the [Git documentation](http://git-scm.com/documentation) if new to Git.
You only need basic understanding to start contributing to our code.
Cloning the repository
----------------------
Cloning the repository and working with Git
-------------------------------------------
1. Have or make an account on Gitorious or GitHub
2. Clone (Gitorious' term) or Fork (GitHub's term) the snowdrift repository to your account
2. Clone (Gitorious) or Fork (GitHub) the snowdrift repository to your account
3. Tell Gitorious/GitHub the public side of your local SSH key
* If you don't yet have a key, create one on your local machine with the command "ssh-keygen"
* If not done already, create a key on your local machine with `ssh-keygen`
* The public part is in the .pub file (such as id_rsa.pub)
* Both sites have further instructions if this isn't clear enough
4. On your local machine, use the `git clone` command with the Gitorious or Github address for your account
4. On your local machine, use the `git clone` command
with the Gitorious or Github address for *your* account
This will create a directory and download the code to it.
In the future, when in the new directory,
`git pull` will update your local machine from your Gitorious or GitHub account,
and `git push` will go the other direction, sending any local commits to Gitorious or GitHub.
After pushing to your online account,
alert us to the changes with Gitorious' "request merge" or GitHub's "pull request" commands on their websites.
You should also set a remote for the main code with
git remote add snowdrift-main git@gitorious.org:snowdrift/snowdrift.git
To get updates from our main code, use
The same sort of command can be used to add remotes for other contributors you
may collaborate with.
git fetch git@gitorious.org:snowdrift/snowdrift.git
### Making changes to the code
Then, to see the diff for the updates, use
We suggest that all work be done on separate *branches*.
So, to make changes to the code, first run `git checkout -b [branchname]`
with an appropriate "branchname" for the work you plan to do.
Use as many branches as needed for all work that functions independently
(you can remove merged branches later).
git diff FETCH_HEAD
When sharing your changes, it is best to first rebase them onto the latest
master code. So, after you have made commits on a branch, update your master
by running `git checkout master` followed by `git pull snowdrift-main`.
To edit the new code before merging, you can do
Next, rebase your work onto master with `git checkout [branchname]`
followed by `git rebase master`.
git checkout FETCH_HEAD
Let us know if you have trouble with any conflicts that may arise,
and we can help work through them.
To merge the update, make sure you checkout the branch where you want the updates, then
To upload your changes after rebase, run `git push origin [branchname]`.
git merge FETCH_HEAD
After pushing, alert us to the changes with Gitorious' "request merge"
or GitHub's "pull request" commands on their websites.
Make sure to choose the correct source branch.
Note: when collaborating with others across Gitorious and GitHub (or other hosts),
you can use the same fetch process by using the git address from each developer
and simply communicate by e-mail or IRC or other options about when to fetch updates.
Note: as a rule, don't rebase any work that you have already pushed.
In the case that you know others have not pulled the work, you can
rebase and then *force* push, and there are other advanced git management tools,
but we won't get into those here.
Building
......@@ -151,42 +193,51 @@ Building
### Notes for different operating systems:
We don't yet have all the details documented, but Snowdrift has been successfully built
on Debian, Ubuntu, Arch, Gentoo, and related distros of GNU/Linux and should work on all
other distros.
We don't yet have everything documented, but Snowdrift has been built
successfully on Debian, Ubuntu, Arch, Gentoo, and related distros of GNU/Linux
and should work on all other distros.
For NixOS, see the notes in the appendix here under the section about Nix package manager.
For NixOS, see the notes in the appendix here.
Snowdrift also has been built on Mac OS Yosemite.
The Mac OS build process seems to have some issues with postgres user names being different;
so until we address that, the database set-up for Mac OS will need to be done manually,
and the precise commands may vary slightly from the ones we include here.
The Mac OS build process seems to have some issues with postgres user names;
so for now, the database set-up for Mac OS will need to be done manually.
See the appendix at the end of this file for more.
### Build steps
Install the essential dependencies: ghc, cabal, postgresql, happy, alex, zlib1g
Additional dependency (which may vary for different systems): libpq-dev
Additional dependency (which may vary for different systems): libpq
On Debian-based GNU/Linux distros, use this command:
**Note: we are now using GHC 7.8.x**
sudo apt-get install ghc cabal-install postgresql zlib1g-dev libpq-dev happy alex
As the details vary by system, we may not have the complete instructions
correct for every case. Come ask for help at #snowdrift on freenode.net IRC
if you have any trouble. Help us improve this guide when you can.
**Note: we are now using GHC 7.8.x**
If your system's GHC version is older, get the update from <https://www.haskell.org/ghc/>
**<https://www.haskell.org/downloads/linux>** has instructions for
installing ghc, cabal, happy, and alex on Ubuntu, Fedora, and Arch
along with manual install instructions for other systems.
Next, update cabal's package list:
You will need to also install postgresql and the other libraries.
If you didn't run it as part of installation, update cabal's package list:
cabal update
Add cabal location(s) to your PATH; the location may vary by system and set-up. Below are the most common situations:
Add cabal location(s) to your PATH; the location may vary by system and set-up.
Below are the most common situations:
* for GNU/Linux, just add `export PATH=.cabal-sandbox/bin:~/.cabal/bin:$PATH` to your ~/.bashrc (or equivalent) file
* for GNU/Linux, add `export PATH=.cabal-sandbox/bin:~/.cabal/bin:$PATH`
to your ~/.bashrc (or equivalent) file
* for Mac OS, try adding `export PATH="$HOME/Library/Haskell/bin:$PATH"` to ~/.bash_profile
* for Mac OS, try adding `export PATH="$HOME/Library/Haskell/bin:$PATH"`
to ~/.bash_profile
Start a new terminal (or run `source ~/.bashrc` or similar) to make the PATH active.
Start a new terminal (or run `source ~/.bashrc` or similar)
to make the PATH active.
Now, upgrade cabal itself:
......@@ -202,8 +253,9 @@ Install dependencies and build Snowdrift
cabal install --enable-tests -fdev
This will take a *long* time but should ultimately tell you it installed Snowdrift.
Note: the `-fdev` flag skips optimization to make build faster. It should be ommited for building the actual live site.
This will take a *long* time but should ultimately tell you it installed.
Note: the `-fdev` flag skips optimization to make build faster.
It should be ommited for building the actual live site.
Contact us for help if the build is not successful.
......@@ -212,28 +264,29 @@ Setting up the database
-----------------------
We offer a simple script that will setup the PostgreSQL databases for you.
Some systems may need some extra set-up, but for most GNU/Linux systems, simply run:
Some systems may need extra set-up, but for most GNU/Linux systems, simply run:
sdm init
It will prompt you for your sudo password.
If you prefer to set up databases manually, see the appendix at the end of this guide.
To set up databases manually, see the appendix at the end of this guide.
Running the site
----------------
After completing all the steps above,
you can start the server from within your snowdrift directory with the command:
start the server from within your snowdrift directory with the command:
Snowdrift Development
To stop the running server, press ctrl-C
To rebuild after code changes, run `cabal install` (perhaps with `-fdev` to skip optimization).
To rebuild after code changes, run `cabal install`
(perhaps with `-fdev` to skip optimization).
(note `cabal build` works as well but fails to recognize changes to template files)
(`cabal build` works also but fails to recognize changes to template files)
After the server starts, it may print a bunch of text about creating tables,
......@@ -246,9 +299,11 @@ Using the live test site
Test the running site by directing your web browser to localhost:3000
You can log into the site via the built-in system with user: admin pass: admin
You can log into the site via the built-in system with
user: `admin` pass: `admin`
You can now register new users, make pledges, add discussion comments, tickets, wiki pages, blog posts, and test and work on all aspects of the site.
You can now register new users, make pledges, add discussion comments,
tickets, wiki pages, blog posts, and test and work on all aspects of the site.
Running tests
......@@ -256,9 +311,10 @@ Running tests
After making various changes to the code and running locally
to verify that everything compiles and also appears to work as desired,
best practice involves then running our automated tests before sharing your changes with the main project.
best practice involves then running our automated tests before sharing
your changes with the main project.
Assuming you ran `sdm init` when you first set up the databases, run the tests with:
Assuming you ran `sdm init` to set up the databases, run the tests with:
yesod test
......@@ -275,18 +331,15 @@ After any change to the database schema (in config/models),
the first time you recompile and then start the server,
a migration script will be automatically generated and placed in /migrations.
The safe (i.e. guaranteed not to lose data) statements, if any,
are placed in migration/migrateN where N is the next number in sequence.
If there are no unsafe statements in the migration,
the safe statements will be run and the server will continue to start normally.
the migrations will be run and the server will continue to start normally.
If there are any unsafe (may destroy data) statements,
they are placed in migrations/migrate.unsafe, and the server will abort.
In an unsafe case, if the data *is* intended to be lost
(e.g. destroying a column storing data we no longer want),
just copy the statements to the new migrateN file (creating it if necessary).
copy the statements to the new migrateN file (creating it if necessary).
If you don't want to lose the data
(a column is being moved to a different table, a column is being renamed, &c),
......@@ -296,15 +349,20 @@ modify the migration file to use the appropriate intended SQL commands.
Committing database migrations
------------------------------
In the course of testing and/or resetting your database, you might generate extra migrations.
When that happens, be sure to reset your database and remove any extraneous migration files.
Once you have a final version of the code, you can run the site once to generate the correct final migration.
NOTE: THE MIGRATION SITUATION IS BEING ADJUSTED, THIS MAY BE OUTDATED
Ideally consolidate all migrations so there is only one migration file per commit.
In the course of testing and/or resetting your database,
you might generate extra migrations. When that happens,
be sure to reset your database andremove any extraneous migration files.
Once you have a final version of the code, you can run the site once to
generate the correct final migration.
Make sure to add the associated migration file to git when you commit the corresponding schema changes.
Ideally consolidate all migrations to only one migration file per commit.
When merging migrations, always put any you've added on the end in separate file(s).
Make sure to add the associated migration file to git when you commit
the corresponding schema changes.
When merging migrations, put any you've added on the end in separate file(s).
Don't merge them into migration files others may have already run.
......@@ -315,16 +373,17 @@ To remove any changes and reset your database to the devDB default
(such as when others have provided a new update you want to try
or to start clean before making changes you plan to commit) run:
sdm reset --db=dev
sdm reset
Sharing updates to the devDB database
-------------------------------------
If you make specific improvements or additions to your database
that aren't just playing around but that you think will make for a better starting database
for other contributors (and also when you have updated the basic database with migration files),
you can use the following command to export the changes (which can then be committed via git as usual).
that you think will make for a better start for other contributors
(and also when you have updated the basic database with migration files),
you can use the following command to export the changes
(which can then be committed via git as usual).
While in your project directory:
......@@ -340,14 +399,9 @@ Updating to the latest test database
When the testDB.sql file is updated, you'll need to update your template.
Although `sdm reset --db=test` ought to work, something is wrong with that script as of this writing.
If you run `sdm clean` followed by `sdm init`,
that will work, but it will reset both your development *and* test databases.
Simply run `sdm reset --db=test` to reset/update your test databases.
If you don't want to reset your development database,
you can *manually* reset only the test database.
See the appendix section at the end of this guide.
See the appendix section of this guide for how to reset manually.
---
......@@ -358,17 +412,18 @@ Happy hacking!
APPENDIX A: Using yesod devel
=============================
A useful development tool, `yesod devel` will rebuild snowdrift, start the server,
*and* can stay running and will automatically update the build after each saved change
`yesod devel` is a command that will rebuild snowdrift, start the server,
*and* can stay running and automatically update the build after file changes
(although it fails to auto-recognize changes in some file types like .cassius).
To enable yesod devel, you must first install yesod-bin.
Unforunately, yesod-bin will not currently build in the same sandbox with the main site.
However, yesod-bin will not currently build in the main sandbox.
So, at this time, to enable yesod devel, first make a new directory for yesod-bin.
So, at this time, to enable yesod devel, make a new directory for yesod-bin.
Call it "yesod-bin-sandbox" perhaps.
Then, inside the new directory, run `cabal sandbox init` followed by `cabal install yesod-bin`.
Then, inside the new directory, run `cabal sandbox init`
followed by `cabal install yesod-bin`.
Next, add to the new directory to your PATH. Put in your .bashrc the line:
......@@ -384,55 +439,80 @@ you can rebuild and start the server in your snowdrift directory by running
To stop yesod devel, press ENTER a couple times
Note that `yesod devel` builds just the library,
so `cabal install` and related commands are needed to update other resources like sdm or the payment processing script.
so `cabal install` and related commands are needed to update other resources
like sdm or the payment processing script.
APPENDIX B: Using the Nix package manager
=========================================
We're now testing the use of Nix as a reliable, simple way to manage packages for Snowdrift.
We're now testing the use of Nix as a reliable, simple way
to manage packages for Snowdrift.
Once we have it fully working, it should help simplify building overall.
**The instructions in this appendix are just draft and need cleaning up.**
We're not sure each of these commands is best, it may change as we continue testing.
We're not sure each of these commands is best,
it may change as we continue testing.
To install Nix, visit [NixOS.org/nix](https://nixos.org/nix/) and follow the "Get Nix" instructions (works for GNU/Linux and Mac OS).
To install Nix, visit [NixOS.org/nix](https://nixos.org/nix/)
and follow the "Get Nix" instructions (works for GNU/Linux and Mac OS).
*Note: Nix can take a lot of drive space, so if you do not have many GB of free space on your root partition, you may need to find another approach.
Free up space or put the `nix` directory somewhere else with more space and edit `/etc/fstab` to bind the location to mount at `/nix`.*
*Note: Nix can take a lot of drive space, so if you do not have many GB
of free space on your root partition, you may need to find another approach.
Free up space or put the `nix` directory somewhere else with more space
and edit `/etc/fstab` to bind the location to mount at `/nix`.*
Next, log out and back into your whole system (the environment variables command shown at the end of the install script's output works for the immediate terminal session for a temporary fix).
Next, log out and back into your whole system (the environment variables
command shown at the end of the install script's output works for the
immediate terminal session for a temporary fix).
[Nixpkgs](https://nixos.org/nixpkgs/), a collection of packages used by Nix, usually has only the latest packaged version and is a rolling-release distribution, which leaves us with two options:
[Nixpkgs](https://nixos.org/nixpkgs/), a collection of packages used by Nix,
usually has only the latest packaged version and is a rolling-release
distribution, which leaves us with two options:
* Update our code and dependencies whenever the unstable channel (or the master branch) is changed.
* Update our code and dependencies whenever the unstable channel
(or the master branch) is changed.
* Maintain our own collection of package versions that are known to work.
The former is clearly too much work and is not reliable anyway, so we use the latter approach.
Get a copy of our repository with this command:
The former is clearly too much work and is not reliable anyway,
so we use the latter approach. Get a copy of our repository with this command:
git clone https://github.com/nkaretnikov/nixpkgs.git -b snowdrift
It automatically switches to the right branch, so the only thing left is to point the [`NIX_PATH`](https://nixos.org/nix/manual/#sec-common-env) environment variable to the directory *containing* the `nixpkgs` repository.
For example, if a user cloned it to `/home/user`, that's the value they need to use:
It automatically switches to the right branch,
so the only thing left is to point the
[`NIX_PATH`](https://nixos.org/nix/manual/#sec-common-env)
environment variable to the directory *containing* the `nixpkgs` repository.
For example, if a user cloned it to `/home/user`,
that's the value they need to use:
export NIX_PATH=/home/user
Within the snowdrift project directory, run `nix-shell --pure -j4 shell.nix` to get necessary libraries and set `PATH` (the `-j4` part should be adapted to fit the number of cores on your machine).
Within the snowdrift project directory,
run `nix-shell --pure -j4 shell.nix` to get necessary libraries
and set `PATH`
(the `-j4` part should be adapted to fit the number of cores on your machine).
The first time this is run, it will take a long time,
but then will present you a new prompt within `nix-shell`.
The first time this is run, it will take a long time, but then will present you a new prompt within `nix-shell`.
Within the nix shell, run
Within the nix shell, run `cabal configure -fdev --enable-tests && cabal build -j4`
cabal configure -fdev --enable-tests && cabal build -j4
*Note the `-fdev` argument speeds up the build by bypassing optimization, which means the site runs slower, but that's not a problem for development work.*
*Note the `-fdev` argument speeds up the build by bypassing optimization,
which means the site runs slower, but that's not a problem for development work.*
This will take a *long* time but should ultimately tell you it built `Snowdrift`.
Since the `nix-shell` command changed your `PATH`, it doesn't have things like `sudo`, which is used by the `sdm` script.
Run `dist/build/sdm/sdm init` *outside* the nix shell (in a different terminal window) if you need to setup the databases.
Then, you can go back to the nix shell to run `cabal test`, which runs the testsuite.
Since the `nix-shell` command changed your `PATH`,
it doesn't have things like `sudo`, which is used by the `sdm` script.
Run `dist/build/sdm/sdm init` *outside* the nix shell
(in a different terminal window) if you need to setup the databases.
Then, you can go back to the nix shell to run `cabal test`,
which runs the testsuite.
You can run the application with `dist/build/Snowdrift/Snowdrift Development`.
......@@ -440,7 +520,8 @@ You can run the application with `dist/build/Snowdrift/Snowdrift Development`.
Note for users of NixOS
-----------------------
To get the sdm script to work, NixOS users should install postgres by adding these lines to /etc/nixos/configuration.nix:
To get the sdm script to work, NixOS users should install postgres
by adding these lines to /etc/nixos/configuration.nix:
services.postgresql.enable = true;
services.postgresql.package = pkgs.postgresql94;
......@@ -457,7 +538,7 @@ APPENDIX C: Manual database management
Our sdm script makes database management quick and easy.
All the steps below can be done simply with the sdm script,
but here we explain what it does and how to handle databases manually if you prefer.
but here we explain what it does and how to handle databases manually.
The commands below are written with GNU/Linux in mind.
***
......@@ -465,15 +546,20 @@ The commands below are written with GNU/Linux in mind.
Notes for Mac OS X
------------------
Assuming the postgres server is running, where `sudo -u postgres psql` is seen below, run `psql postgres` instead.
The commands that don't use psql can be adapted to run within the psql command line.
Assuming the postgres server is running,
where `sudo -u postgres psql` is seen below,
run `psql postgres` instead.
The commands that don't use psql can be adapted
to run within the psql command line.
For Mac OS, instead of `sudo -u postgres psql snowdrift_development <devDB.sql` follow these steps:
For Mac OS, instead of `sudo -u postgres psql snowdrift_development <devDB.sql`
follow these steps:
1) Run `psql snowdrift_development`
2) At snowdrift_development=# prompt, run `\i devDB.sql`
Similar adjustments will be needed for the test database setup and resetting databases.
Similar adjustments will be needed for the
test database setup and resetting databases.
***
......@@ -484,7 +570,8 @@ Setting up the development database manually
Go to the config/ directory within the project directory,
make a copy of postgresql.template, and name the new file postgresql.yml
Create database user called "snowdrift_development" *without* superuser, createdb, or createuser privileges:
Create database user called "snowdrift_development"