<commit_before>Snowdrift.coop
==============

Infrastructure for [Snowdrift.coop](https://snowdrift.coop).

Code is mirrored at [GitHub](https://github.com/dlthomas/snowdrift) (which is popular but proprietary) and [Gitorious](https://gitorious.org/snowdrift/snowdrift) (which is FLO, licensed AGPL, but less popular).

See the main [Git documentation](http://git-scm.com/documentation) if you are new to Git and need to learn the basics. You only need rudimentary understanding to start contributing to our code. It will help to understand branching so that you can segregate work on different features.


Work to do / how to help
========================

On the live site, we have [volunteer info](https://snowdrift.coop/p/snowdrift/w/how-to-help) which includes a general guide around the site. The site wiki and discussion system is our main organizational tool, but our #snowdrift IRC channel on freenode.net is a good place to get help or ask casual questions.

We have [our own in-progress ticketing system](http://snowdrift.coop/p/snowdrift/t) which lists most of the specific tasks of all sorts, organized with tags indicating priority, skills involved, and more.

This README assumes a basic understanding of command-line operations. If you need help with that or *any other* issues, let us know and we'll be happy to guide you!
                                                                                                                                        

About the frameworks and tools we use
=====================================

The Snowdrift.coop site uses the [Yesod web framework](http://www.yesodweb.com/).

Yesod uses the Haskell programming language alongside its
[Shakespearean Templates](http://www.yesodweb.com/book/shakespearean-templates) which generate HTML/CSS/JS using indentation with no need for closing tags or bracketing.

HTML, CSS, and JavaScript work on the site may be done without knowing Haskell, but because everything is integrated, some familiarity with the Haskell syntax is helpful.

* For learning Haskell, check out the [Haskell Wikibook](https://en.wikibooks.org/wiki/Haskell), which also has links to additional resources.
* Stack Overflow user postings are FLO (CC-BY-SA), see the tags for [yesod](http://stackoverflow.com/questions/tagged/yesod) and [haskell](http://stackoverflow.com/questions/tagged/yesod)
* The #yesod and #haskell IRC channels on freenode.net are active and helpful

Our front-end design uses **[Twitter Bootstrap](http://getbootstrap.com/)** for layout and styles, although there are cases where we use our own custom CSS.

On the site we have a page about [site-design](https://snowdrift.coop/p/snowdrift/w/site-design), and the tickets and discussion there cover specific issues.

As a suggestion: Firefox's built-in developer tools offer lots of great ways to test the site, although [Firebug](https://getfirebug.com) may also be a useful addition for certain features.


Text-editor settings
--------------------

We recommend setting your text editor to have the TAB key do indentation of four spaces.
For VIM, for example, the config file .vimrc should have these three lines:

    set expandtab
    set shiftwidth=4
    set tabstop=4

VIM users should also install [Syntax Highlighting Files for Haskell](https://github.com/pbrisbin/html-template-syntax).

Emacs users should use a package manager (preferably Marmalade) to install [Haskell Mode](https://github.com/haskell/haskell-mode).


Development guidelines and notes
================================

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 be built with simple HTML/CSS along with Yesod/Haskell server-side functions.
JavaScript may then added for enhancement. 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/).

We have a separate wiki and discussion page on the site for discussing specific [web-design issues](https://snowdrift.coop/p/snowdrift/w/site-design).


Working on the code
===================

Cloning the repository
----------------------

1. Have or make an account on Gitorious or GitHub
2. Clone (Gitorious' term) / Fork (GitHub's term) 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"
    * 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

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.

To pull updates from our main code, use

    git pull <EMAIL>:snowdrift/snowdrift.git


Building
--------

Install ghc, cabal, and postgresql, however you do that on your system.

On Debian-based GNU/Linux distros, that's:

    sudo apt-get install ghc cabal-install haskell-platform postgresql zlib1g-dev libpq-dev happy alex

(There are a few non-Haskell libraries that some dependencies which you may
need to install, presumably in your system's package manager as well.
I don't have the list at hand, but they can be picked out of the error
messages when the below fails for want of them - if you make a list,
please update this and send a pull request!)

   *note: there have been some errors reported with older versions of ghc and the haskell-platform* At this time, we are using GHC 7.6.3 and Haskell Platform 2013.2.0.0 — both are included in the latest Ubuntu, and there are [instructions for building updated GHC on older Ubuntu-based systems](https://gist.github.com/Dexyne/5791465). We tested this with Ubuntu 12.04 LTS and it should work on derivatives as well (such as the fully-FLO Trisquel 6). These instructions or similar should work for other systems as well, but see <http://www.haskell.org/platform/> for more general info.

Update cabal's package list:

    cabal update

Add ~/.cabal/bin to your PATH; for bash, run the following command
(also add it to your .bashrc (or equivalent) file so it will run automatically in the future):

    export PATH=~/.cabal/bin:$PATH

Update cabal so you can use the new [sandbox](http://coldwa.st/e/blog/2013-08-20-Cabal-sandbox.html) feature in cabal 1.18+:

    cabal install Cabal cabal-install

**change to your snowdrift directory (if you're not already working there).**

For isolation in case you have multiple snowdrift checkouts or other Haskell projects, initiate a cabal sandbox:

    cabal sandbox init

Add your sandboxed binaries to your PATH: (For the future, you may also wish to add this to your .bashrc or equivalent.)  
*note: replace "snowdrift" in the command with whatever the name of your directory.
GitHub clones are normally just "snowdrift" but Gitorious clones are "username-snowdrift"*<commit_msg>updated with better clarity about putting the directory wherever<commit_after>Snowdrift.coop
==============

Infrastructure for [Snowdrift.coop](https://snowdrift.coop).

Code is mirrored at [GitHub](https://github.com/dlthomas/snowdrift) (which is popular but proprietary) and [Gitorious](https://gitorious.org/snowdrift/snowdrift) (which is FLO, licensed AGPL, but less popular).

See the main [Git documentation](http://git-scm.com/documentation) if you are new to Git and need to learn the basics. You only need rudimentary understanding to start contributing to our code. It will help to understand branching so that you can segregate work on different features.


Work to do / how to help
========================

On the live site, we have [volunteer info](https://snowdrift.coop/p/snowdrift/w/how-to-help) which includes a general guide around the site. The site wiki and discussion system is our main organizational tool, but our #snowdrift IRC channel on freenode.net is a good place to get help or ask casual questions.

We have [our own in-progress ticketing system](http://snowdrift.coop/p/snowdrift/t) which lists most of the specific tasks of all sorts, organized with tags indicating priority, skills involved, and more.

This README assumes a basic understanding of command-line operations. If you need help with that or *any other* issues, let us know and we'll be happy to guide you!
                                                                                                                                        

About the frameworks and tools we use
=====================================

The Snowdrift.coop site uses the [Yesod web framework](http://www.yesodweb.com/).

Yesod uses the Haskell programming language alongside its
[Shakespearean Templates](http://www.yesodweb.com/book/shakespearean-templates) which generate HTML/CSS/JS using indentation with no need for closing tags or bracketing.

HTML, CSS, and JavaScript work on the site may be done without knowing Haskell, but because everything is integrated, some familiarity with the Haskell syntax is helpful.

* For learning Haskell, check out the [Haskell Wikibook](https://en.wikibooks.org/wiki/Haskell), which also has links to additional resources.
* Stack Overflow user postings are FLO (CC-BY-SA), see the tags for [yesod](http://stackoverflow.com/questions/tagged/yesod) and [haskell](http://stackoverflow.com/questions/tagged/yesod)
* The #yesod and #haskell IRC channels on freenode.net are active and helpful

Our front-end uses **[Twitter Bootstrap](http://getbootstrap.com/)** for layout and styles, although there are cases where we use our own custom CSS.

On the site, we have a page about [site-design](https://snowdrift.coop/p/snowdrift/w/site-design) with associated tickets and discussion.

As a suggestion: Firefox's built-in developer tools offer lots of great ways to test the site, although [Firebug](https://getfirebug.com) may also be a useful addition for certain features.


Text-editor settings
--------------------

We recommend setting your text editor to have the TAB key do indentation of four spaces.
For VIM, for example, the config file .vimrc should have these three lines:

    set expandtab
    set shiftwidth=4
    set tabstop=4

VIM users should also install [Syntax Highlighting Files for Haskell](https://github.com/pbrisbin/html-template-syntax).

Emacs users should use a package manager (preferably Marmalade) to install [Haskell Mode](https://github.com/haskell/haskell-mode).


Development guidelines and notes
================================

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 be built with simple HTML/CSS along with Yesod/Haskell server-side functions.
JavaScript may then added for enhancement. 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/).

We have a separate wiki and discussion page on the site for discussing specific [web-design issues](https://snowdrift.coop/p/snowdrift/w/site-design).


Working on the code
===================

Cloning the repository
----------------------

1. Have or make an account on Gitorious or GitHub
2. Clone (Gitorious' term) / Fork (GitHub's term) 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"
    * 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

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.

To pull updates from our main code, use

    git pull <EMAIL>:snowdrift/snowdrift.git


Building
--------

Install ghc, cabal, and postgresql, however you do that on your system.

On Debian-based GNU/Linux distros, that's:

    sudo apt-get install ghc cabal-install haskell-platform postgresql zlib1g-dev libpq-dev happy alex

(There are a few non-Haskell libraries that some dependencies which you may
need to install, presumably in your system's package manager as well.
I don't have the list at hand, but they can be picked out of the error
messages when the below fails for want of them - if you make a list,
please update this and send a pull request!)

   *note: there have been some errors reported with older versions of ghc and the haskell-platform* At this time, we are using GHC 7.6.3 and Haskell Platform 2013.2.0.0 — both are included in the latest Ubuntu, and there are [instructions for building updated GHC on older Ubuntu-based systems](https://gist.github.com/Dexyne/5791465). We tested this with Ubuntu 12.04 LTS and it should work on derivatives as well (such as the fully-FLO Trisquel 6). These instructions or similar should work for other systems as well, but see <http://www.haskell.org/platform/> for more general info.

Update cabal's package list:

    cabal update

Add ~/.cabal/bin to your PATH; for bash, run the following command
(also add it to your .bashrc (or equivalent) file so it will run automatically in the future):

    export PATH=~/.cabal/bin:$PATH

Update cabal so you can use the new [sandbox](http://coldwa.st/e/blog/2013-08-20-Cabal-sandbox.html) feature in cabal 1.18+:

    cabal install Cabal cabal-install

**change to your snowdrift directory (if you're not already working there).**

For isolation in case you have multiple snowdrift checkouts or other Haskell projects, initiate a cabal sandbox:

    cabal sandbox init

Next, add your sandboxed binaries to your PATH: (For the future, you may also wish to add this to your .bashrc or equivalent.)

*Replace "~/snowdrift/" in the command below with your correct directory.*
GitHub clones are normally just "snowdrift" but Gitorious clones are "*username*-snowdrift".
It is also possible to place the directory wherever you like with whatever name.
{'fraction_non_alphanumeric': 0.08926806772514659, 'fraction_numerical': 0.0052704394228868835, 'mean_word_length': 3.946236559139785, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 24, 'lorem ipsum': 0, 'www.': 8, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 16, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6656327', 'n_tokens_mistral': 4272, 'n_tokens_neox': 3964, 'n_words': 1978}