code contributing process

[Josh Thompson <jo...@ncsu.edu>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Here are my initial thoughts on a process for code contributions (I use "code 
contributions" to distinguish from testing/bug report/feature request type 
feedback).

Everything but very minor bugs should have a Jira issue created for them.  
Before starting on an issue, email the dev list stating that you starting on 
the issue and either state your plan for working (or just ask if anyone 
already has a plan).  Also, make sure to ask for feedback on your plans.  I'm 
not sure how to handle strong disagreements on how an issue should be 
handled.

Issues probably shouldn't be worked on unless they are assigned to a version - 
either as a bug fix for an already released version or as development on a 
new version.  So, if you want to work on an issue not assigned to a version, 
ask about what version it should be added to.  If you run across a very minor  
bug, I think it is ok to fix it without having a Jira issue created for it.

To start with, we'll add all the issue's we have on our (NCSU) roadmap to Jira 
and assign them to versions we've determined (at least as much as we've 
assigned - there are many features we haven't assigned to versions yet).  
After all of that is entered, we'll start a discussion about how the issues 
have been assigned to see if people agree with how they've been split up and 
adjust things accordingly.

After that initial step, as new issues get created and versions get released, 
anyone on the list can suggest (via an email to the list) some issues that 
could make up a new version.  That list of issues can be vetted on the dev 
list to come up with a new version.  As development progresses, the set of 
issues in the version can change accordingly.



So, share your thoughts on how you think this process should go.  If you are 
subscribed to this list with any intention of ever contributing, you should 
at least say something - even if its just stating you agree with what someone 
else said (just make it clear what you are agreeing with).

Once we have this process vetted, we need to create a wiki page containing the 
process for reference to us and future members.

Also, please bear with us in trying to migrate our existing development 
processes to ASF.  There are three of us that have been developing this full 
time (well, between meetings and administering our installation of it).  Some 
of that process is going to be along the lines of "this is what we had 
planned - what do you think?".  Unfortunately, we can't completely stop 
development until all of the community driven processes are created.  We'll 
try to switch to them as fast as possible, but we do have a production 
environment to keep moving along (and the beginning of a semester demanding 
some features/fixes to happen ASAP).

Josh
- -- 
- -------------------------------
Josh Thompson
Systems Programmer
Virtual Computing Lab (VCL)
North Carolina State University

Josh_Thompson@ncsu.edu
919-515-5323

my GPG/PGP key can be found at pgp.mit.edu
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)

iD4DBQFJY5WBV/LQcNdtPQMRApKlAJdUb9hydeYVRWlWYmqoklquPiEaAJ443orJ
xo8iBAJ67HMpe2N3tiTRtA==
=0x3q
-----END PGP SIGNATURE-----

Re: code contributing process

[Andy Kurth <an...@ncsu.edu>]

Thanks Josh, this is a good start.  Some simple guidelines to direct the 
community's efforts will be very helpful.  Imposing and adhering to guidelines 
can be tedious, but in some ways makes it easier by relieving developers from 
having to make judgment calls.

I made some comments inline with Josh's message below and also would like to 
pose the following questions:

What should the relationship between Jira issues and commits be?  I think we 
agree that every commit should be tied to an issue but can a single commit be 
tied to multiple issues if they are related or if it's most efficient to tackle 
2 problems at the same time?

When committing, should there be a standard format for the commit message?  Alan 
mentioned placing the Jira issue number in the comment so Fisheye can interact. 
    For those experienced with these products, is there a format that works best 
or does it not matter?

Other thoughts are inline...

Josh Thompson wrote:

> Everything but very minor bugs should have a Jira issue created for them.  
> Before starting on an issue, email the dev list stating that you starting on 
> the issue and either state your plan for working (or just ask if anyone 
> already has a plan).  Also, make sure to ask for feedback on your plans.  

I agree with the points about posting to the dev list.

I would go a bit farther in defining what should have a Jira issue tied to it 
and would propose anything that changes how the software functions.  There would 
be very few examples of changes which wouldn't require an associated Jira issue, 
examples being adding/modifying comments or correcting typos.


> I'm not sure how to handle strong disagreements on how an issue should be 
> handled.
> 

Strong disagreements are probably inevitable.  As long as the community 
guidelines and development practices are clearly communicated and every 
participant shows respect for each other, I'm hoping disagreements shouldn't be 
too difficult to resolve.


> Issues probably shouldn't be worked on unless they are assigned to a version - 
> either as a bug fix for an already released version or as development on a 
> new version.  So, if you want to work on an issue not assigned to a version, 
> ask about what version it should be added to.  If you run across a very minor  
> bug, I think it is ok to fix it without having a Jira issue created for it.

I think every bug you find should be documented somewhere in Jira, whether it be 
in its own Jira issue or noted in another related issue.

This raises the question: how granular should Jira issues should be?  If I’m 
working on an issue and notice an unrelated trivial improvement that can be made 
or find a minor bug, should I create a separate issue?  Would it be acceptable 
to note the minor bug or improvement in the issue I was working on?


> To start with, we'll add all the issue's we have on our (NCSU) roadmap to Jira 
> and assign them to versions we've determined (at least as much as we've 
> assigned - there are many features we haven't assigned to versions yet).  
> After all of that is entered, we'll start a discussion about how the issues 
> have been assigned to see if people agree with how they've been split up and 
> adjust things accordingly.
> 
> After that initial step, as new issues get created and versions get released, 
> anyone on the list can suggest (via an email to the list) some issues that 
> could make up a new version.  That list of issues can be vetted on the dev 
> list to come up with a new version.  As development progresses, the set of 
> issues in the version can change accordingly.
> 

Sounds like a good plan to me.  I think there needs to be a pretty organized way 
of assigning Jira issues to versions.  Until now, the NC State team decided what 
features to focus on for each version by considering the needs of the campus and 
our partners.  There will hopefully be many more stakeholders in the future so 
version assignment of new features should certainly be discussed and decided on 
the dev list.


> So, share your thoughts on how you think this process should go.  If you are 
> subscribed to this list with any intention of ever contributing, you should 
> at least say something - even if its just stating you agree with what someone 
> else said (just make it clear what you are agreeing with).
> 
> Once we have this process vetted, we need to create a wiki page containing the 
> process for reference to us and future members.

I have started a page on Confluence site entitled "Developer Guidelines".  It's 
currently just a placeholder and can be renamed if necessary as things are 
discussed.  I'll try to add to it as things get decided.  Please do the same.


> Also, please bear with us in trying to migrate our existing development 
> processes to ASF.  There are three of us that have been developing this full 
> time (well, between meetings and administering our installation of it).  Some 
> of that process is going to be along the lines of "this is what we had 
> planned - what do you think?".  Unfortunately, we can't completely stop 
> development until all of the community driven processes are created.  We'll 
> try to switch to them as fast as possible, but we do have a production 
> environment to keep moving along (and the beginning of a semester demanding 
> some features/fixes to happen ASAP).

I completely agree.  I also agree with the points made by Alan and Kevan in 
other messages about the importance of communication and a community mindset. 
I'm very eager to help build a community with the help of the ASF.  Everyone 
needs to understand that a transition period is required.  If anyone disagrees 
with the way something is being done or knows of a better method, please bring 
it up on the list in a constructive way.  Any wisdom the community can provide 
which will help this project is greatly appreciated.

Regards,
Andy