poi-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nick Burch <n...@apache.org>
Subject Advice for new and potential committers
Date Thu, 21 May 2015 19:48:57 GMT
Hi All

As we've just added a new committer, and we've a few people working away 
in the community who might be committer material in the future, I thought 
it might be helpful to write some notes and advice for newer members. This 
is a little bit of a brain-dump, so please shout if something isn't clear, 
and please reply if you have advice to add!

Unit tests - the project has fairly good unit test coverage, but it's not 
100%. When working on fixes or features, please try to leave the code with 
higher coverage than before! Unit tests can be standalone, but many rely 
on test files, these live in test-data, but ideally should be as small as 
possible, and must be given to us as an apache licensed contribution / 
generated by yourself

Formats / warnings - the project is almost 15 years old now! So we have 
code of various ages, with varying code formatting/style. If you find 
yourself needing to fix formatting or warnings while working on code, 
please try to do two commits/patches, one to bring things into line, one 
to change/fix functionality, to make code review easier. Also, while 
you're fixing those formatting/warnings, please fix anything else you spot 
while you're in there!

Ask for advice - not sure on the impact of a change, or the best way to do 
something? Ask! We've people here, including lurkers, with lots of 
experience. Post a question to the list, or on a bugzilla entry, include 
possible code if it helps, but check before making huge changes that might 
not be the best way

Backwards compatibility - if possible we maintain binary compatibility, if 
not source, and only break things if really needed. Try to keep it if you 
can, try to @deprecate rather than remove, and note breaking changes in 
the release notes if you can't avoid it

Bugzilla isn't just for bugs - we like changes to have unique ids, 
typically bugzilla entries or github pull numbers, so we have something to 
refer to. If you spot a problem, if possible, raise a bug then fix then 
close it, rather than just diving into the code and committing. New 
features are similar. A typo fix may not need one, but a huge fix probably 

Changelog - please update the changelog when you've made a change, it's in 
src/documentation/content/xdocs/status.xml - so when we recreate the site 
or do a release we've a full list of what changed. Much easier to add an 
entry after a commit, then months later...

Share intermediate work - if you're planning a big change, use a branch / 
post patches / fork on git, and share. Get feedback on your big change as 
you go, don't just code-dump an epic patch months later that's hard to 

The code is everyone's - it's great to have an area you keep an eye on, 
and it's fine to have your favourite areas! The project is almost 15 years 
old though, and committers have come and gone in that time, but the 
project and community lives on. No code is "yours", it's everyone's, so 
please maintain it as such! We do all have our pet areas we keep a close 
eye on, we just share nicely with others :)

Related areas - if you're fixing a bug, or adding a feature, or keeping an 
eye on one area of the project, do please try to find the time to branch 
just out of that area and fix some related / similar ones too!

All kinds of help matters - Doesn't matter if it's fixing a bug or adding 
a new feature, or non-code things like helping people answer their 
questions, triarging bugs, closing old bugs, testing if patches apply, 
helping write unit tests, giving examples, writing docs, anything that 
helps the community is good. Welcome and support all positive 
contributions, not just code

Have fun - we're not paid by Apache to work on this stuff, and many of us 
work on POI on our own time (even if $WORK sometimes asks/lets us work on 
it there too), so have fun! Enjoy it, come to events (eg ApacheCon 
events), learn from it, feel good about it!


To unsubscribe, e-mail: dev-unsubscribe@poi.apache.org
For additional commands, e-mail: dev-help@poi.apache.org

View raw message