Introduction

This is documentation for developers and maintainers of Hexatomic.

If you are looking for documentation of how to use Hexatomic, please refer to the user documentation.

Contributing to Hexatomic development

Hexatomic is an open source project. We welcome contributions from the community.

If you want to contribute code to Hexatomic, please make yourself familiar with the general contributing guidelines first, then continue to read this documentation.

The contributing guidelines also include information on how to report a bug, request a feature, etc.

Requirements

Hexatomic is an Eclipse e4 application, built on the Eclipse Platform for rich client applications, and implemented in Java. It is built with Apache Maven and the Eclipse Tycho extension, and versioned with Git.

It will be easier for you to contribute to Hexatomic if you already have some experience with these technologies.

Here are links to some resources that can help you get started:

License


Unless otherwise noted, this documentation is licensed under a CC0 1.0 Universal (CC0 1.0) license. Please see the section License for details.

1

Daisie Huang and Ivan Gonzalez (eds): "Software Carpentry: Version Control with Git." Version 2016.06, June 2016, https://github.com/swcarpentry/git-novice, doi:https://doi.org/10.5281/zenodo.57467

Development

Development setup

Operating system for development

You can develop and build Hexatomic on Linux, Mac OS and Windows. We suggest that you use Linux for development, to avoid non-straightforward install procedures for required technologies as well as potential issues with file encodings, paths, and file permissions.

Required software

Hexatomic is implemented in Java, built with Apache Maven, and versioned with Git. You need all three on your computer to contribute code to Hexatomic.

The documentation is written in Markdown and generated with mdbook.

Java 1.8

You need to have a copy of the Java Development Kit (JDK), Version 1.8 (sometimes referred to as Java 8) installed on your computer. It shouldn't make any difference whether you use the open OpenJDK implementation of Java, or an Oracle JDK. We suggest that you use OpenJDK in its latest build (which was 1.8u232 at the time of writing). See the OpenJDK 8 Updates site to find out what the currently latest build is. OpenJDK is included in the package management repositories (dpkg (via apt), RPM, etc.) of most Linux distributions. For stand-alone packages, you can use the installers distributed by the AdoptOpenJDK project. AdoptOpenJDK packages are are available for Windows, MacOS, and Linux.

You can check which version of Java you have installed by typing the following command into the terminal of your computer:

java -version

On Linux, this should produce the following output. The second line may look different, depending on the Linux distribution you use.

openjdk version "1.8.0_222"
OpenJDK Runtime Environment (build 1.8.0_222-8u222-b10-1ubuntu1~18.04.1-b10)
OpenJDK 64-Bit Server VM (build 25.222-b10, mixed mode)

Apache Maven

You need to have a copy of Apache Maven in version 3.6.0 or newer installed on your computer. To find out how to install Maven on your system, please see the Apache Maven website.

You can check which version of Maven you have installed by typing the following command into the terminal of your computer:

mvn -version

On Linux, this should produce the following output. The first line is the important one, the other ones may look different, depending on the Linux distribution you use.

Apache Maven 3.6.0
Maven home: /usr/share/maven
Java version: 1.8.0_222, vendor: Private Build, runtime: /usr/lib/jvm/java-8-openjdk-amd64/jre
Default locale: en_US, platform encoding: UTF-8
OS name: "linux", version: "5.0.0-23-generic", arch: "amd64", family: "unix"

Git

You need to have a copy of Git in version 2.17.1 or newer installed on your computer. To find out how to install Git on your system, please see the Git website.

You can check which version of Git you have installed by typing the following command into the terminal of your computer:

git --version

On Linux, this should produce the following output.

git version 2.17.1

mdbook

If you want to build the documentation online book locally to, e.g., see your changes as they will look like online, you need to have a copy of mdbook, version 0.3.1 or newer installed on your computer. To find out how to install mdbook on your system, please see the mdbook website.

You can check which version of mdbook you have installed by typing the following command into the terminal of your computer:

mdbook --version

On Linux, this should produce the following output.

mdbook v0.3.1

Suggested editor: Eclipse Integrated Development Environment (IDE)

Hexatomic is built on the Eclipse 4 Platform, and takes the form of an Eclipse product composed of Eclipse plugins and Eclipse features. While you can certainly write your Java, XML, Markdown, etc., in any editor of your choice, we suggest that you use the free and open source Eclipse IDE, version 2019-06 or newer.

You can download it from the Eclipse download website.

Eclipse IDE installation

The download contains an installer which lets you configure the setup of your IDE. To develop Hexatomic, you will need to install Eclipse IDE for RCP and RAP Developers:

  • Extract the downloaded file.
  • Start the Eclipse installer (eclipse-inst).
  • From the list of available Eclipse packages, choose Eclipse IDE for RCP and RAP Developers.

