In relation with prior inquiries, I did some research on past discussions and existing wiki pages, and I have come up with a revision of the old contribution policy. My proposed changes are based on findings seemingly in the majority’s best interest, so let me know if I am on the right path here.You’ll also notice that I will go slightly beyond just contribution policies, but everything still points back to the original subject.
Also, these changes would currently apply first and foremost to jME2 as with jME3 being in the early development phase there won’t be much direct community contributions happening with it anyhow. We will however adopt these same principles for the new branch if everything works out.
First off, direct changes, big and small:
- Board description change - The 'Contribution Depot' should clearly state that this is where all first-time contributors should post their contribution, and link to all relevant pages. Links appear again in sticky-form and maybe even in the form of an introduction to new contributors (wiki page).
- Changelog - I have my doubts about how well this changelog will be maintained, so I propose we go automatic => Wikipage is rewritten into some mere reference links (e.g. to the issues list and an explanation of how to separate between jME2 and 3 changes when browsing that list.
Where the changelog really comes in is when we have gone from one stable release to another, so this automatic list does not actually quite suffice, but unless there is someone stepping up to the task I see no reason why we should try and force it. Some quick examples of good changelogs include Opera and Ogre3D.
Now for the repository…
First to clear up some restrictions
Though it seems there’s been some desire to exercise greater control over which branches can be edited by who and such, googlecode simply do not provide us with the necessary permission set to restrict commits to a specific branch; I can’t even change this on a per-user basis. I know for a fact that Bazaar allows this and Mercurial’s features are very similar, but from what I have read on Google it does not seem like Mercurial (or with Google’s settings anyways) allows for it either.
SO:
“Access” to the individual branches cannot be functionally prevented because of googlecode’s administrative restrictions, but rules still apply to the different branches, and stepping on said rules will have implications.
Dev-branch and stable-branch
It has been suggested many times that we split the 2.0 branch in two, which I agree with and suggest we get done once Hudson is set up and ready. The dev branch would be the one with the nightly builds, while the stable branch might not need to be built more often than monthly, and maybe quarterly there is an actual release (I don’t want to aim at making it too often, seeing as there are no volunteers yet to help determine version milestones).
A lot of my proposals are based on the preconception that we will establish a second branch for 2.0, calling it a development branch, and merging the changes in that one with the stable one every once in a while. Remember to take that into account, and feel free to comment on this as well.
Code Commit Practices
I have committer access but I’m not a core developer - what are my restrictions?
Rule 1 - You may not commit directly to the stable branch.
# Rule 2 - So long as you're not just dealing with a couple lines of code, all contributions must go through the contribution depot for review *before* entered in the dev branch.
# Rule 3 - Only developers with explicit access to the 2.0_stable branch, dubbed 'stable certified', will be allowed to make any direct changes to that branch.
# Rule 4 - commits made on behalf of an originator post should refer to that post by its name, a full link and the #xxxx id number.
Recommended commit practices:
- Even if you are 2.0_stable certified, please always hold off merging large commits into the stable until you have had at least one valid review of your code. Remember you can 'request a review'. (also see the review section below)
- Trivial changes that obviously cannot have any negative impact on the stable branch do not have to be posted to the forum for review, but should be posted to the dev branch first so a(-nother) certified developer can at least look it over real quick before merging it.
- Do not make commits without corresponding Javadoc and internal documentation. We should validate all documentation for each commit.
Review practices
Forum
Posters & Reviewers
- First of all, you don't have to make your post an actual review, but do always keep it constructive. (everyone's doing a great job at this already so it's kinda unnecessary to state it, but just as a lil' aid in keeping it that way...)
- If you have made a fair review of the presented code, be clear about whether you think it is ready to be committed. Keep in mind that 'ready' implies that even though you know this code is going into the dev branch first, you consider it solid enough to be in the stable.
Thread starters; Code submitters
- When you submit code to the contribution depot, remember, you are submitting it for review and approval, so be open to suggestions and constructive criticism.
- Specify whether you expressively wish to submit the patch yourself, or if another developer may handle it for you.
- Important: Please, once you have confirmed that your submission has been committed to the trunk, change the icon of your thread (click 'modify' on the top post) to 'solved', to reflect the update.
A moderator can also be asked to change the icon of the post, but it will primarily be the code-submitter's responsibility to update the state of their contribution.
- If after about a week you have not received any reviews or comments yet, you may bump your post.
Note: If you were granted contributor/write access after some of your code submits had been added by others, you may comment on your own code to clearly express that you are the author of that code, effectively making you accountable for its future use and maintenance.
Note2: If you really wish to submit your first-time contributions yourself, you may request commit access right away, and it will usually be granted if you clearly express intent to make more future commits, and your code and credentials presented so far are solid.
Repository (googlecode)
Just one rule: Read Googlecode's CodeReviews, as these are the ideal practices we want our contributors to follow. This page also covers useful information in regards to requesting reviews, which every contributor is encouraged to do.
More common practices for reviewing, commenting and documenting are covered throughout the 'developer manual'.
I plan to create a 'contributor's manual' on our wiki, including all of this information, along with some existing wiki pages and posts. Here is the list of pages as I currently envision it:
Developer Manual:
- Review Practices (all that relates to it on this page)
- Development/coding conventions (dev-conv wiki page revised to be properly merged with thread1 & thread2
- Commit practices (all that relates to it on this page)
- Versioning (versioning wiki page revised to reflect the two separate branches and their purpose.
- Changelog (url=http://www.jmonkeyengine.com/wiki/doku.php?id=jme_changelog]changelog wiki page[/url] heavily revised to accomodate the fact that noone has the time to maintain such a page. Possibly if we do quarterly releases someone could find the time to make a decent changelog every 4 months?)