This document lists out some of the do’s, don'ts, and hows of getting code into Graphine.

Why Your Code Didn’t Get In

Really, we aren’t nazis. We want Graphine to have as many features as it can without getting
bloated beyond recognition. We know that there are tons of different ways to use a graph and
that even if your submission makes no sense to us, it might to somebody else. And we know
that to you, your code is a snowflake-like thing of unique and precious beauty. Trust me, we've
been there. But sometimes we just can’t accept it. Mostly, that’s going to be because of one of
the following things:

1. We don’t see the point- either there is an existing tool in Graphine that does much the same thing,
   or we don’t think there’s enough demand for that feature for it to make sense in the core of Graphine,
   or we’re just too stupid to figure out why you want that function. Providing lots of well-documented
   examples with your submission really helps us out here, and that decreases the chances that we’ll
   randomly bin your code.
   
2. Your code isn’t clean- we aren’t programming gods, but we do know unreadable code when we see it.
   Please try to follow the Python style guidelines, comment thoroughly and well, and don’t sacrifice clarity
   for minor increases in performance. See below.
   
3. Your code is inefficient- there may be much better ways of doing what you’re trying to do than how you’re
   trying to do it. As a general rule, we won’t accept anything that strays above O(N³), and even that is
   somewhat questionable. We absolutely will not accept anything in NP.
   
4. It would add a dependency- We aren’t doing that. One of our major goals is to stay pure Python.
   
5. It would break existing code- In small doses, this may be tolerable, but most of the time its avoidable.
   If you break a piece of code to turn O(N²) into O(1), you still have a solid chance at getting in-
   but you’re going to have to either 1) submit a patch to fix the other code too, 2) convince somebody else to do
   it, or 3) wait until the next major release.
   
6. It doesn’t include tests- we don’t accept any code without tests attached. That means that for new features,
   exercise your code fully and thoroughly- it isn’t unusual for it to take 3 lines of code to test 1. For bugfixes,
   please include a test that exercises the old bug to make sure we don’t get bushwhacked by it again. For
   pieces of code that are difficult to test, but which, in your mind, desperately crave resolution, send us an email.

What We Want in Code

We love new code- the way it smells, the way it squeaks when you turn around too quickly, the shiny new
superpowers it gives us, it’s just one of the joys of our lives. So, please, fill our lives with happiness- contribute
code that:

1. Makes Graphine easier to read- I love my code, but dear Lord some of it is ugly. Hit it with a stick if you must,
   but please, please, please, make it pretty. We love beautiful code.
   
2. Makes Graphine faster- here’s something that’s not going to surprise the graph theorists out there: I'm not a graph
   theorist. There are ways of doing things to graphs that I couldn’t spell if I had a degree in Latin and an urge to
   conjugate. Some of them are bound to be better than my way, and speed is darned important in some graph
   applications. Please- let us know where we can improve.
   
3. Makes Graphine easier to use- graph theory is a formidable, intimidating obstacle in front of what is otherwise a very
   accessible, intuitive data structure. We've tried to balance formal correctness and usability and strayed, I think, not
   too far from the mark- but there is always room for improvement. If you think you see a rough spot, take a file to it,
   and we’ll appreciate your efforts.

How to Submit Code

Please post on the google group, including information on
what you've written, why you've written it, and who should care. If there’s a favorable response, please submit your
patches as just that. For those of you who are unfamiliar with git, you can format your changes very simply by doing
the following:

user@host:~$ git clone http://git.gitorious.org/graphine/mainline.git graphine
user@host:~$ cd graphine  
user@host:~$ git checkout -b <featurename>  
... make changes ...  
user@host:~$ git add .  
user@host:~$ git commit -a -m "your message here"  
user@host:~$ git-format-patch master

This will produce a patch for every commit you've made. Please try to keep patchsets small and easy to apply.

A Word on Commit Messages

Every commit message should include a one-word, all-caps description as the first word. These help us to keep track
of who should pay attention to what as they roll into the logs. The ones we’ll pay attention to are:

• RELEASE
  
• FEATURE
  
• BUGFIX
  
• DOCUMENTATION

The ones we don’t pay attention to are:

• MINOR
  
• MISSPELL

After that, what you put in your commit message should be short and sweet, one line if possible and two if not.
Trust me, it saves us all lots of headaches.

Code Maintenance

We don’t hold you responsible for maintaining the code you submit. We'd like it if you did- but we won’t make you sign some
kind of agreement or anything to do so.

Credit

Primary authors of a module get a mention in the docstrings. Bugfix authors get a mention in the “additional thanks to” section
below the copyright notice.