Personal tools

Diagrams/Contributing

From HaskellWiki

< Diagrams(Difference between revisions)
Jump to: navigation, search
m (Best practices: a few more notes)
(Best practices: dump some text, still needs cleanup)
Line 29: Line 29:
 
* encourage submitting update to documentation
 
* encourage submitting update to documentation
 
* link to coding style document
 
* 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.

Revision as of 14:20, 2 August 2012

This page is under construction -- please help!

Contents

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.

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, we recommend XXX. Also, see the walkthrough example below.

3 Choosing a project

  • bug tracker
  • projects page
  • ask on mailing list or IRC

4 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.

  • 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.