CrossProject:HouseKeeping Best Practices Group:Main
As we grow together a community, it can help to figure out best practices to recommend to projects to make the process of living together more comfortable. These are not intended to be things *forced* on a project, but rather, to identify problems we need to solve, and robust solutions to those problems suitable for broad adoption. This page attempts to track both best practices and what outstanding problems we still have.
Current Best Practices
This section contains the summary of what we know for a fact is a good advice for ODL projects to follow. Projects following these will be familiar ground for developers working with other projects, hopefully enabling more cross-project communication.
The layout of your project directly determines how much 'at home' other developers will feel when they look at your repository for the first time. Using the layout to organize information and (maven) build system instructions in specific ways allows you to harness common infrastructure pieces and ease your interaction with other projects. You can find the specific guidelines in the dedicated Project Layout page.
|VERSIONING||This is actually a few problems rolled together. First, there is a desire to have bundles rev their versions whenever their API changes. Second, there is a desire on the part of projects to be able to control the rate at which they absorb change from projects they depend on. A reasonable best practice for versioning looks like a promising mechanism for managing both.||There are several potential problems with using versioning to solve these problems. First, we have many many bundles, and so manually keeping up versions across many projects is likely to be extremely fragile. Second, There is danger in projects falling *too* far behind things they depend on, particularly if that falling behind is unintentional. Neither of these problems should be insurmountable, but both need to be addressed||Versioning|
|INTEGRATION TESTS||Pax-exam turns out to be quite fragile as an integration test mechanism cross projects, as it can produce false failures in situations in which no actual functional failure has occurred. This leads to false appearances of instability due to failures rooted in pax-exam fragileness rather than actual breakage in the system.||Integration Test|
|WHITESPACE||A failure on the part of a project to have a single, enforced policy on whitespace can lead to difficult to read diffs, where simple whitespace changes get reported along side actual code changes.||Care must be taken if using a mechanism like checkstyle to insure that it not run on generated code, as such code is not in fact checked into the code base, and there is often limited control over whitespace issues there. Additionally, care must be taken to insure that projects have independence.||Whitespace|
|MINDFULDEPENDENCIES||Java has an incredibly rich ecosystem of components available through maven allowing for rapid code velocity. Thus the ability to bring shift dependencies, both for new functionality and to address bugs is critical to development and should not be curtailed. However, developers *should* be made to *think* about their dependency choices. Additionally, there is benefit in trying to converge on a common version of a dependency when possible.||Mindful Dependencies|
|DEVBRANCHES||Git allows many different branching styles when developing projects. Using a system such as GitFlow where "feature" branches are leveraged and kept up to date might allow the ODL community to have better visibility to the code being developed by the various projects as well as define a common pattern for merging from development to production.||While feature branches may contain up to date code, they are not necessarily in a build or running state. Additionally, branching usually just postpones pain. It is quite common for merging dev branches to be a very difficult exercise, and we have a couple of examples already in ODL history of dev branches that have been impossible to actually merge due to the divergence. Further, even outstanding *Gerrits* sometimes become very painful to rebase if they are to stale.|