During the installation, accept licenses, set directories, etc., as you see fit.

After you have installed the IDE itself, install the required tool plugins.

IDE Plugin installation

If not noted otherwise, Eclipse plugins are installed as follows:

  • Open the Install Wizard via the menu Help > Install New Software...
  • In the Work with: field, enter the URL of the Update Site for the plugin, given in brackets below.
  • Select the plugins you want to install, and install it with the help of the wizard.

List of Eclipse IDE plugins required for Hexatomic development

Getting the source code

The Hexatomic source code is hosted on GitHub at https://github.com/hexatomic/hexatomic.

You don't have direct write permissions to this main source code repository, unless you are a core contributor. This means that you will make your changes in your own copy (fork) of the repository, and request that we merge your changes into the main code base when you are finished (pull request).1

Downloading the source code to your computer

First, you need to create a fork of the Hexatomic main repository on GitHub:

  1. Log in to your GitHub account (github.com/login).
  2. Go to https://github.com/hexatomic/hexatomic, and click the Fork button in the upper right-hand corner of the repository page. This will create a copy of the repository under your own account.

To download the source code onto your computer and put it under local version control with Git, type the following command into the terminal of your computer:

git clone https://github.com/<your-GitHub-user-name>/hexatomic.git

It will download the latest version of the source code in the master branch to a sub-directory hexatomic, along with the complete Git version history.

For your actual contribution, you will need to create a new Git branch, but this is explained in detail in section Workflow. For now, all that is left to do is get the Hexatomic source code into your IDE.

Getting the source code into the Eclipse IDE

If you have set up the Eclipse IDE for development of Hexatomic, as described in the section Development setup, you will have to import the source code from your local Git repository.

To import the Hexatomic into your Eclipse IDE, do the following:

  1. Start Eclipse
  2. Open the Import window via the menu File > Import
  3. Select the import wizard Existing Projects into Workspace and click Next >
  4. In Select root directory, select the directory where you have downloaded the Hexatomic source code to (the Git root)
  5. In the Options section of the window, activate Search for nested projects
  6. Click Finish

Congratulations, you are now set up to start contributing to Hexatomic!

Before starting to work on your contribution, please read the section Workflow carefully.

1

For more info on forks and pull requests, read the section Workflow.

Running and debugging Hexatomic in Eclipse

Hexatomic is a modular project, and while it is possible to debug a user-defined subset of its bundles, it may be more useful to debug the complete application.

To run or debug Hexatomic from within the Eclipse IDE, with all the features and bundles, you have to open the org.corpus_tools.hexatomic.product project which contains the Hexatomic product definition. In this project, open the org.corpus_tools.hexatomic.product file in Eclipse.

Location of the product definition file in the Project Explorer

To debug Hexatomic, click on the Launch an Eclipse application in Debug mode link in the overview tab of the Product Configuration Editor. To run the product without debugging, click Launch an Eclipse application on the same page. If you don't see the Product Configuration Editor, you may have opened the file with a different editor instead. In this case, right-click on the org.corpus_tools.hexatomic.product file, and choose Open With > Product Configuration Editor.

Product configuration file editor with launch links

Development workflow

Summary

  • We use Gitflow for developing Hexatomic, with the Maven plugin for Gitflow.
  • To contribute new functionality, create a feature branch by running mvn gitflow:feature-start in the repository root, and create a draft pull request against develop on https://github.com/hexatomic/hexatomic.
  • To contribute a bug fix, add to documentation, change relesae engineering, create a hotfix branch by running mvn gitflow:hotfix-start in the repository root, and create a draft pull request against master on https://github.com/hexatomic/hexatomic.
  • Describe your changes in the pull request title and complete the pull request form.
  • When you think that your contribution is good to be merged into the main repository, change the pull request status to Ready for review.
  • Collaborate with the maintainer to fulfill any missing requirements and to merge your changes into the main repository.

Hexatomic follows a common development workflow: Gitflow. It is a development workflow that works with a specific Git branch structure, and is actually quite simple to understand and follow, and based on just a few rules. Also, Hexatomic actually uses a Maven plugin for Gitflow, which makes it really easy to work with Gitflow.

If you are interested in learning more about Gitflow, read the original blog post describing it. The figure below gives an overview of the complete Gitflow workflow.


Figure: Git branching model overview. Graphic by Vincent Driessen from the original blog post "A successful Git branching model". Licensed under a CC BY-SA license.

The Gitflow branching model

