(→Making changes: how to make changes)
(→Submitting a pull request: info on submitting pull requests)
Revision as of 15:56, 21 August 2012
This page is under construction -- please help!
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 (
#diagramson 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.
2 Getting the sources
All the core diagrams code can be found in the diagrams organization on github.
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:
- Take a look at the issue trackers for repositories in the diagrams organization on github, especially those for the diagrams-core, diagrams-lib, diagrams-contrib, and diagrams-doc repositories.
- See the projects page for a list of ongoing projects to get involved with, or new projects to start.
- Don't hesitate to ask for ideas on the mailing list or IRC channel.
4 Best practices
As a running example, let's suppose you want to add a function to the
Diagrams.TwoD.Shapes module (from the diagrams-lib package) to draw a diamond shape.
4.1 Getting the code
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
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.)
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---though you will have to build it from source, and it is only known to work on Linux systems. Good suggestions of similar tools for Windows or Mac are welcome.
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.
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
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.
4.5 Old text
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.
- use topic branches
- encourage submitting update to documentation
- link to coding style document
TODO: expand/clean up the below
But the short version is that a pull request is not for a set of 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.
- Make some commits in your branch.
- 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 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 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.