Difference between revisions of "Reviews/Contributor Guide"
(Undo last commits)
|(3 intermediate revisions by the same user not shown)|
Latest revision as of 16:29, 20 January 2012
|Mailing List • Forums • IRC|
|Browse Source • Project Set File|
- 1 Development IDE Configuration
- 2 Obtaining Sources
- 3 Builds
- 4 Documentation
- 5 Tests
- 6 Website
- 7 Contributing Patches
- 8 Libraries from Orbit
Development IDE Configuration
Recommended: Eclipse Helios with EGit plugins
Reviews currently have Java 1.5 and Eclipse Platform 3.5 as minimum requirements (following the Mylyn policy).
The current release always supports the last two stable Eclipse versions + the latest Eclipse milestone. Hence dependencies to newer Java and platform versions must be avoided.
- Download Team Project File (PSF) http://www.eclipse.org/mylyn/doc/dev/mylyn.psf
- Import -> Team Project Set and select the previously downloaded psf file.
- Apply the Patches on the tasks (Search for task Ctrl+Shift+F12)
Reviews sources are hosted in Git. Browse the repositories in cgit.
There are several ways to obtain a copy of each repository:
From the command line
git clone git://git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.reviews.git
From an installed EGit plugin
- File > Import > Git > Git Repository
- Enter URI:
- Import projects
To compile you also need libraries from Orbit. TODO- list of libraries
Mylyn Reviews can be built using Maven 3 and Tycho.
To build the Mylyn Reviews distribution clone the Mylyn Reviews Git repository and invoke Maven on the top-level POM:
git clone git://git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.reviews.git mvn -f org.eclipse.mylyn.reviews/pom.xml package
This creates a p2 repository in org.eclipse.mylyn.reviews/releng/reviews-site/target/site
The Reviews website is located in a CVS repository on the Eclipse Foundation's servers.
- File > Import > CVS > Projects from CVS
- Select URL :pserver:firstname.lastname@example.org/cvsroot/org.eclipse
- Use module reviews (from www)
Granularity of Changes
- Make small commits, as small as reasonable. This makes them easy to review.
- Each commit should have a commit message that explains very clearly what the commit sets out to achieve (unless this is abundantly clear from the code itself, which is basically only the case for trivial patches). Also, when you fix a bug then report which bug you fix. When there are deeper reasons for doing things the way the commit does, then explain these as well. This all is for the reviewers and yourself: the context of the commit is completely clear.
- Do not mix concerns in commits: have a commit do a single thing. This makes them reviewable 'in isolation'. The purpose of the commit is clear and can be understood easily by the reviewers and yourself.
- Do not break the build and tests for any commit: this is very important for bug hunting.
- Split your work into multiple smaller pieces of work (when possible) and implement each of these pieces in a series of commits.
- A series of commits should work towards a 'feature' in a clear way and only 'enable' the feature in the last commit of the series.
- In a series of commits first lay the groundwork and then build on that towards the feature.
- Do not mix concerns in branches: when you encounter a bug while working on something then create a new branch to fix the bug. If your work depends on the bug being fixed then rebase your work on that new branch.
Commit message guidelines
- The commit message header should fit on one line and should start with an uppercase letter
- The commit message have newline characters after every 60-70 characters.
- If there is an associated bug number in Bugzilla about it, it should come towards the end.
- The first sentence should be a clear and concise description about the change.
- Enter a newline before providing a more detailed description about the change.
Test before submitting
- Run all existing tests. It does not take very long.
Sending patches by mail
Although sending patches by mail is the approved way of interacting with, and asking feedback from, the Git project, please don't send patches via git send-email. Instead, please use git format-patch to generate the
mbox, and then attach that to an item in bugzilla as per the above SUBMITTING_PATCHES guides.
If you're sending a work-in-progress for a review, be aware that you can also attach work-in-progress (or RFC) items to Bugzilla; it's not just for finished patches.
Libraries from Orbit