Gitflow assumes that there is a single, central "repository of truth". In our case, this is the main repository at https://github.com/hexatomic/hexatomic.

Main branches

In the repository, there are two main branches that always exist and have an infinite lifetime:

  • master
  • develop

The master branch always reflects the production-ready state. In other words, master will always contain the releases of Hexatomic, and any changes that are merged into master are releases.

The develop branch always contains the latest finished development changes. That means, whenever a feature is ready to be released, it is merged into develop to wait for the next release (which will then contain the new feature).

Branches you do your work in

In Gitflow, there are two types of branches where the actual work is happening:

  • feature branches are used for developing new functionality.
  • hotfix branches are used to fix bugs in releases, and to fix documentation and release engineering for releases without actually changing functionality.

This is an important distinction, because depending on what type of contribution you want to make, it means that you have to start your work by running different commands.

Contribute new functionality (feature)

To contribute new functionality to Hexatomic, create a feature branch which is based on the develop branch.

  1. Download the develop branch from your fork repository:
# Download the contents of the remote `develop` branch (and others) to your local repository
git fetch
# Switch to the local branch `develop`
git checkout develop
  1. Install the project as is to prepare your development work:
mvn clean install
  1. Create the new feature branch:
mvn gitflow:feature-start
  1. Give the feature branch a name as prompted by the Maven Gitflow plugin.
  2. Create a draft pull request against the develop branch of https://github.com/hexatomic/hexatomic and start working.
  3. Once you've finished your work, run mvn clean install to make sure that the project builds correctly.
  4. If any files were changed during mvn clean install - e.g., license headers have been added automatically - make sure to commit and push these changes.
  5. Make sure that you have documented your changes in the changelog (CHANGELOG.md) in the [Unreleased] section, and that the updated changelog is pushed to your feature branch.
  6. Once you are ready to have your changes merged into the project, request a review of your pull request from the maintainer by requesting a review from the maintainer (via the Reviewers settings for the pull request) and clicking Ready to review in the pull request page on GitHub.

Contribute a bug, documentation, or release engineering fix for a released version (hotfix)

To contribute new a bug, documentation, or release engineering fix to Hexatomic, create a hotfix branch which is based on the master branch.

  1. Create the new hotfix branch:
mvn gitflow:hotfix-start
  1. Give the hotfix branch a name as prompted by the Maven Gitflow plugin.
  2. Create a draft pull request against the master branch of https://github.com/hexatomic/hexatomic and start working.
  3. Once you've finished your work, run mvn clean install to make sure that the project builds correctly.
  4. If any files were changed during mvn clean install - e.g., license headers have been added automatically - make sure to commit and push these changes.
  5. Make sure that you have documented your changes in the changelog (CHANGELOG.md) in the [Unreleased] section, and that the updated changelog is pushed to your hotfix branch.
  6. Once you are ready to have your changes merged into the project, request a review of your pull request from the maintainer by requesting a review from the maintainer (via the Reviewers settings for the pull request) and clicking Ready to review in the pull request page on GitHub.

Create a pull request for your contribution before you start working

Once you are ready to start working on your contribution, it's time to let the Hexatomic maintainer know about it, so that they can discuss the new changes and provide comments and support while you work. The way to do this is via a pull request on GitHub. Pull requests (PRs) aren't part of Git as such, but a feature of the GitHub platform.

This is how you start a draft pull request:

  1. Go to https://github.com and log in.
  2. In your fork of the Hexatomic main repository (github.com/<your-user-name>/hexatomic), select the branch you have been working on via the Branches tab or the Branch dropdown menu.
  3. Click the button New pull request. It's next to the Branch dropdown menu.
  4. Set the correct target of the pull request:
    • For features, the base repository is hexatomic/hexatomic and the base branch is develop, the compare branch is your feature branch.
    • For hotfixes, the base repository is hexatomic/hexatomic and the base branch is master, the compare branch is your hotfix branch.
  5. Click the Create pull request button.
  6. Give your pull request a meaningful title describing your changes.
  7. Complete the pull request form in the editor window.
  8. From the green dropdown menu below the editor, select Draft pull request.
  9. Make sure that Allow edits from maintainers is activated.
  10. Click the Draft pull request button to create your pull request.

Now, anytime you push a new commit to your feature branch, it will also show up in the pull request located in the Hexatomic main repository. This way, the Hexatomic maintainer can track progress, review changes as soon as they come in, and discuss changes with you.

Naming conventions

TODO FIXME BELOW

  • Plugin projects are called org.corpus_tools.hexatomic.<plugin-name> and are stored in /bundles/org.corpus_tools.hexatomic.<plugin-name>.
  • Feature projects are called org.corpus_tools.hexatomic.<feature-name>.feature with an identifier of org.corpus_tools.hexatomic.<feature-name>, and are stored in features/org.corpus_tools.hexatomic.<feature-name>.

Checklist for pull requests

What is a feature contribution, what is a hotfix?

Within the Hexatomic project, hotfixes are changes that are made to a deployed major or minor release. These obviously include functional changes (i.e., bug fixes), but also non-functional changes to Hexatomic, such as updating the documentation to reflect the latest released version, updating the release workflow, etc.

Features are changes that introduce new functionality to the software, while the existing functionality keeps working.

The following table gives some examples.

FeatureHotfix
Add a new editorFix a bug in an existing editor
Add new functionality to an editorFix unwanted behaviour in the release workflow
Add other functionalityUpdate the documentation to reflect the last release
Update documentation to reflect changes in the development workflow

It is important to note that all bug fixes that are made on a released version are hotfixes, and that the develop branch always contains the truth, i.e., always holds the stage of development against which all features must be developed. Implementation of new functionality must always start with a branch from develop via mvn gitflow:feature-start! Do not base your work on any other feature/... or other branches. Finished features are collected in develop before release.

Repositories

Project setup

TODO Merge with repositories.md

Repository structure of hexatomic/hexatomic:

  • Root directory
    • main POM
    • .travis.yml (Travis CI config)
    • Meta files (.gitignore, README.md, LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, etc.)
  • bundles
    • plug-in sub-projects
  • features
    • feature sub-projects
  • docs
    • source files for user and developer/maintainer documentation
  • releng
    • configuration and release engineering files

Setup details

The Hexatomic project in the hexatomic/hexatomic repository is set up generally along the lines of Eclipse Tycho for building plug-ins, OSGi bundles and Eclipse applications - Tutorial by Lars Vogel and Simon Scholz, Version 13.03.2019, and Eclipse RCP (Rich Client Platform) - Tutorial by Lars Vogel, Version 10.12.2018.

This means that

  1. It is built using Eclipse Tycho, a plugin for the Maven build system.
  2. Plug-ins, i.e., units that encapsulate well-defined functionality, are located in the bundles directory.
  3. Features, i.e., units that integrate one or more plug-ins, are located in the features directory.
  4. Configuration and release engineering-related files are located in the releng directory. This includes:
    • Project configuration (for packaging, target platform configuration, etc.)
    • Product definition; in the Eclipse world, products are units that in turn integrate one or more features to define a deliverable software.
    • Target platform definition; the target platform defines the features and plug-ins that Hexatomic is built on top of (against).
    • Update site definition; Hexatomic's features and plug-ins are provided
      1. through a repository in the p2 repository format, from which Hexatomic can be updated automatically and manually from within the application; and
      2. As deployable units, i.e., the actual zip files that users will download in order to get Hexatomic.
    • Miscellanea, e.g., shell scripts for deploying artifacts, etc.
  5. It uses pomless builds, i.e., not every single plug-in or feature needs its own build definition XML file (pom.xml), which saves a lot of manual labour.

Project parent / root POM

Hexatomic has a root POM, i.e., to build the entire project, a single Maven command, e.g., mvn clean install, in the root folder is enough.

Target platform

tpd

Documentation

All folders that are parent folders shall contain a README.md file that explains the contents of the folder.

TODO FIXME BELOW

Other than that, cf. section on documentation!

TODO FIXME ABOVE

Data model

Hexatomic works on instances of a graph-based meta model for linguistic data called Salt.

In Salt, linguistic data is organized in projects:

  • A Salt project contains at least one - and often only one - corpus graph.
  • A corpus graph contains corpora as nodes.
  • The child nodes of a corpus can again be corpora (so-called sub-corpora) and documents.
  • Each document has a document graph, which is the model element containing the actual linguistic data:
    • primary data sources (text, audio, or video material), and
    • annotations.

Salt is very powerful in that it is theory-neutral and tagset-independent, and can model a vast variety of linguistic data and annotations.

To find out more about the Salt meta model for linguistic data and its Java API, please refer to the Salt homepage, and the Salt documentation.

Accessing the data model

During runtime, Hexatomic operates on a single Salt project at any one time. The currently opened Salt project is part of the global state of the application, and can be accessed by injecting an instance of the ProjectManager singleton into your code. For an overview of how dependency injection works in Eclipse-based applications such as Hexatomic, see Lars Vogel's tutorial "Dependency injection and Eclipse".

import javax.inject.Inject;
import org.corpus_tools.hexatomic.core.ProjectManager;
import org.corpus_tools.salt.common.SaltProject;

public class MyClass {
	
