Skip to content

Commit 373f8c1

Browse files
author
Tim Watson
committed
minimise wiki content where possible
1 parent a96e476 commit 373f8c1

8 files changed

+258
-176
lines changed

‎documentation.md

+5
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,11 @@ growing number of features for
2222
* working with several network transport implementations (and more in the pipeline)
2323
* supporting *static* values (required for remote communication)
2424

25+
There is a recent
26+
[presentation](http://sneezy.cs.nott.ac.uk/fun/2012-02/coutts-2012-02-28.pdf)
27+
on Cloud Haskell and this reimplementation, which is worth reading in conjunction
28+
with the documentation and wiki pages on this website..
29+
2530
Cloud Haskell comprises the following components, some of which are complete,
2631
others experimental.
2732

‎wiki/contributing.md

+112-2
Original file line numberDiff line numberDiff line change
@@ -102,5 +102,115 @@ github issue.
102102

103103
### General Style
104104

105-
Please carefully review the [Style Guide](/wiki/style.html) and stick to the
106-
conventions set out there as best you can.
105+
A lot of this **is** taken from the GHC Coding Style entry [here](http://hackage.haskell.org/trac/ghc/wiki/Commentary/CodingStyle).
106+
In particular, please follow **all** the advice on that wiki page when it comes
107+
to including comments in your code.
108+
109+
I am also grateful to @tibbe for his
110+
[haskell-style-guide](https://github.com/tibbe/haskell-style-guide), from
111+
which some of these rules have been taken.
112+
113+
As a general rule, stick to the same coding style as is already used in the file
114+
you're editing. It **is** much better to write code that is transparent than to
115+
write code that is short. Please don't assume everyone is a minimalist - self
116+
explanatory code is **much** better in the long term than pithy one-liners.
117+
Having said that, we *do* like reusing abstractions where doing so adds to the
118+
clarity of the code as well as minimising repetitious boilerplate.
119+
120+
### Formatting
121+
122+
#### Line Length
123+
124+
Maximum line length is *80 characters*. This might seem antiquated
125+
to you, but some of us do things like github pull-request code
126+
reviews on our mobile devices on the way to work, and long lines
127+
make this horrendously difficult. Besides which, some of us are
128+
also emacs users and have this rule set up for all of our source
129+
code editing modes.
130+
131+
#### Indentation
132+
133+
Tabs are illegal. Use **only** spaces for indenting.
134+
Indentation is usually 2 spaces, with 4 spaces used in some places.
135+
We're pretty chilled about this, but try to remain consistent.
136+
137+
#### Blank Lines
138+
139+
One blank line between top-level definitions. No blank lines between
140+
type signatures and function definitions. Add one blank line between
141+
functions in a type class instance declaration if the functions bodies
142+
are large. As always, use your judgement.
143+
144+
#### Whitespace
145+
146+
Do not introduce trailing whitespace. If you find trailing whitespace,
147+
feel free to strip it out - in a separate commit of course!
148+
149+
Surround binary operators with a single space on either side. Use
150+
your better judgement for the insertion of spaces around arithmetic
151+
operators but always be consistent about whitespace on either side of
152+
a binary operator.
153+
154+
#### Alignment
155+
156+
When it comes to alignment, there's probably a mix of things in the codebase
157+
right now. Personally, I tend not to align import statements as these change
158+
quite frequently and it is pain keeping the indentation consistent.
159+
160+
The one exception to this is probably imports/exports, which we *are* a
161+
bit finicky about:
162+
163+
{% highlight haskell %}
164+
import qualified Foo.Bar.Baz as Bz
165+
import Data.Binary
166+
( Binary (..),
167+
, getWord8
168+
, putWord8
169+
)
170+
import Data.Blah
171+
import Data.Boom (Typeable)
172+
{% endhighlight %}
173+
174+
Personally I don't care *that much* about alignment for other things,
175+
but as always, try to follow the convention in the file you're editing
176+
and don't change things just for the sake of it.
177+
178+
### Comments
179+
180+
#### Punctuation
181+
182+
Write proper sentences; start with a capital letter and use proper
183+
punctuation.
184+
185+
#### Top-Level Definitions
186+
187+
Comment every top level function (particularly exported functions),
188+
and provide a type signature; use Haddock syntax in the comments.
189+
Comment every exported data type. Function example:
190+
191+
{% highlight haskell %}
192+
-- | Send a message on a socket. The socket must be in a connected
193+
-- state. Returns the number of bytes sent. Applications are
194+
-- responsible for ensuring that all data has been sent.
195+
send :: Socket -- ^ Connected socket
196+
-> ByteString -- ^ Data to send
197+
-> IO Int -- ^ Bytes sent
198+
{% endhighlight %}
199+
200+
For functions the documentation should give enough information to
201+
apply the function without looking at the function's definition.
202+
203+
### Naming
204+
205+
Use `mixedCase` when naming functions and `CamelCase` when naming data
206+
types.
207+
208+
For readability reasons, don't capitalize all letters when using an
209+
abbreviation. For example, write `HttpServer` instead of
210+
`HTTPServer`. Exception: Two letter abbreviations, e.g. `IO`.
211+
212+
#### Modules
213+
214+
Use singular when naming modules e.g. use `Data.Map` and
215+
`Data.ByteString.Internal` instead of `Data.Maps` and
216+
`Data.ByteString.Internals`.

‎wiki/faq.md

+19-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
layout: wiki
3-
title: FAQ
3+
title: FAQ/Getting Help
44
wiki: FAQ
55
---
66

@@ -31,3 +31,21 @@ project of this size. Cloud Haskell consists of no less than **13** individual
3131
projects at this time, and that's not to mention some of the experimental ones
3232
that have been developed by community members and *might* end up being absorbed
3333
by the team.
34+
35+
### Help
36+
37+
If the documentation doesn't answer your question, queries about Cloud Haskell
38+
can be directed to the Parallel Haskell Mailing List
39+
([email protected]), which is pretty active. If you think
40+
you've found a bug, or would like to request a new feature, please visit the
41+
[Jira Issue Tracker](https://cloud-haskell.atlassian.net) and submit a bug.
42+
You **will** need to register with your email address to create new issues,
43+
though you can freely browse the existing tickets without doing so.
44+
45+
46+
### Getting Involved
47+
48+
If you're interested in hacking Cloud Haskell then please read the
49+
[Contributing](/wiki/contributing.html) wiki page. Additional help can be obtained through the
50+
[Developers Forum/Mailing List](https://groups.google.com/forum/?fromgroups=#!forum/cloud-haskell-developers)
51+
or Parallel Haskell mailing list.

‎wiki/help.md

-23
This file was deleted.

‎wiki/maintainers.md

+83-4
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,54 @@ wiki: Maintainers
66

77
### Maintainers
88

9-
This guide is specifically for maintainers, and outlines the
10-
development process and in particular, the branching strategy.
9+
This part of the guide is specifically for maintainers, and
10+
outlines the development process and in particular, the branching
11+
strategy. We also point out Cloud Haskell's various bits of
12+
infrastructure as they stand at the moment.
1113

12-
#### Branching/Merging Policy
14+
----
15+
#### Releases
16+
17+
All releases are published to [hackage][3]. At some point we may start to
18+
make *nightly builds* available on this website.
19+
20+
----
21+
22+
#### Community
23+
24+
We keep in touch through the [parallel-haskell google group][7],
25+
and once you've joined the group, by posting to the mailing list address:
26+
[email protected]. This is a group for **all** things related
27+
to concurrent and parallel Haskell. There is also a maintainer/developer
28+
centric [cloud-haskell-developers google group][9], which is more for
29+
in-depth questions about contributing to or maintaining Cloud Haskell.
30+
31+
You might also find some of us hanging out at #haskell-distributed on
32+
freenode from time to time.
33+
34+
We have a twitter account! [@CloudHaskell](https://twitter.com/CloudHaskell)
35+
will be used to make announcements (of new releases, etc) on a regular basis.
36+
37+
----
38+
39+
### Bug/Issue Tracking and Continuous Integration
40+
41+
Our bug tracker is a hosted/on-demand Jira, for which a free open source
42+
project license was kindly donated by [Atlassian][6]. You can browse all
43+
issues without logging in, however to report new issues/bugs you will
44+
need to provide an email address and create an account.
45+
46+
If you have any difficulties doing so, please post an email to the
47+
[parallel-haskell mailing list][7] at [email protected].
48+
49+
We currently use [travis-ci][11] for continuous integration. We do however,
50+
have an open source license for Atlassian Bamboo, which we will be migrating
51+
to over time - this process is quite involved so we don't have a picture of
52+
the timescales yet.
53+
54+
----
55+
56+
### Branching/Merging Policy
1357

1458
The master branch is the **stable** branch, and should always be
1559
in a *releasable* state. This means that on the whole, only small
@@ -37,6 +81,25 @@ you're planning on doing lots of squashing, then work in a branch
3781
and don't commit directly to development - and **definitely** not to
3882
master.
3983

84+
#### Committing without triggering CI builds
85+
86+
Whilst we're on travis-ci, you can do this by putting the text
87+
`[ci skip]` anywhere in the commit message. Please, please
88+
**do not** put this on the first line of the commit message.
89+
90+
Once we migrate to Bamboo, this may change.
91+
92+
#### Changing Jira bugs/issues via commit messages
93+
94+
You can make complex changes to one or more Jira issues with a single
95+
commit message. As with skipping CI builds, please **do not** put this
96+
messy text into the first line of your commit messages.
97+
98+
Details of the format/syntax required to do this can be found on
99+
[this Jira documentation page](https://confluence.atlassian.com/display/AOD/Processing+JIRA+issues+with+commit+messages)
100+
101+
----
102+
40103
#### Follow the <a href="/wiki/contributing.html">Contributing guidelines</a>
41104

42105
What's good for the goose...
@@ -45,7 +108,11 @@ What's good for the goose...
45108

46109
Currently this is a manual process. If you don't sed/awk out the
47110
reference/link paths, it'll be a mess. We will add a script to
48-
handle this some time soon.
111+
handle this some time soon. I tend to only update the static
112+
documentation for d-p and d-p-platform, at least until the process has
113+
been automated. I also do this *only* for mainline branches (i.e.,
114+
for development and master), although again, automation could solve
115+
a lot of issues there.
49116

50117
There is also an open ticket to set up nightly builds, which will
51118
update the HEAD haddocks (on the website) and produce an 'sdist'
@@ -94,3 +161,15 @@ feature that makes this very easy.
94161

95162
After that, it's time to tweet about the release, post to the parallel-haskell
96163
mailing list, blog etc. Spread the word.
164+
165+
[1]: https://github.com/haskell-distributed
166+
[2]: https://github.com/haskell-distributed/haskell-distributed.github.com
167+
[3]: http://hackage.haskell.org
168+
[4]: http://git-scm.com/book/en/Git-Basics-Tagging
169+
[5]: https://cloud-haskell.atlassian.net/secure/Dashboard.jspa
170+
[6]: http://atlassian.com/
171+
[7]: https://groups.google.com/forum/?fromgroups=#!forum/parallel-haskell
172+
[8]: /team.html
173+
[9]: https://groups.google.com/forum/?fromgroups#!forum/cloud-haskell-developers
174+
[10]: http://en.wikipedia.org/wiki/Greenwich_Mean_Time
175+
[11]: https://travis-ci.org/

‎wiki/otherprotocols.md

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
layout: wiki
3+
title: Applications and other protocols
4+
wiki: Applications
5+
---
6+
7+
### Applications
8+
9+
If you are using `Network.Transport` in your application, or if you are writing (or interested in writing) `Network.Transport` support for another protocol, please add a brief description to this page so that we can coordinate the efforts.
10+
11+
### HdpH
12+
13+
**H**askell **D**istributed **P**arallel **H**askell is a shallowly embedded parallel extension of Haskell that supports high-level semi-explicit parallelism. HdpH has a distributed memory model, that manages computations on more than one multicore node. In addition _high-level semi-explicit parallelism_ is supported by providing `spark` for implicit task placement, alleviating the job of dynamic load management to HdpH. Explicit task placement is supported with the `pushTo` primitive. Lastly, HdpH supports the node <-> node transfer of polymorphic closures. This enables the definition of both evaluation strategies and algorithmic skeletons by using a small set of polymorphic coordination primitives.
14+
15+
Efforts to adopt these new transport abstractions into HdpH are a work-in-progress, and early testing is showing positive performance results. When this work is complete, the upstream HdpH repository will be updated.
16+
17+
* Paper presented at IFL 2011 [Implementing a High-level Distributed-Memory Parallel Haskell in Haskell](http://www.macs.hw.ac.uk/~pm175/papers/Maier_Trinder_IFL2011_XT.pdf)
18+
* HdpH source code [HdpH GitHub repository](https://github.com/PatrickMaier/HdpH)
19+
20+
# Protocol Implementations
21+
22+
## CCI
23+
24+
The [CCI](http://cci-forum.com) project is an open-source communication interface that aims to
25+
provide a simple and portable API, high performance, scalability for
26+
the largest deployments, and robustness in the presence of faults. It
27+
is developed and maintained by a partnership of research, academic,
28+
and industry members.
29+
30+
[Parallel Scientific](http://www.parsci.com) is contributing with CCI development and promoting
31+
its adoption as a portable API. We have developed [Haskell bindings](https://www.assembla.com/code/cci-haskell/git/nodes) for
32+
the CCI alpha implementation, and are keen to have a CCI backend for
33+
Cloud Haskell as resources allow.

‎wiki/reliability.md

+6-26
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ title: Fault Tolerance
44
wiki: reliability
55
---
66

7-
### reliability
7+
### Reliability
88

99
We do not consider the presence of side effects a barrier to fault tolerance
1010
and automated process restarts. We **do** recognise that it's easier to
@@ -20,8 +20,8 @@ how to initialise and/or re-initialise a process that has been previously
2020
terminated.
2121

2222
When it comes to failure recovery, we defer to Erlang's approach for handling
23-
process failures in a generic manner, by drawing on the [OTP][13] concept of
24-
[supervision trees][15]. Erlang's [supervisor module][16] implements a process
23+
process failures in a generic manner, by drawing on the [OTP][1] concept of
24+
[supervision trees][2]. Erlang's [supervisor module][3] implements a process
2525
which supervises other processes called child processes. The supervisor process
2626
is responsible for starting, stopping, monitoring and even restarting its
2727
child processes. A supervisors *children* can be either worker processes or
@@ -30,26 +30,6 @@ supervision trees in Erlang parlance).
3030

3131
The supervision APIs are a work in progress.
3232

33-
[1]: http://www.haskell.org/haskellwiki/Cloud_Haskell
34-
[2]: https://github.com/haskell-distributed/distributed-process
35-
[3]: https://github.com/haskell-distributed/distributed-process-platform
36-
[4]: http://hackage.haskell.org/package/distributed-static
37-
[5]: http://hackage.haskell.org/package/rank1dynamic
38-
[6]: http://hackage.haskell.org/packages/network-transport
39-
[7]: http://hackage.haskell.org/packages/network-transport-tcp
40-
[8]: https://github.com/haskell-distributed/distributed-process/network-transport-inmemory
41-
[9]: https://github.com/haskell-distributed/distributed-process/network-transport-composed
42-
[10]: http://hackage.haskell.org/package/distributed-process-simplelocalnet
43-
[11]: http://hackage.haskell.org/package/distributed-process-azure
44-
[12]: http://research.microsoft.com/en-us/um/people/simonpj/papers/parallel/remote.pdf
45-
[13]: http://en.wikipedia.org/wiki/Open_Telecom_Platform
46-
[14]: http://hackage.haskell.org/packages/remote
47-
[15]: http://www.erlang.org/doc/design_principles/sup_princ.html
48-
[16]: http://www.erlang.org/doc/man/supervisor.html
49-
[17]: /static/doc/distributed-process-platform/Control-Distributed-Process-Platform-Async.html
50-
[18]: https://github.com/haskell-distributed/distributed-process-platform
51-
[19]: http://hackage.haskell.org/package/async
52-
[20]: /wiki/networktransport.html
53-
[21]: /static/doc/distributed-process-platform/Control-Distributed-Process-Platform-ManagedProcess.html
54-
[22]: /tutorials/3.managedprocess.html
55-
33+
[1]: http://en.wikipedia.org/wiki/Open_Telecom_Platform
34+
[2]: http://www.erlang.org/doc/design_principles/sup_princ.html
35+
[3]: http://www.erlang.org/doc/man/supervisor.html

0 commit comments

Comments
 (0)