# Project Policies and Procedures Version 1.0

The following policies and procedures are intended to ensure that Acegi Security will continue to achieve its project objectives and support the community in the context of an expanding development team.

The following was unanimously supported by the community supporting following discussion on acegisecurity-developer. The policies and procedures below represent version 1.0 and are effective 1 August 2005.

- This project uses JIRA. Please log a task in JIRA for any changes you make to CVS, with the exception of very minor changes that users are unlikely to ever be interested in searching for and/or the change affects code that has never been in an officially released version of the project (eg ongoing changes to a new feature in CVS HEAD that hasn't been released previously).
- Any users running from CVS HEAD are warmly encouraged to join acegisecurity-cvs so that they can keep an eye on commit comments. Developers are encouraged to join acegisecurity-cvs and read the commit comments. If anyone has a concern with any commit, please raise it on acegisecurity-developer so that the broader community can participate (not acegisecurity-cvs). Alternatively, contact the author of the change directly if you think that would be more appropriate or diplomatic.
- Please make your commit comments informative, yet not too detailed. Detailed comments are ideally placed in the JIRA task. In the case of a contribution by a non-developer, please use the CVS commits to reflect who provided the contribution and add that person's name to /project.xml in the contributors section. If the contributors section does not list the name of someone who has contributed accepted code, please add them or let me know so that I can do so.
- If you add a major new feature, please announce it on acegisecurity-developer. That way people using the project have an idea of what is coming up in the next release, and any implementation-specific comments can be received prior to the first release when users will start expecting some degree of consistency and stability. It also encourages people to try out your new feature.
- Please edit /docs/xdocs/changes.xml to reflect any changes you commit. The entry should be short enough so that I can copy it into the new release announcement email, and reflect the JIRA issue number if appropriate. Do not add the name of contributors to /doc/xdocs/changes.xml, as acknowledgement is already provided via /project.xml, source code @author tags, the CVS commit message, and typically a JIRA task.
- Please edit /docs/xdocs/upgrade/upgrade-xx-yy.html if you make a change that is significant and you think users who are upgrading should be aware of it. Equally, users are encouraged to consult the upgrade-xx-yy.html file before they deploy subsequent official release JARs.
- Please use Jalopy with the /jalopy.xml file to format your Java code before checkin. This keeps our code consistent and ensures the license message is correct. There are plugins for all major IDEs.
- The /sandbox can be used to obtain feedback from fellow developers and the community about your code, general approach or new ideas. If you have CVS rights, please use /sandbox instead of emailing ZIP files to other developers for feedback. The community should understand that code in the sandbox is unsupported, subject to refactoring, may not have any unit tests, and may be removed at any time. The /sandbox will never be included in official release ZIPs. It's a "scratching pad" only.
- Unit tests are important to any security project, and we have a good history of high coverage. You can view the latest coverage report online (rebuilt every 24 hours). Please keep an eye on coverage and don't hesitate to add more unit tests. Please do not check code into /core unless it has at least an exercising unit test - use the /sandbox instead.
- Never check in code if the unit tests fail. This means, at minimum, successfully running "maven test:test" from /core. Always name your unit test classes so they end in "*Tests" - this ensures that Maven picks them up. If there is code in CVS which you didn't write and it is breaking the unit tests, please correct it yourself - don't leave CVS "broken" whilst waiting for the responsible developer to address it (the delay causes confusing and long-running threads on the list and forum). You can always rollback to the previous working version if in doubt of how the class works (just remember to comment the commit appropriately and let the author know).
- Please update the reference guide and JavaDocs for any new major features. The JavaDocs should always be correct. The reference guide may be kept updated with less rigor, although please briefly discuss any major new features. XMLmind can be used if you don't have a DocBook editor.
- Developers please keep an eye on the Acegi Security forum. It's a very active forum, and it takes a lot of work if not shared around. Please don't hesitate to reply to users - I try to read every thread and correct/confirm the situation if someone mentions they're unsure. I also will generally send developers an email if there's a question I can't answer as I didn't write the code.
- In the future, I will put to vote any proposed new developers. New developers will be firstly encouraged to attach patches to JIRA tasks to illustrate their understanding of the project, or, if they're long-time users, they might be given access without this JIRA stage if they're undertaking a major new feature.
- Developers should be subscribed to acegisecurity-developer. Obviously it would take significant time to read every thread, but reading the high priority messages (as indicated by the subject line) is needed to ensure we all have a way of communicating.
- Please do not hesitate to assign yourself any JIRA task that is unassigned, or assigned to me and not in the "In Progress" status. Also feel free to approach fellow developers to volunteer to work on tasks they might be assigned but haven't started.
- No code in CVS is "sacred". If you have a good idea or refactoring for an area of code that someone else wrote, raise it on acegisecurity-developer or contact the author directly. Please don't commit changes to such code unless it is a unit test failure correction, or you've firstly raised it on the acegisecurity-developer list or directly with the author.
- People's priorities are ever-changing, and we're all short on time. For this reason it's perfectly understandable that over time developers will move on to other things. This is not a negative reflection in any way - just part of any long-term project. If a developer no longer has the time or inclination to participate in the project , please send an email to acegisecurity-developer or myself. I will remove the CVS rights and reassign any JIRA tasks. Importantly, this helps find a new maintainer of the former developer's code (or, in very extreme cases, their code might be relocated to the sandbox or removed).
- Use CDATA inside XML files for multi-line properties. There is no tab/space policy for XML files, although try to maintain whatever the file is already using. The tab/space policy for Java files is managed by Jalopy.
- Keep the warm community spirit. The Spring community is a nice place to be - especially compared with some of the other open source communities out there where people are abused, ignored, insulted or excluded. No policy or procedure (including those above) should ever compromise operating in a considerate and diplomatic manner that respects the dignity of each individual member of the community. If in doubt, please contact me directly first. If I am ever guilty of this, please let me know and I will correct myself.

Thanks for your help in connection with the above. If you have any suggestions for improving these policies and procedures, please use the acegisecurity-developer list to raise them.

Ben Alex
Project Admin

$Id$