Set up Repositories

Clone the repositories and link them together for development

To develop in the API, both the Elentra ME and Elentra API repositories will need to be cloned on to your local computer, and then linked via composer so that changes made to the API will immediately appear in your Elentra ME local installation.

Clone the Elentra API Github Repository

The Elentra API is a separate Git repository from other application repositories (e.g., ME, CPD, Admissions). You will need to check this out from your Institutional Fork of elentra-1x-api. If your Institutional Fork does not have an elentra-1x-api repository, create it by forking the main ElentraProject/elentra-1x-api repository.

Be aware that if you clone the main elentra-1x-api repository, you will not be able to push any changes. Updates can only be made through pull requests from your Institutional Fork.

If you also have a Branded Edition of the API, clone that as well and set it up in the same way as the instructions below. You will need the ability to merge commits from the Institutional Fork into your Branded Edition to keep it up to date.

cd ~/Sites
git clone [email protected]/<your organisation>/elentra-1x-api elentra-1x-api
git checkout develop

If you are using Sourcetree as a GUI for git repositories, add both the ME and API repositories so that you can manage the branches in each repository.

Link the ME and API repositories

When installing composer dependencies in release 1.13 or higher, composer will install the release version of the Elentra API at the version number stored in the composer.lock file. For development of new API endpoints, this is not what we want.

To link the repositories together, create a file in the elentra-1x-me top level folder called composer-api-dev.json with content:

{
    "repositories": [
        {
            "name": "elentrapackages/elentra-1x-api",
            "type": "path",
            "url": "../elentra-1x-api",
            "options": {
                "symlink": true
            }
        }
    ],
    "require": {
        "elentrapackages/elentra-1x-api": "dev-develop"
    }
}

If you cloned the elentra-1x-api repository as a different name on your local machine, update the url path on line 6 so that it will be ../<folder_name>. All other references to elentra-1x-api should remain the same.

A note about branches. If you want to work on a feature branch in the API, check it out in the repository and also put the branch name in place of dev-develop. If the branch name checked out in the repository does not match the branch name in composer-api-dev.json, then composer will check out the requested branch from your local repository and none of the changes you make on the API repository will be visible to the application

If you are developing a new feature that will include Elentra ME and Elentra API changes, you will need a branch in each repository and will have to create separate pull requests for ME and the API. Best practice is to name the branches identically, and reference the other repository in each pull request, to ensure that both will be code reviewed and merged at the same time.

Once you have set up the file and validated that the branch names are the same, run composer in the Elentra ME repository to update the dependencies. These instructions assume you are using Docker, if not adjust the initial path to your Elentra ME install

docker exec -it elentra-developer bash

cd /var/www/vhosts/elentra-1x-me
composer install
composer update elentrapackages/elentra-1x-api

git checkout -- composer.lock

For Elentra ME 1.13+, composer install should be used to load the initial dependencies based on the composer.lock file supplied with Elentra ME.

The composer update that follows is just to pick up the local api via composer-api-dev.json

The final git checkout step is to abandon any changes to the composer.lock that were made when updating the API. You should not commit any changes to composer.lock

After running the second composer command you should see a message like the following

Loading composer repositories with package information
Updating dependencies (including require-dev)
Package operations: 0 installs, 1 update, 0 removals
  - Removing elentrapackages/elentra-1x-api (v1.2.4)
  - Installing elentrapackages/elentra-1x-api (9999999-dev): Symlinking from ../elentra-1x-api
Writing lock file
Generating autoload files

If you do not see "Symlinking from ../elentra-1x-api", check that the branch checked out in the API repository matches the branch name in composer-api-dev.json

At this point, you have linked the Elentra API repository to the Elentra ME application, and you can begin to make changes to the API.