Collaborative Development

Contents

Introduction

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:

There are also a number of ‘core-related’ projects:

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.

Source code

PickCells is written in Java.

The PickCells source code has the following features:

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:

The PickCells Developer Guide describes how to build the complete code, as well as any dependencies and requirements.

Coding standards

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

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.

Release versioning

For releases, PickCells uses semantic versioning e.g. PickCells-0-7-3-alpha.zip.

Testing

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

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).

Issue tracker

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.