	@Inject
	private ProjectManager projectManager;
	
	public void execute() {
		SaltProject theProject = projectManager.getProject();
	}
}

You can register for any changes on the Salt project (e.g., added annotations to a document), by adding a Salt notification listener to the project manager using its addListener(Listener listener) function. For more information on Salt notification listener's, see the Salt notification documentation. After registering your listener, you will receive all updates for all documents and all changes to the project structure. You have to decide in your own code if you need to handle an update, e.g., because it is related to a document you are editing for which the event should trigger a redraw of the editor you are implementing.

Logging and error handling

Logging

Hexatomic uses the SLF4J logging API to log messages. To enable a logger for a specific class, create a static final variable which holds the class-specific logging object.

private static final org.slf4j.Logger log = 
	org.slf4j.LoggerFactory.getLogger(MyClass.class);

You can use this log object everwhere in the code to output debug, info, warning or error messages to the console or to the log files. 

int counter = 101;
log.debug("Selecting created document {}.", 101);

See the SLF4J manual for more information on the API.

To implement the API, we use the Logback library in the org.corpus_tools.hexatomic.core bundle. For testing and debugging purposes, there is a logback-test.xml file in the root of the logging bundle. This configuration file is loaded whenever Hexatomic is started from Eclipse using the Debug/Run configuration and will output messages on the debug level. When compiling the Hexatomic product, the file logback.xml is copied to the product root directory and loaded from there. This allows a user/developer to customize the logging on their own, even when using a published binary artifact instead of debugging directly from the Eclipse IDE. Per default, only messages from the info level and above are printed to the command line. See the Logback documentation how to write or adapt this file.

Handling exceptions

The core bundle exports the special org.corpus_tools.hexatomic.core.errors.ErrorService service which should be used to display error messages to the user.

To report an exception, simply call the handleException(...) function of the service with an error message, the exception object, and the class of the caller, i.e., the class in which you catch the exception.

project = SaltFactory.createSaltProject();
try {
	project.loadCorpusStructure(path);
} catch (SaltException ex) {
	// In this example the calling function is part of the ProjectManager class.
	errorService.handleException("Cannot load project from " + path.toString(), ex, 
		ProjectManager.class);
}

This will produce the exception dialog shown below. It includes the error message, and a stack trace which the user can inspect by expanding "Details" (which is initially hidden).

An example for an exception dialog

In addition to the dialog, a log entry is added. This log entry uses the logger for the caller class which has been passed to the handleException(...) method.

18:52:54.324 [main] ERROR o.c.h.c.ProjectManager - Exception occured: Could not load salt project from file:/tmp
org.corpus_tools.salt.exceptions.SaltResourceException: Can not load SaltProject, because path '/tmp/saltProject.salt' does not exist. 
	at org.corpus_tools.salt.util.SaltUtil.loadSaltProject(SaltUtil.java:835) ~[org.corpus-tools.salt-api_3.3.8.20190808115214.jar:na]
	at org.corpus_tools.salt.common.impl.SaltProjectImpl.loadCorpusStructure(SaltProjectImpl.java:148) ~[org.corpus-tools.salt-api_3.3.8.20190808115214.jar:na]
	at org.corpus_tools.hexatomic.core.ProjectManager.open(ProjectManager.java:108) ~[org.corpus_tools.hexatomic.core/:na]
	at org.corpus_tools.hexatomic.core.handlers.OpenSaltProjectHandler.execute(OpenSaltProjectHandler.java:26) [org.corpus_tools.hexatomic.core/:na]
	at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) ~[na:1.8.0_232-ea]

Showing error messages

If an error does not originate from an exception, you can use the showError(...) function of the error service to display a dialog. This function takes an optional dialog title, the error message, and the class of the caller as arguments, as shown in the following example.

if (hasChildren) {
	errorService.showError("Error when deleting (sub-) corpus",
			"Before deleting a (sub-) corpus, first delete all its child elements.", this.getClass());
	return;
}

This produces both an error dialog and a logging output (without stack trace).

An example for an error dialog

19:03:26.013 [main] ERROR o.c.h.c.CorpusStructureView$8 - Error when deleting (sub-) corpus: Before deleting a (sub-) corpus, first delete all its child elements.

Adding a new editor

Following the principle of "separation of concerns", editors should generally be developed in separate, dedicated bundles in the bundles directory of the project. Exceptions to this rule should be based on compelling reasons for including an editor in an existing bundle project. Reasons may include, for example, that the architectural overhead for creating a very simple editor may be too high. In cases of uncertainty, follow the rule that changes to software should keep the maintenance effort in proportion to the benefit of the change, and generally as small as possible.

In Eclipse 4, additions to the user interface are organized in so-called Parts. A part consists of two components:

  • a PartDescriptor entry in the fragment.e4xmi file of the bundle containing the new editor, and
  • the actual Java class implementing the behavior.

Adding a minimal Java class

Add a Java class to your bundle project. This class does not need to inherit any interface, but should have a method with the @PostConstruct annotation.

public class TextViewer {
	@PostConstruct
	public void postConstruct(Composite parent, MPart part, ProjectManager projectManager) { 
		// TODO: add actual editor implementation
	}
}

This example injects the SWT parent composite which can be used to construct user interface elements and the part parameter, which describes the application model for this part.

SWT ("Standard Widget Toolkit") is the default user interface widgets toolkit for Eclipse-based applications, such as Hexatomic, and is used in this example. For more information, see the Eclipse SWT project website. For information on the application model of Eclipse-based applications, see the Eclipse Wiki page on the UI model.

The projectManager is an Hexatomic specific service that provides access to the global Salt project which is currently loaded.

Note that you can directly add the SWT instructions to define your user interface in the code, or use the Eclipse Window Builder, which is a graphical editor for user interfaces based on SWT (and other technologies).

Adding a part to the application model

To add the newly created class to the Eclipse RCP 4 application model, open the fragment.e4xmi file of the existing bundle, or create a new one via the File -> New -> Other menu and choose "New Model Fragment".

Adding a new fragment model file

In the fragment editor, add a new model fragment by selecting "Model fragments" and clicking on the "Add" button.

Adding a new model fragment in the editor

Edit the model fragment properties by selecting the newly created entry. Make sure to set the extended element ID to xpath:/and the feature name to descriptors (1). This means that the model fragment extends the part descriptors of the application. Then, add a new part descriptor with the Add button (2).

Edit model fragment properties

Select the new part descriptor in the model fragment editor and you can edit several properties, such as the caption of the part, or an icon. Make sure to set the "Class URI" field to the newly created editor class. You can use the "Find" button to navigate the workspace and insert the proper value. Also, the "Category" must be set to org.corpus_tools.hexatomic.tag.editor to mark that this part is an Hexatomic editor. The Label field will be used as a name for the editor, for example in a menu from which the user will choose one of the editors available to open a document with.

Part descriptor general properties

Getting the associated Salt document to display

When an editor part is created, it is initialized with a state. This state can hold internal configurations, but also contains the ID of the associated Salt document that this editor should edit. The actual ID is set to the editor part's state in the class handling user actions to open a Salt document, org.corpus_tools.hexatomic.core.handlers.OpenSaltDocumentHandler.

It is stored in the part state in a setting with the name org.corpus_tools.hexatomic.document-id. The injected ProjectManager can then be used to get the actual document.

String documentID = part.getPersistedState()
	.get("org.corpus_tools.hexatomic.document-id");
Optional<SDocument> doc = projectManager.getDocument(documentID);

Maintenance

GitFlow

Continuous integration

Pull Requests

Releases

Versioning

Hexatomic adheres to Semantic Versioning 2.0.0.

Versions take the form of MAJOR.MINOR.PATCH.

  • MAJOR versions are incompatible with each other. MAJOR is incremented, when an incompatible API change is introduced.
  • MINOR versions add "features", i.e., backwards-compatible functionality.
  • PATCH versions add backwards-compatible bug fixes.

Versioning of product, features, and modules

Hexatomic is complex software: It consists of modules which are bundled in features. The actual software product deliverable is again made up of several features.

Despite this, we apply a unified versioning scheme for Hexatomic. This means that changes on any level of modularity (module, feature, product) triggers a change in the unified version number.

Examples:

  • A bug in a module is fixed. All version numbers in the Hexatomic product, all of its features and all of its bundles increment the PATCH identifier.
  • A new module - developed by Hexatomic contributors or a third-party module - is added to a feature. The module adds new functionality to Hexatomic. All version numbers in the Hexatomic product, all of its features and all of its bundles increment the MINOR identifier.

Scope

The versioning scheme described above applies to Hexatomic as present in the hexatomic/hexatomic repository on GitHub. It does not automatically apply to contributions which live in other repositories.

Licensing

This section describes how licensing is handled in Hexatomic.

What licenses is Hexatomic licensed under?

The Hexatomic software is licensed under the Apache License, Version 2.0. Read the whole license text to learn more about the license.

The Hexatomic documentation is licensed under a CC0 1.0 Universal (CC0 1.0) license. See the License page for more information.

Automating the fulfillment of license requirements

In order to make it easier to maintain the licenses for Hexatomic and its dependencies, we automate the fulfillment of license requirements.

For this, Hexatomic includes the Maven License Plugin from MojoHaus in the build. You can read about the plugin on the Maven License Plugin website.

Pull requests

Working with pull requests (PRs)

  • To include pull requests in the repository, do Rebase and merge rather than the other merging options on GitHub.
  • You can change the pull request template in the file .github/PULL_REQUEST_TEMPLATE.md

Checklist for handling pull requests

  1. Make sure that the pull request is against the correct branch
    • New API is requested to be merged into develop
    • Bug fixes are requested to be merged into master
  2. Check everything is there [TODO, documentation, tests, correct version number, etc.]
  3. Use the Rebase and merge option to merge the pull request
  4. Pull the

Releases

Feature releases

To release a new feature (i.e., minor) version of Hexatomic, run the following commands in the repository root directory.

  1. git checkout develop - Checks out the develop branch (feature releases are always based on develop).
  2. git pull origin develop - Updates the local develop branch.
  3. mvn clean install - Builds the project, runs tests, and may update the file headers in Java files.
  4. git add . - Adds the updated files - if any - to the Git index.
  5. git commit -m "Update file headers" - Commits the updates to version control.
  6. git push - Updates the remote develop branch.
  7. mvn gitflow:release-start - Starts the release process.
  8. The Maven GitFlow plugin will then prompt you to enter a version number for the release. Make sure you enter a version identifier according to semantic versioning, in the format MAJOR.MINOR.PATCH. Do not use a -SNAPSHOT suffix!
  9. Check if the [Unreleased] changelog section in CHANGELOG.md is complete and up-to-date. Make changes, commit and push if necessary.
  10. mvn keepachangelog:release -N - Updates the changelog in the release branch.
  11. git add . - Adds the updated changelog to the Git index.
  12. git commit -m "Update changelog" - Commits the updated changelog to version control.
  13. git push - Updates the remote release branch.
  14. mvn gitflow:release-finish - Finalizes the release process.

Hotfix releases

Hotfixes come into the project via pull requests of a hotfix branch against master. Important: Do not merge pull requests from hotfix branches into master!

Instead, checkout the hotfix branch locally, and start the merge and release process with the Maven GitFlow plugin:

  1. git checkout hotfix/{hotfix version} - Checks out the respective hotfix branch.
  2. git pull origin hotfix/{hotfix version} - Checks for any remote changes to the branch.
  3. mvn clean install - Builds the project, runs tests, and may update the file headers in Java files.
  4. git add . - Adds the updated files - if any - to the Git index.
  5. git commit -m "Update file headers" - Commits the updates to version control.
  6. git push - Updates the remote develop branch.
  7. Check if the [Unreleased] changelog section in CHANGELOG.md is complete and up-to-date. Make changes, commit and push if necessary.
  8. mvn keepachangelog:release -N - Updates the changelog in the release branch.
  9. git add . - Adds the updated changelog to the Git index.
  10. git commit -m "Update changelog" - Commits the updated changelog to version control.
  11. git push - Updates the remote release branch.
  12. mvn gitflow:hotfix-finish - Finalizes the hotfix and finishes the merge and release procedure.

What to do when releases go wrong?

When a feature release doesn't work as expected, simply

  1. Checkout the develop branch (git checkout develop).
  2. Delete the release branch for the version you wanted to release (git branch -d release/{version}).
  3. Delete the same branch on GitHub (via the web interface).
  4. Restart the release process from the top.

When a hotfix release doesn't work as expected, simply

  1. Make the necessary changes in the hotfix branch, then continue with the merge and release process.

Checklist

Governance

The decision-making processes for the Hexatomic project are described in the contributing guidelines in the main Hexatomic repository.

License


With the exception of the content listed below, this documentation is licensed under a CC0 1.0 Universal (CC0 1.0) license.

Content excepted from the CC0 1.0 Universal license

CC0 1.0 Universal legal code

Creative Commons Legal Code

CC0 1.0 Universal

    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
    HEREUNDER.

Statement of Purpose

The laws of most jurisdictions throughout the world automatically confer
exclusive Copyright and Related Rights (defined below) upon the creator
and subsequent owner(s) (each and all, an "owner") of an original work of
authorship and/or a database (each, a "Work").

Certain owners wish to permanently relinquish those rights to a Work for
the purpose of contributing to a commons of creative, cultural and
scientific works ("Commons") that the public can reliably and without fear
of later claims of infringement build upon, modify, incorporate in other
works, reuse and redistribute as freely as possible in any form whatsoever
and for any purposes, including without limitation commercial purposes.
These owners may contribute to the Commons to promote the ideal of a free
culture and the further production of creative, cultural and scientific
works, or to gain reputation or greater distribution for their Work in
part through the use and efforts of others.

For these and/or other purposes and motivations, and without any
expectation of additional consideration or compensation, the person
associating CC0 with a Work (the "Affirmer"), to the extent that he or she
is an owner of Copyright and Related Rights in the Work, voluntarily
elects to apply CC0 to the Work and publicly distribute the Work under its
terms, with knowledge of his or her Copyright and Related Rights in the
Work and the meaning and intended legal effect of CC0 on those rights.

1. Copyright and Related Rights. A Work made available under CC0 may be
protected by copyright and related or neighboring rights ("Copyright and
Related Rights"). Copyright and Related Rights include, but are not
limited to, the following:

  i. the right to reproduce, adapt, distribute, perform, display,
     communicate, and translate a Work;
 ii. moral rights retained by the original author(s) and/or performer(s);
iii. publicity and privacy rights pertaining to a person's image or
     likeness depicted in a Work;
 iv. rights protecting against unfair competition in regards to a Work,
     subject to the limitations in paragraph 4(a), below;
  v. rights protecting the extraction, dissemination, use and reuse of data
     in a Work;
 vi. database rights (such as those arising under Directive 96/9/EC of the
     European Parliament and of the Council of 11 March 1996 on the legal
     protection of databases, and under any national implementation
     thereof, including any amended or successor version of such
     directive); and
vii. other similar, equivalent or corresponding rights throughout the
     world based on applicable law or treaty, and any national
     implementations thereof.

2. Waiver. To the greatest extent permitted by, but not in contravention
of, applicable law, Affirmer hereby overtly, fully, permanently,
irrevocably and unconditionally waives, abandons, and surrenders all of
Affirmer's Copyright and Related Rights and associated claims and causes
of action, whether now known or unknown (including existing as well as
future claims and causes of action), in the Work (i) in all territories
worldwide, (ii) for the maximum duration provided by applicable law or
treaty (including future time extensions), (iii) in any current or future
medium and for any number of copies, and (iv) for any purpose whatsoever,
including without limitation commercial, advertising or promotional
purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
member of the public at large and to the detriment of Affirmer's heirs and
successors, fully intending that such Waiver shall not be subject to
revocation, rescission, cancellation, termination, or any other legal or
equitable action to disrupt the quiet enjoyment of the Work by the public
as contemplated by Affirmer's express Statement of Purpose.

3. Public License Fallback. Should any part of the Waiver for any reason
be judged legally invalid or ineffective under applicable law, then the
Waiver shall be preserved to the maximum extent permitted taking into
account Affirmer's express Statement of Purpose. In addition, to the
extent the Waiver is so judged Affirmer hereby grants to each affected
person a royalty-free, non transferable, non sublicensable, non exclusive,
irrevocable and unconditional license to exercise Affirmer's Copyright and
Related Rights in the Work (i) in all territories worldwide, (ii) for the
maximum duration provided by applicable law or treaty (including future
time extensions), (iii) in any current or future medium and for any number
of copies, and (iv) for any purpose whatsoever, including without
limitation commercial, advertising or promotional purposes (the
"License"). The License shall be deemed effective as of the date CC0 was
applied by Affirmer to the Work. Should any part of the License for any
reason be judged legally invalid or ineffective under applicable law, such
partial invalidity or ineffectiveness shall not invalidate the remainder
of the License, and in such case Affirmer hereby affirms that he or she
will not (i) exercise any of his or her remaining Copyright and Related
Rights in the Work or (ii) assert any associated claims and causes of
action with respect to the Work, in either case contrary to Affirmer's
express Statement of Purpose.

4. Limitations and Disclaimers.

 a. No trademark or patent rights held by Affirmer are waived, abandoned,
    surrendered, licensed or otherwise affected by this document.
 b. Affirmer offers the Work as-is and makes no representations or
    warranties of any kind concerning the Work, express, implied,
    statutory or otherwise, including without limitation warranties of
    title, merchantability, fitness for a particular purpose, non
    infringement, or the absence of latent or other defects, accuracy, or
    the present or absence of errors, whether or not discoverable, all to
    the greatest extent permissible under applicable law.
 c. Affirmer disclaims responsibility for clearing rights of other persons
    that may apply to the Work or any use thereof, including without
    limitation any person's Copyright and Related Rights in the Work.
    Further, Affirmer disclaims responsibility for obtaining any necessary
    consents, permissions or other rights required for any use of the
    Work.
 d. Affirmer understands and acknowledges that Creative Commons is not a
    party to this document and has no duty or obligation with respect to
    this CC0 or use of the Work.