Architecture Council/Contributor Guide Recommendation
Under Construction: This page is still under construction. It should provide a recommendation for new projects to provide a Gontributor Guide. See bug 397644 for more information.
Contributor Guide - Motivation
To simplify adoption and encourage contributions it is recommended that Projects maintain a "Contributor Guide" page. Such a page may contain information about:
- the dependencies of the project
- how to quickly setup the workspace for local development - where/how to get the sources and import projects into the IDE, how to easily get all the necessary libraries the project depends on, etc...
- how to build the project artifacts (e.g. bundles, features, standalone products)
- some ideas what could be contributed to the project
- project speciffic preferences on code quality, proposing patches, etc...
Such information helps adopters to see for example all the dependencies of the project. People interested in the project could easily start looking into and playing with the code, and hopefully do contributions.
This section contains brief information on concrete tools, frequently mentioned in the contribution guides
Getting the Sources
- For projects in Git usually EGit is used. See the Contributor_Guide#From an installed EGit plugin
- For projects in SVN usually Subversive is used. Project Set files (psf) may also be provided.
Using an Explicit Target Platform Definition
One technical possibility for projects to simplify the handling of dependencies is to provide one or more target definition files. Such files can be stored in the repository together with the sources and should be promoted on the "How to Contribute" page.
Using a target definition file, one can setup the workspace with a few steps:
- clone (or checkout) source from the repository
- import the projects (usually at this time there are compiling errors because of missing dependencies)
- open the target definition file and set it as target platform for the workspace - all dependencies are resolved
- start develpoing
In addition, projects using Tycho as a build technology can use exactly the same target definition during the build. This guarantees that the dependencies used in the IDE and the ones fetched during the build are the same.
Target definition files should contain the strict necessary dependencies for the project to compile and execute. It's recommended setting includeSources attribute to true in .target files to provide to developers access to sources of the dependencies, when available, in their development environment (PDE) without effort; for Tycho builds, this attribute is ignored and does not add sources to the build target-platform. Project could maintain several target defintions, for example to match several version of Eclipse.
There are many projects at Eclipse which provide a "How to contribute" description. Just to name a few examples: