Contributing to the code (third party development)

Introduction & challenges

Archetype code base is open source and fully available on github. It is written in Python 2 (Django 1.8), Javascript (jQuery), HTML, CSS and XSLT.

Legacy system

The framework is now considered legacy as many parts of the code are 8 year old, some functions are obsolete and the architecture relies on deprecated libraries. The system should receive a minor upgrade in the first half of 2020 to make it compatible with Django 2.2 and Python 3 but at the moment, without further funding, we cannot guarantee that the framework will be functional beyond 2023. King's College London doesn't pro-actively support, upgrade or enhance Archetype, we carry out critical maintenance and updates for the ongoing research project based on the framework.

Lack of documentation and automated testing

The two biggest challenges for new developers are the lack of documentation (we only have inline documentation but no introduction to the code) and the lack of testing suite (mainly due to the fact that 75% of Archetype is front-end based and bypasses web APIs).

Some of the code is very dense and convoluted, especially the Annotation, Collection and Editing components. We generally discourage people to make modifications there if they are not familiar with the system. The server-side code should be more accessible and easy to understand to Django developers.

One important thing to keep in mind is that the same Archetype code base has been used to run ~15 web sites. All of them are very different (some work with coins, other with decoration, iconography, large text with dense markup, ...). The code is very versatile and it is hard to think about all possible use cases at the same time. Testing your changes on one system is therefore unlikely to guarantee regressions in others.

At the very least you should make and test your changes in a system which has many images, annotations, texts, collection items, ... and fully re-test all the main functions of the system both within and outside Docker.

As mentioned above Archetype no longer have dedicated full time developers for maintenance / improvement. Developers with the required expertise now work on other research projects. The discussion, review and integration of your changes to the framework are therefore dependent on their limited availability. Please be mindful of that before going ahead and investing your time into core modification of the framework (see option a) below). You might prefer to consider option c) or b) below.

How can I adapt Archetype?

There are three ways to adapt Archetype:

• a) modify or extend the shared code base
• b) create project-specific or reusable code customisations
• c) build on top of Archetype Web APIs

a) Modifying the shared code base

If you need to fix a bug or add a new feature that is generic enough to benefit all instances of the framework, the github code base is the best place. Please follow this procedure if you want your change to be incorporated into the main repository:

1. open a ticket on github with a description of a single issue and the suggested solutions
2. take part in the discussion to agree on a particular solution and make sure it is described in details
3. if the suggested change is accepted, fork the repository, pull the latest version of the develop branch and make your code change there into a single feature branch (named after the github ticket number)
4. test your changes thoroughly to insure the changes do not create any regressions
5. create a pull request for the KDL team to review

b) Instance customisations

If you want to introduce a new feature which is specific to a project, the easiest approach is to develop it as an add-on within the customisation area of the framework. The customisation system allows you to change the behaviour of the search page, the Text Editor, the appearance, layout and content of some front-end pages. You can also add new database tables and admin forms.

Those changes are essentially written in new code, separate from the main repository. You'll be responsible to keep them up to date with latest version of Archetype and manually deploy them into your own instances of the framework.

c) Web APIs

Archetype offers a data API to read and update records in the database. It also has an API to access the texts.

You can use the API in two ways:

• create XSLT transforms to produce pages based on the content of the database (e.g. show annotation, hands, ...)
• develop external apps that call the Web API: e.g. new input forms, visualisations, data summaries, data extractions

The XSLT transform mechanism is already part of the existing framework and your actual transforms saved in database of your instance.

External apps are independent from the main repository.

How to use the branches in Github?

Git branches:

• develop branch is the current development version. Before being merged into master the branch has to be fully tested.
• master branch is for latest stable version of the framework. Small Hotfixes can be done directly in master but they have to carefully tested and the changes must be merged into develop.

Testing is currently entirely manual and done by the core Archetype team. All new features should be added to develop branch first, never to master directly. Please always keep develop functional, don't commit something that will break the framework; minor bugs are acceptable.

Since version 2.2.1 our aim is to follow gitflow, with develop, master and releases branches.

https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow

http://www.geekgumbo.com/wp-content/uploads/2011/08/nvie-git-workflow-commands.png