- What is core and non-core development?
- Open, by default
- Source code
- Coding standards
- Reuse not repetition
- Managing multiple developers and version control
- Build artefacts
- Release versioning
- Continuous integration
- Issue tracker
- PickCells Colony forum
In this page we document our approach to developing PickCells.
What is core and non-core development?
Core development of PickCells relates to development of the PickCells architecture and framework, developments which are held within the PickCells source code repositories and are distributed as part of PickCells. Generally, core development includes:
- Developing features which provide new functionality to other modules. For example, see the issue Provide API to easily obtain segmented object thumbnails.
- Developments which affect the behaviour of the PickCells framework.
- Developments which could potentially lead to changes in APIs.
- Developments whichy record user’s actions e.g. see the PickCells colonly forum discussion Auto-generated pipelines, or the issue Add Trigger system when certain objects are deleted from the database.
There are also a number of ‘core-related’ projects:
- pickcells-j3d: visualisation modules based on Java3D.
- pickcells-jzy3d: visualisation modules based on Jzy3D.
- pickcells-rjava: Allows R integration into PickCells using rJava.
- pickcells-jfree: visualisation modules based on JFreeChart.
- pickcells-prefuse: visualisation modules based on Prefuse.
Non-core development relates to development done by third-parties e.g. development of plugins, other extensions or tutorials. Non-core components are not distributed as a part of PickCells.
Open, by default
To leverage the power of open source, and to build and grow a community, the default for all discussions is to use publicly-visible source code repositories, a web site and a forum. We adopt the philosopgy that everything is open unless there is a good reason for it to be private.
Developers of PickCells components should be open to inviting others to contribute. This includes welcoming users and developers, acknowledging and working on pull requests, encouraging improvements, working together, enhancing upon each others' work, sharing insights, etc.
For information on what the contributions we welcome from the community, see How to Contribute.
PickCells is written in Java.
The PickCells source code has the following features:
- PickCells is written entirely in Java.
- Apache Maven is use as PickCells' build and dependency management tool.
- The code in the pickcells-assembly repository assembles PickCells from its constituent components held within its other Git repositories. pickcells-assembly holds a Maven aggregator POM file.
- The “master” branch of each repository is considered release-ready at all times, meaning it compiles with passing tests, and is ready for downstream consumption.
- PickCells maintainers may make commits and release new versions of the components as needed, so that PickCells as a whole continues to work as intended.
The PickCells source code is held within several Git source code repositories, hosted within a GitLab service provided by Framgit.
PickCells source code is freely accessible:
- Anyone is able to clone and fork the repositories.
- Permission to merge or push to the repositories is by invitation-only.
- Anyone is able to submit pull requests to the repositories.
- PickCells source code is licenced under the GNU General Public Licence v3.
- Components contributed to PickCells must comply with certain conditions (see our Contributor Licence Agreement).
The PickCells Developer Guide describes how to build the complete code, as well as any dependencies and requirements.
Our code aims to conform to the Google Java Style Guide.
Reuse not repetition
Whenever possible, we aim to use third-party packages (licences permitting) and to improve the existing PickCells source code. We only write code from scratch if absolutely necessary.
Managing multiple developers and version control
A number of developers work on PickCells. We exploit the features of version control in Git and Framagit’s GitLab service to manage collaborative development of source code.
If you are unfamiliar with Git then we recommend Software Carpentry’s introduction to Version Control with Git.
To manage development across multiple developers, a “forking workflow” is used. Each developer creates a “fork” (or “clone”), in Framagit, of the PickCells repositories they want to work upon. They then “clone” this to their local computer. The developer works on their local version, commiting their changes, and “pushing” these, at regular intervals to their version on Framagit. If they want their changes merged into the official PickCells repositories, they issue a “pull request”. The PickCells maintainers will then review this “pull request” and, if happy, “merge” this into the official PickCells repositories, or provide feedback if there are issues with the “pull request” (e.g. it is missing documentation or has an obvious bug). This approach to development allows each developer to work independently on their local copies, and to make changes for these, without the risk of them accidently introducing bugs into the official PickCells repositories.
For a fuller description of this model, see Atlassian’s description of the Forking Workflow.
For an example of its use with PickCells, see Get PickCells repositories and Using Git and Framagit.
Build artefacts, built and used by Maven, are published on a PickCell’s specific deployment of the Apache Archiva build repository manager, archiva.pickcellslab.org.
For releases, PickCells uses semantic versioning e.g.
Ideally, all compoents should have a suite of unit, integration and regression tests.
For an introduction to testing concepts, see Testing in Introduction to Software Engineering on Wikibooks.
Tests in PickCells are implemented using the JUnit 5 unit testing framework. For an introduction to testing with JUnit 5, see the JUnit 5 Tutorial.
Mockito is used for mock object-based testing.
We also recommend the use of code coverage tools such as Jacoco and Cobertura. These tools identify the code that is executed as a side-effect of running tests and so can help to identify code that is not currently being tested.
Continuous integration is a practice whereby developers are encouraged to commit changes to their code regularly. These commits trigger an automated build of the software and a run of any tests. Continuous integration software provides the underlying infrastructure for detecting changes to source code repositories, running scripts in response to these changes and publishing the results of build-and-test runs.
For automated testing, PickCells uses GitLab Continuous Integration (GitLab CI) freely provided by Framagit to all projects hosted there. Not only can GitLab CI be used to run tests, it can also be used to run other jobs and to build artefacts e.g. documentation (it is used to build this web site, for example).
PickCells uses an issue tracker to record feature requests and bugs. These can also be raised and discussed in the PickCells Colony forum, but for milestones and tracking purposes, the issue tracker is the entry point for feature requests and bugs. The issue tracker is an overarching issue tracker associated with the PickCells project as a whole. It provides a view onto all repository-specific issue trackers.
PickCells Colony forum
The PickCells Colony forum is the place to find help and share ideas with other members of the PickCells community. There you can find out about and discuss research, how-tos, tutorials, feature requests, bugs, news and events.
The PickCells Colony forum is publicly-readable. You need to register to create new posts. Currently registration is by invitation only. However, there will be a sign-up option added soon.
The PickCells Colony forum is implemented using Discourse.