Personal tools

Diagrams/Contributing

From HaskellWiki

< Diagrams(Difference between revisions)
Jump to: navigation, search
(Walkthrough: #!/bin/sh)
(add description of mr for multiple repos)
 
(19 intermediate revisions by 2 users not shown)
Line 1: Line 1:
This page is under construction -- please help!
 
 
 
== Getting involved ==
 
== Getting involved ==
   
Line 14: Line 12:
   
 
If you don't already know how to work with repositories hosted on
 
If you don't already know how to work with repositories hosted on
github, we recommend XXX. Also, see the walkthrough example below.
+
github, take a look at some introductory material like [http://git-scm.com/book this book about git] and [http://learn.github.com/p/intro.html this github tutorial] and this [http://try.github.io/levels/1/challenges/1 interactive tutorial-game-thingy]. The [http://defunkt.io/hub/ hub utility] is an optional but recommended tool for simplifying common tasks involving github.
   
 
== Choosing a project ==
 
== Choosing a project ==
   
* bug tracker
+
If you would like to begin contributing to the diagrams project but are not sure where to start, here are a few resources that may be helpful:
* projects page
+
* ask on mailing list or IRC
+
* The [https://trello.com/b/pL6YdKgz/diagrams Trello board for diagrams] has lots of ideas for projects, todos, and gives a snapshot of what various people are working on.
  +
* Take a look at the issue trackers for repositories in the [http://github.com/diagrams diagrams organization on github], especially those for the [http://github.com/diagrams/diagrams-core/issues?state=open diagrams-core], [http://github.com/diagrams/diagrams-lib/issues?state=open diagrams-lib], [http://github.com/diagrams/diagrams-contrib/issues?state=open diagrams-contrib], and [http://github.com/diagrams/diagrams-doc/issues?state=open diagrams-doc] repositories.
  +
* See the [http://www.haskell.org/haskellwiki/Diagrams/Projects projects page] for a list of ongoing bigger projects to get involved with, or new projects to start.
  +
* Don't hesitate to ask for ideas on the mailing list or IRC channel.
   
 
== Best practices ==
 
== Best practices ==
   
XXX walk through example of checking out repo, making and committing changes, and submitting a pull request. Show how to do it manually and also using 'hub' utility.
+
=== Getting the code ===
   
* use topic branches
+
To begin, you will need a [http://github.com github] account, and to fork and clone some of the diagrams repositories. See [https://help.github.com/articles/fork-a-repo here for help on how to fork a repo]. At a minimum, you will need the following repositories:
* encourage submitting update to documentation
 
* link to coding style document
 
   
TODO: expand/clean up the below
+
* [https://github.com/diagrams/diagrams-core diagrams-core]
  +
* [https://github.com/diagrams/diagrams-lib diagrams-lib]
  +
* [https://github.com/diagrams/diagrams-contrib diagrams-contrib]
  +
* [https://github.com/diagrams/diagrams-doc diagrams-doc]
   
But the short version is that a pull request is not for a set of
+
as well as one of the following two backends:
commits, it is for a *branch*. In particular, you add new commits to
 
a pull request simply by pushing to the branch which the pull request
 
is from. So best practice when working on a new feature is
 
   
* make a new branch (a "feature" or "topic" branch). If you have push access you can make a branch directly in the main repo; otherwise, fork it and make a branch in your fork.
+
* [https://github.com/diagrams/diagrams-cairo diagrams-cairo]
* Make some commits in your branch.
+
* [https://github.com/diagrams/diagrams-svg diagrams-svg]
* Open a pull request from your branch to 'master'.
 
* If necessary, make revisions etc. by pushing additional commits to the branch. There's no need to "revise" the original commits; it's useful to have the entire history of development with comments, etc.
 
* Once your commits have been merged, you can delete the branch.
 
   
The important point is that it's usually a bad idea to open a pull
+
If you do not plan to make any modifications to the code in a certain repo, you may clone it directly instead of first forking on github and then cloning from your fork, for example
request from the 'master' branch of your fork because then you can't
 
do anything else while waiting for your changes to be merged.
 
   
Another interesting point is that there's not necessarily any reason
+
git clone https://github.com/diagrams/diagrams-core
to wait until you are "done" to open a pull request. Just make sure
 
you state that the feature is "in progess", and then you can get
 
useful early feedback as you continue to work on the feature and push
 
more commits. Of course, branches/pull requests also make for a nice
 
way to work on a new feature collaboratively.
 
   
  +
or, using [http://defunkt.io/hub/ hub], simply
   
== Walkthrough ==
+
hub clone diagrams/diagrams-core
   
Here's how you can clone all of the repositories:
+
(In fact, hub makes it easy to later convert a direct clone into your own fork if you wish, via the <code>hub fork</code> command; see the [https://github.com/defunkt/hub#readme hub documentation] for more information.)
   
#!/bin/sh
+
=== Building ===
git clone https://github.com/diagrams/docutils
+
git clone https://github.com/diagrams/dual-tree
+
It's recommended to use some sort of sandboxing tool while working on diagrams. Because diagrams consists of several separate packages, using [http://hackage.haskell.org/package/cabal-dev cabal-dev] can be something of a pain. Instead, we recommend using [http://hackage.haskell.org/package/hsenv hsenv]. [http://coldwa.st/e/blog/2013-08-20-Cabal-sandbox.html cabal-sandbox] also works well, except for diagrams-doc.
git clone https://github.com/diagrams/monoid-extras
+
git clone https://github.com/diagrams/vector-space-points
+
In any case, there is an important trick for building multiple local packages at once that you should know, which works with cabal as well as cabal-dev. Instead of installing each package one at a time, simply go up to the parent directory and issue a command such as
git clone https://github.com/diagrams/diagrams-core
+
git clone https://github.com/diagrams/active
+
cabal install monoid-extras/ dual-tree/ diagrams-core/ diagrams-lib/ diagrams-cairo/ diagrams-contrib/
git clone https://github.com/diagrams/diagrams-lib
+
git clone https://github.com/diagrams/diagrams-cairo
+
The trailing slashes tell cabal to install packages from local directories, rather than trying to download packages from Hackage. In addition, it doesn't even matter in what order you list the directories; cabal will figure out the correct order based on dependencies.
git clone https://github.com/diagrams/diagrams-contrib
+
+
=== Making changes ===
# optional
+
git clone https://github.com/diagrams/diagrams-doc
+
Now that you have your cloned/forked repositories and know how to build them, go ahead and make some edits. You can see what changes you've made using the <code>git diff</code> command, stage certain changes with <code>git add</code> (try the <code>-p</code> flag!), and create a commit from staged changes with <code>git commit</code>.
  +
  +
For coding style, see Johan Tibell's [https://github.com/tibbe/haskell-style-guide/blob/master/haskell-style.md Haskell style guide].
  +
  +
You are also encouraged to update the diagrams user manual in parallel with any changes you make; see the [https://github.com/diagrams/diagrams-doc diagrams-doc repository].
  +
  +
=== Submitting a pull request ===
  +
  +
Once you have a set of commits you are happy with, push them to your forked repository on github and open a pull request. At this point your code will be reviewed by someone with push access to the repository. They may very well leave some comments; feel free to respond with comments of your own.
  +
  +
If any errors are pointed out, changes requested, etc., simply make some new commits and push them to your forked repo. There is no need to create another pull request; any newly pushed commits will be automatically added to the existing pull request.
  +
  +
=== Pull requests and topic branches ===
  +
  +
The important thing to realize about pull requests is that they do not correspond to a particular set of commits, but to a ''branch''. In particular, you add new commits to a pull request simply by pushing to the branch which the pull request is from. This has some interesting implications:
  +
  +
* If you are going to be working on multiple features/bug fixes at once---or even if you just want to be able to get started on a new feature while your previous one is still undergoing review---it is best to create a "topic branch" for each feature, rather than making all your changes on your "master" branch. You can create a new branch called <code>foo</code> with <code>git branch foo</code>; see all branches with <code>git branch</code>; and switch between branches using <code>git checkout</code>.
  +
* Once your pull request is merged, you can delete the branch, using <code>git branch -d foo</code> for the branch in your local repo, and something like <code>git push origin --delete foo</code> for a remote repo named <code>origin</code>.
  +
* Another interesting point is that there's not necessarily any reason to wait until you are "done" to open a pull request. Just make sure you state that the feature is "in progess", and then you can get useful early feedback as you continue to work on the feature and push more commits. Of course, branches/pull requests also make for a nice way to work on a new feature collaboratively.
   
Here's how you can install all of those repositories:
+
=== Keeping up to date ===
  +
It can be a bit tedious to make sure you have all the latest changes to diagrams across a dozen git repos (and some darcs). The [http://myrepos.branchable.com/ mr tool] automates this process. To setup:
  +
* checkout all the repositories with a common parent directory, as above
  +
* in each checkout, run <code>mr register</code>
   
#!/bin/sh
+
Then to pull changes, run <code>mr update</code> from the common parent directory.
cd active
 
cabal install --avoid-reinstalls --user
 
 
cd ../monoid-extras
 
cabal install --avoid-reinstalls --user
 
 
cd ../dual-tree
 
cabal install --avoid-reinstalls --user
 
 
cd ../diagrams-core
 
cabal install --avoid-reinstalls --user
 
 
cd ../diagrams-lib
 
cabal install --avoid-reinstalls --user
 
 
cd ../diagrams-cairo
 
cabal install --avoid-reinstalls --user
 
 
cd ../diagrams-contrib
 
cabal install --avoid-reinstalls --user
 

Latest revision as of 15:58, 2 June 2014

Contents

[edit] 1 Getting involved

There are two major ways to get involved in the diagrams community and find out what is going on:

  • The IRC channel (#diagrams on freenode.org) is fairly active and a good place to interact with other diagrams users and developers. (Be patient: sometimes no one is watching the channel, but if you say something or ask a question, you can be sure that someone will eventually see it and respond.)
  • The mailing list is the place to stay up-to-date with announcements, and also a good place to ask questions, especially longer or more involved ones.

[edit] 2 Getting the sources

All the core diagrams code can be found in the diagrams organization on github.

If you don't already know how to work with repositories hosted on github, take a look at some introductory material like this book about git and this github tutorial and this interactive tutorial-game-thingy. The hub utility is an optional but recommended tool for simplifying common tasks involving github.

[edit] 3 Choosing a project

If you would like to begin contributing to the diagrams project but are not sure where to start, here are a few resources that may be helpful:

[edit] 4 Best practices

[edit] 4.1 Getting the code

To begin, you will need a github account, and to fork and clone some of the diagrams repositories. See here for help on how to fork a repo. At a minimum, you will need the following repositories:

as well as one of the following two backends:

If you do not plan to make any modifications to the code in a certain repo, you may clone it directly instead of first forking on github and then cloning from your fork, for example

git clone https://github.com/diagrams/diagrams-core

or, using hub, simply

hub clone diagrams/diagrams-core

(In fact, hub makes it easy to later convert a direct clone into your own fork if you wish, via the hub fork command; see the hub documentation for more information.)

[edit] 4.2 Building

It's recommended to use some sort of sandboxing tool while working on diagrams. Because diagrams consists of several separate packages, using cabal-dev can be something of a pain. Instead, we recommend using hsenv. cabal-sandbox also works well, except for diagrams-doc.

In any case, there is an important trick for building multiple local packages at once that you should know, which works with cabal as well as cabal-dev. Instead of installing each package one at a time, simply go up to the parent directory and issue a command such as

cabal install monoid-extras/ dual-tree/ diagrams-core/ diagrams-lib/ diagrams-cairo/ diagrams-contrib/

The trailing slashes tell cabal to install packages from local directories, rather than trying to download packages from Hackage. In addition, it doesn't even matter in what order you list the directories; cabal will figure out the correct order based on dependencies.

[edit] 4.3 Making changes

Now that you have your cloned/forked repositories and know how to build them, go ahead and make some edits. You can see what changes you've made using the git diff command, stage certain changes with git add (try the -p flag!), and create a commit from staged changes with git commit.

For coding style, see Johan Tibell's Haskell style guide.

You are also encouraged to update the diagrams user manual in parallel with any changes you make; see the diagrams-doc repository.

[edit] 4.4 Submitting a pull request

Once you have a set of commits you are happy with, push them to your forked repository on github and open a pull request. At this point your code will be reviewed by someone with push access to the repository. They may very well leave some comments; feel free to respond with comments of your own.

If any errors are pointed out, changes requested, etc., simply make some new commits and push them to your forked repo. There is no need to create another pull request; any newly pushed commits will be automatically added to the existing pull request.

[edit] 4.5 Pull requests and topic branches

The important thing to realize about pull requests is that they do not correspond to a particular set of commits, but to a branch. In particular, you add new commits to a pull request simply by pushing to the branch which the pull request is from. This has some interesting implications:

  • If you are going to be working on multiple features/bug fixes at once---or even if you just want to be able to get started on a new feature while your previous one is still undergoing review---it is best to create a "topic branch" for each feature, rather than making all your changes on your "master" branch. You can create a new branch called foo with git branch foo; see all branches with git branch; and switch between branches using git checkout.
  • Once your pull request is merged, you can delete the branch, using git branch -d foo for the branch in your local repo, and something like git push origin --delete foo for a remote repo named origin.
  • Another interesting point is that there's not necessarily any reason to wait until you are "done" to open a pull request. Just make sure you state that the feature is "in progess", and then you can get useful early feedback as you continue to work on the feature and push more commits. Of course, branches/pull requests also make for a nice way to work on a new feature collaboratively.

[edit] 4.6 Keeping up to date

It can be a bit tedious to make sure you have all the latest changes to diagrams across a dozen git repos (and some darcs). The mr tool automates this process. To setup:

  • checkout all the repositories with a common parent directory, as above
  • in each checkout, run mr register

Then to pull changes, run mr update from the common parent directory.