Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Virgo/Committers"

(→‎JavaDoc Guidelines)
(Changed obsolete section about Ubuntu 10.04)
(67 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
{{Virgo}}  
 
{{Virgo}}  
 +
 +
= Committers Charter =
 +
 +
Committers are responsible for:
 +
* Maintaining and enhancing the Virgo code base
 +
* Ensuring the Hudson CI jobs pass all tests (blue ball)
 +
* Responding to queries on virgo-dev
 +
* Handling contributions
 +
* Developing contributors into committers
 +
* Complying with Eclipse IP policy
 +
* Keeping an eye on the Virgo forum
  
 
= Machine Setup =
 
= Machine Setup =
  
−
You need Sun JDK 6, Apache Ant 1.7.1 or later, and [[Git|git]]. You'll probably want an IDE such as Eclipse.
+
You need Sun JDK 6, Apache Ant 1.8.2 or later, and [[Git|git]]. You'll probably want an IDE such as Eclipse and, in order for Virgo projects to build under Eclipse, the [http://wiki.eclipse.org/Virgo/Tooling Virgo IDE tooling] and AJDT (the current update site may be found on http://www.eclipse.org/ajdt/downloads/).
 +
 
 +
<span style="color:#ff0000">Don't forget to install AJDT as this is needed so that Eclipse produces the same compiled classes as the Ant build!</span>
  
 
At the time of writing, some ant targets occasionally fail because they cannot load classes from jsch-0.1.42.jar. A workaround on Mac OS X is to copy this JAR from virgo-build's /lib/ivy directory to /opt/local/share/java/apache-ant/lib.
 
At the time of writing, some ant targets occasionally fail because they cannot load classes from jsch-0.1.42.jar. A workaround on Mac OS X is to copy this JAR from virgo-build's /lib/ivy directory to /opt/local/share/java/apache-ant/lib.
Line 11: Line 24:
 
         ulimit -n 10000
 
         ulimit -n 10000
  
−
To run certain scripts, you'll need ruby, gems, and the 'choice' gem. On Mac OS you can get these by installing the XCode tools (from the Mac OS X disk) and [http://www.macports.org/ MacPorts], then issuing:
+
To run certain scripts (don't run them unless you know what you're doing—and why), you'll need ruby, gems, and the 'choice' gem. On Mac OS you can get these by installing the XCode tools (from the Mac OS X disk) and [http://www.macports.org/ MacPorts], then issuing:
−
 
+
         sudo port -v install ruby (Not required on Mountain Lion)
−
         sudo port -v install ruby
+
         sudo port -v install rb-rubygems (Not required on Mountain Lion)
−
         sudo port -v install rb-rubygems  
+
 
         sudo gem install --remote choice
 
         sudo gem install --remote choice
  
−
= Coding  =
+
To run scripts such as Releaselor or Ripplor you'll need to:
 +
# Generate SSH key by calling ssh-keygen without a passphrase
 +
# Upload your public SSH key to build.eclipse.org
 +
#* login with user <code>virgoBuild</code>
 +
#* follow the steps described [[Git#Setting_up_ssh_keys | here]]
 +
# Log in (adding the host key) at least once to:
 +
#* build.eclipse.org
 +
#* download1.eclipse.org
 +
# Add your private key to ANT_OPTS:
 +
        -Dkey.file=$HOME/.ssh/id_dsa
  
−
Virgo has a strong emphasis on maintainable, or "clean", code. If you need a really good introduction to coding, we recommend "[http://cc2e.com/ Code Complete]". If you are already a proficient programmer and want to write really clean code, read "[http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882 Clean Code]". If you are not an expert in writing Java, read "[http://java.sun.com/docs/books/effective/ Effective Java]".  
+
If you have headless environment you may want to add to ANT_OPTS:
 +
        -Djava.awt.headless=true
  
−
Virgo code is thread safe unless specifically stated. Achieving thread safety in Java is not easy. We recommend "[http://www.javaconcurrencyinpractice.com/ Java Concurrency in Practice]" for a good grounding in Java concurrency.
+
To enable Clover you will need to specify in ANT_OPTS the path to the licence:
 +
        -Dclover.license.path=/opt/clover.license
  
−
== Code Style ==
+
== Notes for Ubuntu ==
  
−
All Virgo code '''must''' adhere to the following code style requirements.
+
=== JDK ===
  
−
=== Code Formatting and Templates ===
+
It is recommended to use the official Oracle JDK and not the OpenJDK.
 +
The offical Oracle JDK can be downloaded from the Oracle Java site.
  
−
Eclipse code templates, formatter, and clean up profile are available in the web server git repository in the doc/code-style/eclipse directory.
+
= Policies =
  
−
All code committed to the repository '''must''' adhere to these templates and '''must''' be formatted to match this code style.
+
In addition to detailed coding and testing policies describe later, there are some specific policies that committers need to be aware of.
  
−
=== Coding Conventions ===
+
== Event Log Message Policy ==
  
−
Virgo code conforms to the [http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html Sun Java Coding Conventions] except for the specific deviations from these conventions detailed below.
+
Please avoid renumbering event log messages when possible. People sometimes write scripts that act on event log messages. Some of our tests may even be sensitive to the numbers. So renumbering an event log message can cause unnecessary disruption to our users and ourselves.
  
−
==== Interface definitions ====
+
= Grokking =
  
−
Interface method definitions must '''not''' include any visibility modifier or the 'abstract' modifier. The code below shows an ''incorrect'' interface definition:
+
You can grok the high level structure of Virgo by understanding the set of [http://wiki.eclipse.org/Virgo/Source git repositories] that comprise Virgo.
  
−
<pre>
+
Use [http://virgo-opengrok.springsource.org/ OpenGrok] for searching the master branch of the entire Virgo code base. Always specify "Virgo" in the File Path field to avoid hits in Gemini Web and SpringSource dm Server which are also included in that index. Note that there is a link to OpenGrok on the Virgo home page for convenience.
−
public interface MyInterface {
+
  
−
public abstract void doSomething();
+
To get an idea of the dependency structure, use OpenGrok specifying "virgo build.versions" in the File Path field and, to see dependencies on a specific component, the component name in Full Search. For example, [http://virgo-opengrok.springsource.org/search?q=org.eclipse.virgo.kernel&defs=&refs=&path=virgo+build.versions&hist= this search] shows the git repositories that depend on the kernel.
−
}
+
−
</pre>
+
  
−
The ''correct'' definition is shown below:
+
= Coding  =
  
−
<pre>
+
Virgo has a strong emphasis on maintainable, or "clean", code. If you need a really good introduction to coding, we recommend "[http://cc2e.com/ Code Complete]". If you are already a proficient programmer and want to write really clean code, read "[http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882 Clean Code]". If you are not an expert in writing Java, read "[http://java.sun.com/docs/books/effective/ Effective Java]".
−
public interface MyInterface {
+
  
−
void doSomething();
+
Virgo code is thread safe unless specifically stated. Achieving thread safety in Java is not easy. We recommend "[http://www.javaconcurrencyinpractice.com/ Java Concurrency in Practice]" for a good grounding in Java concurrency.
−
}
+
−
</pre>
+
  
−
==== Final parameters and local variables ====
+
Coding guidelines are [[Virgo/Committers/Coding| here]].
  
−
The use of the 'final' qualifier on method parameters and local variables is strongly discouraged. Valid scenarios for 'final' usage include passing state to anonymous type instances and preservation of an important internal method contract.
+
A Contextual Bash History can be very useful, guide [[Virgo/Committers/Bash| here]].
  
−
== Concurrent Programming Guidelines ==
+
== Eclipse Setup ==
  
−
=== Levels of Concurrent Support ===
+
# Install the Virgo IDE tooling into Eclipse as [http://wiki.eclipse.org/Virgo/Tooling#Installation described] under the Tooling tab.
 +
# Install [http://www.eclipse.org/ajdt/ AJDT] into Eclipse. This is necessary so that Virgo projects which use AspectJ are correctly woven when rebuilt under Eclipse.
 +
# Install [http://www.eclipse.org/egit/ egit] into Eclipse. This step is recommended but not absolutely essential since it is possible to perform git operations on the command line or using some other git GUI tool.
 +
# Build the Virgo git repository you want to import into Eclipse as [http://wiki.eclipse.org/Virgo/Build#Building_Individual_Repositories described] under the Build tab. Ensure you see BUILD SUCCESSFUL.
 +
# Import the projects of the chosen git repository by using File->Import->Git->Projects from Git. Then click Next and add the git repository, select it, and click Next. Select the "Import existing projects" wizard and click Next. Check the projects you want to import (typically org.eclipse.virgo.xxx where xxx corresponds to the repository - other projects such as test bundle projects and any inside the build-xxx and virgo-build directories are unlikely to be of interest) and click Finish.
 +
# If you see lots of errors, you probably need to define a suitable classpath variable, e.g., KERNEL_IVY_CACHE, to point to the Ivy cache which has been built in the local copy of the git repository (actually to the ivy-cache/repository folder).
 +
# There should be no errors (marked in red). Occasionally, the build paths get out of step with the build.versions file and need updating.
  
−
A class can either be thread safe or not. A class is thread safe if its invariants are protected when accessed simultaneously by multiple threads.
+
= Testing =
  
−
=== Required Level of Concurrent Support ===
+
See {{VirgoLink|Test|Test|{{{tab}}}|testing}}.
  
−
* All classes that form part of the public API of their bundle, or serve as an externally accessible implementation of that public API are '''required''' to be thread safe.
+
= Hudson CI =
  
−
* Public classes that are not intended to be shared by multiple threads may be coded as non thread safe, but this in discouraged since single-threaded usage cannot easily be enforced.
+
Committers should [https://dev.eclipse.org/mailman/listinfo/virgo-build subscribe] to virgo-build@eclipse.org so they are notified when builds fail, become unstable, become stable, etc.
  
−
* Classes that are internal to a bundle are free to be non thread safe. However, if these classes are used as part of the implementation of the bundle API then the API classes must guarantee thread safe access to their delegate classes.
+
Build breaks should be investigated as soon as they occur and should be fixed as soon as possible.
  
−
=== Alien Calls ===
+
= IP Due Diligence  =
  
−
An alien call is any call to a component outside of the control of the caller. Holding a lock while making an alien call is deadlock-prone and '''forbidden'''. The big question is what constitutes a component. Treating each class as a component from the perspective of alien calls is safe but can be too limiting at times. A package (within a bundle) is a more useful component in practice. In some situations, it may be necessary to code alien calls across packages within a bundle, but extreme care must be taken to avoid deadlocks. Alien calls between bundles are '''forbidden'''.
+
== Handling Code Contributions ==
  
−
=== Use of Client Locking Protocols ===
+
Committers are responsible for ensuring that Eclipse IP policy, summarised in the [http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf legal poster], is adhered to.
  
−
A client locking protocol is a contract between a class and its consumers. This contract outlines how the calling class can cooperate in the locking of the callee class. An example of a client locking protocol in common usage can be found in Hashtable. When performing composite operations on a Hashtable it is possible to synchronize on the Hashtable instance and participate cooperatively in the locking inside the Hashtable.
+
Patches must be attached to a bugzilla bug and have its iplog flag set to '+', and the contributor must confirm in the bug that: they wrote 100% of the code, they have the right to contribute the code to Eclipse, and new Java files contain the appropriate license header.
  
−
In Virgo, the use of client locking protocols is '''forbidden''' because they can very easily lead to deadlocks. If a class in Virgo needs to allow composite operations on its internal data structures, it should support these operations in its API.
+
If the contribution is provided in an external git repository, it is not necessary to attach a patch to the bug: details [http://wiki.eclipse.org/Development_Resources/Handling_Git_Contributions here].
−
 
+
−
=== Use of synchronized Methods ===
+
−
 
+
−
The use of synchronized methods in Virgo is '''forbidden'''. A class with synchronized methods implicitly exposes its monitor object (itself) to the outside world.
+
−
 
+
−
In a multi-threaded environment this can easily lead to deadlocks. If class Foo synchronizes on an instance of Bar, and these instances of Bar synchronize on 'this', then access of Foo and Bar across different threads can easily deadlock.
+
−
 
+
−
Note also that explicit 'synchronized(this)' blocks are also '''forbidden'''.
+
−
 
+
−
A simple alternative for classes wishing to maintain some internal synchronization is to use an internal monitor field:
+
−
 
+
−
<pre>
+
−
public class MyClass {
+
−
 
+
−
private final Object monitor = new Object();
+
−
+
−
public void doSomething() {
+
−
synchronized(this.monitor) {
+
−
// logic here
+
−
}
+
−
}
+
−
}
+
−
</pre>
+
−
 
+
−
'''Important:''' The monitor field must be declared as final otherwise synchronizing on it is non-deterministic due to Java Memory Model visibility rules.
+
−
 
+
−
== Code Visibility ==
+
−
 
+
−
=== Types ===
+
−
 
+
−
Types should always have the minimum visibility consistent with their use.
+
−
 
+
−
=== Methods ===
+
−
 
+
−
Methods should have the minimum visibility consistent with their use. Methods that form part of the public contract of a type should of course be public but methods that are used to implement that contract should be private.
+
−
 
+
−
When allowing extension, protected methods can be used to provide extension points for subclasses. Protected final methods may be used to provide functionality to subtypes but that cannot be extended.
+
−
 
+
−
It is valid to relax the visibility of methods to make unit testing easier. In this case, it is common to change a private method to have default access so that test classes in the same package can access it.
+
−
 
+
−
=== Static Fields ===
+
−
 
+
−
For immutable static fields, such as those used in constants, any access modifier is valid. For mutable static state, private access '''must''' always be used and mutations to the state should be done via accessor methods.
+
−
 
+
−
=== Instance Fields ===
+
−
 
+
−
In almost all cases fields should be private. Providing subclasses with access to state ''can'' be done with protected fields but protected accessor methods are preferred.
+
−
 
+
−
== Type Naming Conventions ==
+
−
 
+
−
The following type naming conventions must be adhered to for both runtime and test classes.
+
−
 
+
−
=== Interfaces ===
+
−
 
+
−
When implementing an interface the use of the 'Impl' suffix is not permitted.
+
−
 
+
−
Ideally choose a name that truly reflects the implementation detail. An example of this is XmlConfigurationSource, an implementation of ConfigurationSource that uses XML to read configuration data.
+
−
 
+
−
If no better name is available, the implementation should be named by prefixing Standard to the interface name. For example, the interface Kernel could have an implementation named StandardKernel.
+
−
 
+
−
=== Test Cases ===
+
−
 
+
−
All test case types must have their names suffixed with 'Tests', for example StandardKernelTests.
+
−
 
+
−
== JavaDoc Guidelines ==
+
−
 
+
−
=== Useful Resources ===
+
−
 
+
−
* [http://java.sun.com/j2se/javadoc/writingdoccomments/ Sun Writing Doc Comments Guide]
+
−
* [http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#javadoctags JavaDoc Tag Summary]
+
−
 
+
−
=== Documentation Requirements ===
+
−
 
+
−
API documentation must be written to conform to the guidelines set out in Sun's [http://java.sun.com/j2se/javadoc/writingapispecs/index.html Requirements for Writing API Specifications]. This document is full of useful examples from the JDK.
+
−
 
+
−
In addition to the requirements from this document all types, and methods where relevant, must document their concurrent behavior. Types should document their concurrent semantics including whether or not they are thread safe.
+
−
 
+
−
==== Documenting Interface Concurrency ====
+
−
 
+
−
Interfaces must document any restrictions that their contract places on the concurrency of an implementation. For example, an interface may require that a Collection returned from one of its methods must reflect internal updates accurately, or must throw ConcurrentModificationException if a change occurs during iteration. For example:
+
−
 
+
−
<pre>
+
−
/**
+
−
* ...
+
−
*
+
−
* <strong>Concurrent Semantics</strong><br/>
+
−
*
+
−
* Implementations must be thread safe.
+
−
*/
+
−
public interface ...
+
−
</pre>
+
−
 
+
−
==== Documenting Type-Level Concurrency ====
+
−
 
+
−
Types must as a minimum document whether or not they are thread safe. In addition, types must document any lock acquisition protocols that they require calling code to adhere to.
+
−
 
+
−
Also, types must document the guarantees around state visibility that they provide as part of their implemented concurrency level. For example, some types may present internal Collection state in a weakly consistent manner.
+
−
 
+
−
Example:
+
−
<pre>
+
−
/**
+
−
* ...
+
−
*
+
−
* <strong>Concurrent Semantics</strong><br/>
+
−
*
+
−
* Implementation is immutable and therefore thread safe.
+
−
*
+
−
*/
+
−
</pre>
+
−
 
+
−
==== Documenting Method-Level Concurrency ====
+
−
 
+
−
For methods that have specific concurrency semantics, these semantics should be included in the JavaDoc. For example:
+
−
 
+
−
<pre>
+
−
/**
+
−
* @inheritDoc <p/> Returns a "weakly consistent" view of the
+
−
*            <code>Subsystems</code> that is guaranteed to be consistent
+
−
*            with the view of <code>Subsystems</code> at the time of
+
−
*            calling. Concurrent modifications are not guaranteed to be
+
−
*            reflected.
+
−
* @see ConcurrentHashMap#values()
+
−
*
+
−
*/
+
−
public Collection<Subsystem> getSubsystems() {
+
−
    ...
+
−
}
+
−
</pre>
+
−
 
+
−
= Testing =
+
−
 
+
−
See {{VirgoLink|Test|Test|{{{tab}}}|testing}}.
+
−
 
+
−
= IP Due Diligence  =
+
  
 
== Raising "works with" CQs  ==
 
== Raising "works with" CQs  ==
Line 243: Line 133:
  
 
[[Category:Virgo]] [[Category:EclipseRT]]
 
[[Category:Virgo]] [[Category:EclipseRT]]
 +
 +
= Development process advice =
 +
 +
To enable distributed and cooperative development, some simple rules and processes need to be followed.  These are all subject to change and are in the nature of ''advice'' rather than ''laws''.
 +
 +
The advice is [[Virgo/Committers/Process_Advice|here]].
 +
 +
= Agile Project Management =
 +
 +
The basic principle is that tasks which need to be worked on are placed in the backlog. For a particular sprint, some of the tasks in the backlog are moved to the sprint and completed. So no task appears in both the backlog and a sprint.
 +
 +
Import bugs from bugzilla into [http://eclipse-virgo.acunote.com/projects/16748/sprints Acunote] as follows:
 +
 +
# Export all the open bugs for Virgo (and Gemini Web if you like) to a CSV file using the CSV link on the bugzilla search results panel.
 +
# Go to the "Imported from bugzilla" sprint (not really a sprint at all) and import the CSV using the Tools link followed by "Import tasks from Bugzilla" ('''not''' "Import tasks from CSV"). Make a note of the task numbers added.
 +
# Go to the "Imported from bugzilla" sprint and '''copy''' the tasks added in the previous step to the backlog.
 +
# It is helpful to categorise bugs and features using the "More Actions" pull down. We put the bugs at the top of the backlog so we don't lose track of them.
 +
 +
To work on a sprint:
 +
# Add a sprint.
 +
# '''Move''' tasks from the backlog into the new sprint to work on them. If you don't complete them, '''move''' them to a new sprint or '''move''' them back to the backlog.
 +
 +
 +
Since we are trying to use Acunote to manage sprints in Southampton, Sofia, and potentially elsewhere, please ensure that bugzilla is kept up to date in case the Acunote data gets corrupted.
 +
 +
Note that we never remove tasks from the "Imported from bugzilla" so that subsequent imports do not accidentally re-create finished tasks. The maintainers of Acunote recommended this technique.
 +
 +
= Logos =
 +
 +
If you have need to use the Virgo logos some example and the svg source can be found [[Media:VirgoLogos.zip|here]].

Revision as of 07:30, 21 December 2016


Committers Charter

Committers are responsible for:

  • Maintaining and enhancing the Virgo code base
  • Ensuring the Hudson CI jobs pass all tests (blue ball)
  • Responding to queries on virgo-dev
  • Handling contributions
  • Developing contributors into committers
  • Complying with Eclipse IP policy
  • Keeping an eye on the Virgo forum

Machine Setup

You need Sun JDK 6, Apache Ant 1.8.2 or later, and git. You'll probably want an IDE such as Eclipse and, in order for Virgo projects to build under Eclipse, the Virgo IDE tooling and AJDT (the current update site may be found on http://www.eclipse.org/ajdt/downloads/).

Don't forget to install AJDT as this is needed so that Eclipse produces the same compiled classes as the Ant build!

At the time of writing, some ant targets occasionally fail because they cannot load classes from jsch-0.1.42.jar. A workaround on Mac OS X is to copy this JAR from virgo-build's /lib/ivy directory to /opt/local/share/java/apache-ant/lib.

On Mac OS X, increase the default number of concurrently open files by adding this to .profile: 

       ulimit -n 10000

To run certain scripts (don't run them unless you know what you're doing—and why), you'll need ruby, gems, and the 'choice' gem. On Mac OS you can get these by installing the XCode tools (from the Mac OS X disk) and MacPorts, then issuing: 

       sudo port -v install ruby (Not required on Mountain Lion)
       sudo port -v install rb-rubygems (Not required on Mountain Lion)
       sudo gem install --remote choice

To run scripts such as Releaselor or Ripplor you'll need to:

  1. Generate SSH key by calling ssh-keygen without a passphrase
  2. Upload your public SSH key to build.eclipse.org
    • login with user virgoBuild
    • follow the steps described here
  3. Log in (adding the host key) at least once to:
    • build.eclipse.org
    • download1.eclipse.org
  4. Add your private key to ANT_OPTS:
       -Dkey.file=$HOME/.ssh/id_dsa

If you have headless environment you may want to add to ANT_OPTS: 

       -Djava.awt.headless=true

To enable Clover you will need to specify in ANT_OPTS the path to the licence: 

       -Dclover.license.path=/opt/clover.license

Notes for Ubuntu

JDK

It is recommended to use the official Oracle JDK and not the OpenJDK. The offical Oracle JDK can be downloaded from the Oracle Java site.

Policies

In addition to detailed coding and testing policies describe later, there are some specific policies that committers need to be aware of.

Event Log Message Policy

Please avoid renumbering event log messages when possible. People sometimes write scripts that act on event log messages. Some of our tests may even be sensitive to the numbers. So renumbering an event log message can cause unnecessary disruption to our users and ourselves.

Grokking

You can grok the high level structure of Virgo by understanding the set of git repositories that comprise Virgo.

Use OpenGrok for searching the master branch of the entire Virgo code base. Always specify "Virgo" in the File Path field to avoid hits in Gemini Web and SpringSource dm Server which are also included in that index. Note that there is a link to OpenGrok on the Virgo home page for convenience.

To get an idea of the dependency structure, use OpenGrok specifying "virgo build.versions" in the File Path field and, to see dependencies on a specific component, the component name in Full Search. For example, this search shows the git repositories that depend on the kernel.

Coding

Virgo has a strong emphasis on maintainable, or "clean", code. If you need a really good introduction to coding, we recommend "Code Complete". If you are already a proficient programmer and want to write really clean code, read "Clean Code". If you are not an expert in writing Java, read "Effective Java".

Virgo code is thread safe unless specifically stated. Achieving thread safety in Java is not easy. We recommend "Java Concurrency in Practice" for a good grounding in Java concurrency.

Coding guidelines are here.

A Contextual Bash History can be very useful, guide here.

Eclipse Setup

  1. Install the Virgo IDE tooling into Eclipse as described under the Tooling tab.
  2. Install AJDT into Eclipse. This is necessary so that Virgo projects which use AspectJ are correctly woven when rebuilt under Eclipse.
  3. Install egit into Eclipse. This step is recommended but not absolutely essential since it is possible to perform git operations on the command line or using some other git GUI tool.
  4. Build the Virgo git repository you want to import into Eclipse as described under the Build tab. Ensure you see BUILD SUCCESSFUL.
  5. Import the projects of the chosen git repository by using File->Import->Git->Projects from Git. Then click Next and add the git repository, select it, and click Next. Select the "Import existing projects" wizard and click Next. Check the projects you want to import (typically org.eclipse.virgo.xxx where xxx corresponds to the repository - other projects such as test bundle projects and any inside the build-xxx and virgo-build directories are unlikely to be of interest) and click Finish.
  6. If you see lots of errors, you probably need to define a suitable classpath variable, e.g., KERNEL_IVY_CACHE, to point to the Ivy cache which has been built in the local copy of the git repository (actually to the ivy-cache/repository folder).
  7. There should be no errors (marked in red). Occasionally, the build paths get out of step with the build.versions file and need updating.

Testing

See Test.

Hudson CI

Committers should subscribe to virgo-build@eclipse.org so they are notified when builds fail, become unstable, become stable, etc.

Build breaks should be investigated as soon as they occur and should be fixed as soon as possible.

IP Due Diligence

Handling Code Contributions

Committers are responsible for ensuring that Eclipse IP policy, summarised in the legal poster, is adhered to.

Patches must be attached to a bugzilla bug and have its iplog flag set to '+', and the contributor must confirm in the bug that: they wrote 100% of the code, they have the right to contribute the code to Eclipse, and new Java files contain the appropriate license header.

If the contribution is provided in an external git repository, it is not necessary to attach a patch to the bug: details here.

Raising "works with" CQs

"works with" CQs are required for test dependencies which are not distributed with Virgo or checked in to Eclipse version control (git, svn, cvs).

The initial set of test dependencies was determined, for repositories which are built with ant, as follows:

1. In the build-xxx directory run ant report

2. Extract a raw list of the test dependency jars 

find <report directory> -name "*-test.xml" -exec grep -E \/.+\.jar  {} \; >test-jars.txt

3. Edit test-jars.txt using an editor with a regular expression global change facility and do the following global changes.

3.1 Replace regex .+\/(.+)\.jar\"> with $1.jar.

3.2 Replace regex .+\/(.+)\.jar\"\/> with $1.jar.

3.3 Replace -sources with the empty string

4. Sort test-jars.txt and remove duplicate lines.

5. Look through test-jars.txt and raise "works with" for any JARs which don't have a Virgo CQ for the correct version. Also, raise corresponding Virgo bugzillas and set the iplog flag to enter the bugzillas in the automated IP log.

Development process advice

To enable distributed and cooperative development, some simple rules and processes need to be followed. These are all subject to change and are in the nature of advice rather than laws.

The advice is here.

Agile Project Management

The basic principle is that tasks which need to be worked on are placed in the backlog. For a particular sprint, some of the tasks in the backlog are moved to the sprint and completed. So no task appears in both the backlog and a sprint.

Import bugs from bugzilla into Acunote as follows:

  1. Export all the open bugs for Virgo (and Gemini Web if you like) to a CSV file using the CSV link on the bugzilla search results panel.
  2. Go to the "Imported from bugzilla" sprint (not really a sprint at all) and import the CSV using the Tools link followed by "Import tasks from Bugzilla" (not "Import tasks from CSV"). Make a note of the task numbers added.
  3. Go to the "Imported from bugzilla" sprint and copy the tasks added in the previous step to the backlog.
  4. It is helpful to categorise bugs and features using the "More Actions" pull down. We put the bugs at the top of the backlog so we don't lose track of them.

To work on a sprint:

  1. Add a sprint.
  2. Move tasks from the backlog into the new sprint to work on them. If you don't complete them, move them to a new sprint or move them back to the backlog.


Since we are trying to use Acunote to manage sprints in Southampton, Sofia, and potentially elsewhere, please ensure that bugzilla is kept up to date in case the Acunote data gets corrupted.

Note that we never remove tasks from the "Imported from bugzilla" so that subsequent imports do not accidentally re-create finished tasks. The maintainers of Acunote recommended this technique.

Logos

If you have need to use the Virgo logos some example and the svg source can be found here.

Retrieved from "https://wiki.eclipse.org/index.php?title=Virgo/Committers&oldid=413070"

Back to the top