19. Developing GDA¶
19.1. Commit messages¶
Start with one short line, preferably less than 50 characters, summarising the changes. This should generally be prefixed with a Jira ticket key relating to the change. Note that the summary should relate to the actual changes made in the commit which is usually not the same as the Jira ticket title. Sometimes there may not be an associated Jira ticket; in this case it might be appropriate to prefix with a project/area instead.
Follow this with one empty line, then a more detailed description.
The blank line is important since any text up to the first blank line is
considered the commit’s subject which git uses for various purposes such as the
output of git commit --oneline.
Here is an example:
DAQ-1234 Short (50 chars or less) summary of changes
More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body. The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.
Write the summary line in the imperative mood: "Fix bug" and not "Fixed
bug." This convention matches up with commit messages generated by
commands like git merge and git revert. For the body of the commit message
the tense rule may be relaxed.
Further paragraphs come after blank lines.
- Bullet points are okay, too
- Typically a hyphen or asterisk is used for the bullet, preceded by a
single space, with blank lines in between, but conventions vary here
- Use a hanging indent
The following links provide advice on writing good commit messages:
“A Note About Git Commit Messages” by Tim Pope
FreeBSD’s Committer’s Guide has some useful advice. Search for “Good commit messages”
ScummVM Commit Guidelines
19.2. Deprecation procedure¶
Refactoring and consolidation of the codebase is common in GDA so code will often be removed.
For types or methods which are API (in theory any public type or method) care should be taken to ensure that any code depending on this API is aware and able to migrate to an alternative. The IDE is useful for determining Java callers however there may be Jython scripts also relying on API, in addition to Spring configuration.
The standard timescale is to deprecate an item for two releases before it is deleted. For example deprecate before GDA 9.26 is released and delete before GDA 9.28 is released.
In general the following steps should be taken:
Add the
@deprecatedJavadoc tag to the corresponding type/member explaining the reason for deprecation and specifying an alternativeAdd the
@Deprecatedannotation, using theforRemovalandsincepropertiesLog a warning: for classes log this in the constructor(s) and for methods at the start of the method; a DeprecationLogger [uk.ac.diamond.daq.util.logging.deprecation.DeprecationLogger, maintained on gitlab and available from the Target Plaform], which logs subsequent calls with an increasing fallback (i.e. 1st, 3rd, 6th, 11th… call) should be used if the class/method is created/called many times to avoid spamming the logs. It may also be used when this is not the case.
Here is a complete example for a deprecated method:
/** @deprecated use {@link #setDirectory} instead.
* This method will be removed in GDA 9.28 */
@Deprecated(forRemoval = true, since = "GDA 9.26")
public void setDirLUT(String dirLUT) {
logger.warn("setDirLUT is deprecated, use setDirectory instead. This will be removed in GDA 9.28");
setDirectory(dirLUT);
}
And an example which uses the DeprecationLogger:
private final static DeprecationLogger logger = DeprecationLogger.getLogger(DeprecatedClass.class);
DeprecatedClass(String name) {
logger.deprecatedClass("9.29", "uk.ac.diamond.daq.NonDeprecatedClass");
}
@Deprecated(since="GDA 9.27" forRemoval=true)
public String getDirLUT() {
logger.deprecatedMethod("getDirLUT()", "9.29", "getDirectory()")
return getDirectory();
}
A list of deprecated items can be found within the GDA Javadocs.
19.3. Adding new beamline to GDA¶
19.3.1. gda-diamond.git¶
Create new Java project (e.g. b07-2-config) in configurations folder (e.g. ../workspace_git/gda-diamond.git/configurations/b07-2-config/)
Add more files to configuration folder:
configurations/b07-2-config/config.toml
server.spring-xml = [ "servers/_common/server.xml", "servers/_common/devices/all_devices.xml", "servers/${gda.mode}/all_devices.xml" ] client.spring-xml = [ "clients/${gda.mode}/client.xml", "clients/_common/client.xml" ] properties = [ "properties/${gda.mode}/${gda.mode}_instance_java.properties", "properties/_common/common_instance_java.properties", ] logging = "properties/_common/logging_customisation.xml" [defaults] "gda.mode" = "dummy" [system] "gov.aps.jca.JCALibrary.properties" = "${gda.config}/properties/${gda.mode}/JCALibrary.properties" [extras.dls] root = "../../dls-config" server.spring-xml = [ "servers/_common/file_registrar.xml", "servers/${gda.mode}/icat_xml_creator.xml", "servers/_common/machine_status.xml", ] client.spring-xml = [ "clients/_common/serverFileListener.xml" ]
configurations/b07-2-config/component.def
<?xml version="1.0" encoding="UTF-8"?> <targlets:ComponentDefinition xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:targlets="http://www.eclipse.org/oomph/targlets/1.0" xsi:schemaLocation="http://www.eclipse.org/oomph/targlets/1.0 https://raw.githubusercontent.com/eclipse-oomph/oomph/master/setups/models/Targlets.ecore" id="b07-2-config"> <requirement name="dls-config"/> <requirement name="uk.ac.gda.beamline.b07_2.feature.feature.group"/> </targlets:ComponentDefinition>
Create new plug-in Java project (e.g. uk.ac.gda.beamline.b07-2) in plugins folder using Eclipse menu:
File -> New -> Project -> Plug-in Development -> Plug-in Project
Make sure not using standard location - use plugins folder and add plugin name at the end. (e.g. ../workspace_git/gda-diamond.git/plugins/uk.ac.gda.beamline.b07-2/)
Create a Rich Client Application - yes
Eclipse RCP Application template (or RCP3.x application)
Amend Generated product - should be based on feautures and application uk.ac.gda.client.application
Depending on client code structure and e4/e3 framework there could be different files in project (check similar beamlines and compare), but there must be at least plugin.xml and manifest.mf files. Plugin should extend org.eclipse.core.runtime.products:
```
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.4"?>
<plugin>
<extension
id="product"
point="org.eclipse.core.runtime.products">
<product
application="uk.ac.gda.client.application"
description="A GDA client for the beamline B07-2"
name="Beamline B07-2">
<property
name="windowImages"
value="platform:/plugin/uk.ac.gda.core/icons/GDAlogos/GDALogo16.png,platform:/plugin/uk.ac.gda.core/icons/GDAlogos/GDALogo32.png,platform:/plugin/uk.ac.gda.core/icons/GDAlogos/GDALogo48.png,platform:/plugin/uk.ac.gda.core/icons/GDAlogos/GDALogo64.png,platform:/plugin/uk.ac.gda.core/icons/GDAlogos/GDALogo128.png">
</property>
<property
name="aboutImage"
value="platform:/plugin/uk.ac.gda.core/icons/GDAlogos/GDALogomed.png">
</property>
<property
name="appName"
value="Beamline B07-2">
</property>
</product>
</extension>
<extension
id="uk.ac.gda.beamline.b07-2.fragment"
point="org.eclipse.e4.workbench.model">
<fragment
apply="always"
uri="fragment.e4xmi">
</fragment>
</extension>
</plugin>
```
amend corresponding Maven pom.xml file ../workspace_git/gda-diamond.git/plugins/pom.xml:
<module>uk.ac.gda.beamline.b07-2</module>
Optionally - Copy the Eclipse project settings (files in .settings/) and gitignore from an existing project such as uk.ac.gda.core as the default settings are quite minimal.
Create new Feature project (e.g. uk.ac.gda.beamline.b07_2.feature) in feature folder using Eclipse menu:
NOTE: Use only underscores (not hyphen!) in feature names.
File -> New -> Project -> Plug-in Development -> Feature Project
Make sure not using standard location - use plugins folder and add feature name at the end. (e.g. ../workspace_git/gda-diamond.git/features/uk.ac.gda.beamline.b07_2.feature/)
Initialize from plug-ins list (find corresponding plugin)
Take a look at other beamlines examples and make corrections if required
Move client product from plugin folder to this feature folder
Create new Java project in product folder (e.g. ../workspace_git/gda-diamond.git/products/uk.ac.gda.beamline.b07-2.product/)using Eclipse menu:
File -> New -> Java Project
Include already created feature project
Make sure ../workspace_git/gda-diamond.git/products/uk.ac.gda.beamline.p60.product/.project includes new feature in projects:
``` <?xml version="1.0" encoding="UTF-8"?> <projectDescription> <name>uk.ac.gda.beamline.b07-2.product</name> <comment></comment> <projects> <project>uk.ac.gda.beamline.b07_2.feature</project> </projects> <buildSpec> </buildSpec> <natures> </natures> </projectDescription> ```
create symlink (../workspace_git/gda-diamond.git/products/uk.ac.gda.beamline.b07-2.product/uk.ac.gda.beamline.b07-2.product)
``` uk.ac.gda.beamline.b07-2.product -> ../../features/uk.ac.gda.beamline.b07_2.feature/uk.ac.gda.beamline.b07-2.product ```
19.3.2. daq-aggregator.git¶
amend ../workspace_git/daq-aggregator.git/pom.xml
<profile> <id>b07-2</id> <modules> <module>features/uk.ac.gda.beamline.b07_2.feature</module> <module>products/uk.ac.gda.beamline.b07-2.product</module> </modules> </profile>
amend to ../workspace_git/daq-aggregator.git/setup/GDAWorkspace-master.setup
<choice value="b07-2" label="b07-2 workspace"/>
<requirement name="b07-2-config"/>