System Developer Notes

This documents how one should develop using the sentinel laravel project.

Git Structure

The project is tracked using git and has several key branches, we also operate a pull request system and these branches are protected, a pull request must be raised and approved before code can be merged into the relevant develop, stage, release or main branches. ** Code will not be merged in any other way ***

main

This is the production branch and is protected from direct commits into this branch except for senior developers, in normal circumstances this branch in never tampered with hot fixes and releases being the only exception. This key branch provides the code for http://mediuk:10008 it resides upon the mediuk server in a directory /www/laravel/htdocs.

stage

This branch is mainly deployed to support user quality testing and reside on http://mediqat:10008 NB from time to time other branches may be in effect on this server when progressing towards a software release this structure is normally release/RC-(date)-Vx when (Vx) is is the format of "V" followed by a number to indicate the release candidate version. its location on the mediqat server is /www/laravel/htdocs

develop

This is the key branch that runs on http://medidev:10008 this is not really to be considered a true development branch as historically this has been use as a pseudo user QAT branch.

Important Note

The medidev server also runs th e Oracle Connectors required to run the Spares (MAXIMO) system and you should ensure that this server is working at all times, this may well be backed up by an additional server running on medidev when time permits.

There are also other key branches

release

primarily for release candidates as above.

bugfix

Branches under this in the format bugfix/details are used to provide fixes for running systems

feature

This is for new systems, as we use Laravel modules and all code is self contained with within the module follows the format feature/module_name

hotfix

This branch structure is for hotfixes into the production system ofr emergency updates in the format hotfix/fix_details

support

This is for minor fixes into all of the Sentinel system.

Commit messages

An important aspect of commit messages is the ability to search these in good commit messages are vital to prevent developer confusion and code loss when merging. these should follow the format [Module_Name] or [System_Name] and then a concise narrative of what the commit contains. short and non descriptive commit messages will mean that a pull request is rejected with a request to refine the commit message.

Starting a new project

In amy cases developers have been using the medidev server for pure development and this can cause issues in, medidev should NOT be used for pure development in all cases a separate server should be requested, in the current DB2 database setup there is only one database instance and this can and will cause you issues.

It's recommended that you develop locally using docker a high performance docker_compose file and a docker directory has been provided, you should install docker, once installed you should reach to to MPBA staff to get a backup of the core databases AAMEDIUK, MPDAT10 and ARCHIVE when using docker you will be using MYSQL as a database server the database backups will be provided and these cna be restored to you local database's

Always we aware of the fact that the target DB on all Abbot Servers is IBM DB2 and guard code should be produced to ensure that migrations and seeders which are fully support on DB2 , ensure that they only run once as needed and log all of their actions. This aids other developers.

All permissions and roles should be defined in a seeder so that simple commands can be used to populate the various systems as needed .

We do use actually Laravel Sail in some instances so you can use

docker-compose build --no-cahe 
or
sail build --no-cache

To download the images and build containers, then once build you can use

sail up -d
or
docker-compose up -d

This will start the database server, and php webserver using nginx, its recommended that you add entries to your hosts file for the following

127.0.0.1 mysql
127.0.0.1 mailpit
127.0.0.1 redis
127.0.0.1 host.docker.internal

127.0.0.1 medidev.vm
127.0.0.1 mediuk.vm
127.0.0.1 mediqat.vm
127.0.0.1 sonarcube
127.0.0.1 nginx

Your browser will then respond on http://medidev.v, for example. You can use local self certified SSL if you desire and you should reach out to MPBA staff for details.

Important Apple Silicon Development

With later releases of Apple OSX the file system is case sensitive, where the IBM AS400 Apache server / filesystem is not. Therefore its not possible to hold the mysql database files on a case sensitive drive this will cause the server to crash when loading data etc. We use the Linux sub system provided by the container to overcome this and performance issues with docker and shared volumes.

Beware if you clean your docker system and purge all the volumes you must rebuilt and re-import the database backups.

One could use a separate case insensitive volume but this will impact docker performance.

When starting a new project the root branch is develop and you should create your new branch as feature/module name

Development Steps

  1. Perform a git pull using teh develop branch goit pull origin develop
  2. Create your new feature branch and switch git branch feature/module_name && git checkout feature/module_name
  3. Create a suitable env file .env
  4. Execute docker commands to build system.
  5. Restore the 3 database backups
  6. Add the host file entries
  7. execute docker-compose up -d or sail up -d to start the docker system.
  8. create your new module with ``` php artisan module:make (name)

You should now have a running system.

Module Naming

Think about how you name you module and make it as short as possible with NO spaces php artisan module:make Spares for example. Changing a module name later is hard and will require a senior developer.

In previous releases we were using an environment switcher so that .env.dev ate were added to the SCM ( git) this is not now the case and it relies upon the .env file, teh .env file SHOULD NOT BE COMMITTED under any circumstances.

The existing modules provide a great starting point and you should review the code under the Modules directory

FINAL IMPORTANT NOTES

  1. commit and push pull at high frequency

When a piece has been worked upon commit your changes with a suitable commit message and pull al push any changes, its a good idea to pull and push frequently.

  1. Commit all work at the end of day This is important. ALL WORK should be committed and PUSHED to GIT at the end of the day NO EXCEPTIONS

  2. You are responsible for your own code, if you generate merge conflicts YOU sort them out to ensure no DATA LOSS

  3. if yo do not commit frequently do not expect your code to be updated to GIT you MUST COMMIT your work

Do not rely on backups, its your code, own it and ensure its added to the source control system and also ensure you do not over write and core code in the process, if in doubt ASK !!