Open Source Development in an Ideal World

What should the ideal large open source project offer potential developers to help them to get started as quickly and easily as possible? These are my ideas on what would make my life easier when I'm thinking about producing some code for a project. I wouldn't expect any project to manage to get all of these right, but the more that can be managed the better! The larger a project becomes, and the more developers involved, and more code to understand for even the smallest development project, the more these issues become important.

1. There should be one major release at a time, or it should be clear which release is to be developed against for best integration with the current wishes of the software project community (whether it is the current stable release, existing alpha and beta releases, nightly build versions, or the code available at the moment from the repository). It should be easy to download the right version of the source code at any particular time (including the build which is recommended for development).
2. There should be clear links from the main project website to instructions for developers.
   
3. There should be a mailing list which should support a helpful and understanding development culture.


4. Code conventions and architectural assumptions (e.g. which Java technologies should be used for specific purposes) should be clearly documented, either on the Internet or in the code itself. It should not be necessary to use file search tools or the search interface of an integrated development environment (IDE) to find the source code for a major element of the product.
5. It should be clear how back-end code and interface interact.
6. It should be clear how authorisation to carry out actions is handled.
7. There should be a general architectural philosophy which allows the use of plug-in code where this would be useful. Examples of where this would make life easier would be in adding small features (often known as "widgets") to the interface, which can then just consist of a fragment of HTML template and the code to support the feature which uses an API to interface to the main project code, as opposed to actually needing to modify the main code itself.
8. Java and other modern languages are associated with a wide range of supporting technologies (e.g. compilers, HTML template engines, and development frameworks), and the specific choices made for an individual open source project should be clearly documented, as it is unlikely that developers new to the project will be familiar with all of them.
9. The source code should compile without too much difficulty most of the time (daily builds may be expected to be broken sometimes, and in alpha and beta releases, some parts of the code may fail to compile if components are not yet updated to match new requirements).
10. There should be Javadoc style documentation for every class in the source code to at least make it easy to determine the structure of each class, especially for large classes with many methods. A lot of information can often be obtained about how the code works just from the names of the methods, even if there is no extra detail available. The location of Javadocs should be central and clearly signposted. The Javadocs should be indexed by search engines (if they are automatically generated frequently, this might not happen, so it makes sense to permanently store static versions associated with stable releases, at least).
11. Code should have at least some comments, and java classes should not be unnecessarily complex and long – one of the points of modern programming languages is that developers do not need to put all the code into one huge source file.
12. If a development tool such as an IDE is recommended, this should be made clear and it should be possible to import the code into the IDE either as a whole or in sections without much difficulty, even when it does not compile. This should be possible with the current version of the IDE (or, if not, the version to use should be clear) on a computer with a reasonable amount of memory.
13. Where there are requirements to install third party code, these should be clear and properly maintained (i.e., links to download libraries should not produce “not found” errors). This includes, for example, extensions which need to be installed for the code to work with an IDE of choice, as well as the libraries used by the project itself, for which technologies such as maven make the management of the required libraries much easier.