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
does!
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
review
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!
Nick
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
