Contributing to Pidge

1. Tell Us Your Plans
Before you start, please ensure that your plans are listed under a bug report or blueprint, so that people know what you're doing. You may also discover that somebody has suggested such a thing before, or even made some progress.

Be as specific as you can with your ideas: exactly what will the finished product do. Make sure somebody else will be able to understand any decisions you've made about implementation.

2. Wait for and Encourage Feedback
After putting your ideas out there about how to do the implementation / fix by submitting a blueprint / bug report, give others a few days to contribute ideas that might well save you time or give you new ideas.

If you're keen to do *something* now and don't want to wait a few days for feedback, try working on something else in the meantime. And if you know of people who would be particularly relevant for ideas, use the launchpad feature to ask them to review the proposal.

Please remember that this project is a collaborative effort: your code will be of much higher quality if you work on a feature with someone else, or several others. At the very least, make sure somebody will review your code.

3. Get Current Code
If you're starting work on a feature, pull from the trunk branch and create a new branch with a name in this format:
bugfix+bugname / feature+featurename

If others have started work on this already [please do check!], then pull from their branch [which should be named accordingly].

4. Check it Works
Check you can get the code you've just downloaded to work as expected. Run the test suite. Try it out in a browser.

5. Do
a. Start With Tests
Test-driven development will save you [and everybody else] time, hassle and the utter shame of the massive fail that you hadn't noticed.

So, for the first discrete 'thing' you want your code to do [make it as simple as you can], write a unit test that will fail. Check it fails. Then write the real code...

b. Write Some Code
Write code until your unittest passes.

Then refactor and follow standards - it's hard to break them when you're writing in Python. But, don't do anything silly like quoting HTML in your Python code. If in doubt, ask.

c. Commit
Check that your test passes again, and then commit. Not only does this enable you to step backwards, but other people can see how it was put together, rather than one huge block of code they can't penetrate.

Then pick another microfeature to write code for, and go back to 'a'.

6. Push to Launchpad
When you've got the code in a reasonable state [i.e. without major fails], push your branch's code to launchpad. People can then see what's going on, review your code, offer feedback, and use your current work as a starting point for helping to complete the work.

And make sure you update the bug's / blueprint's status and whiteboard so that people can tell at a glance what's current, and how things have happened over time.

7. Take Breaks, and Work on Several Things at Once
Please keep yourself fresh and in charge - if it's not working, take some time off. Human brains sometimes come up with ingenious solutions whilst you're relaxed and thinking about something totally different.

And work on more than one thing at once - if one feature isn't presenting clear answers, have a bash at completing something else.

8. User Testing
Try it out on some real people who have not been involved in the coding [and preferably nobody who is developing the project]. See how they use it, if it works, etc etc.

Use the feedback to tweak, adapt etc.

9. Rebase your Code to the current Trunk Level
Whilst you've been developing your feature, the trunk code will likely have been updated. Merge trunk into your branch, and check it all works.

10. Ask for a Merge
When it does what it should, robustly, with a proper test suite, and the current trunk code, request a merge with trunk.

You'll probably be given feedback and asked to fix something, but soon enough you'll be awarded a successful merge, and your code will be part of the project. Do not pass go, but DO claim your free official Pidge T-Shirt if you've not had one already.