184 lines
7.2 KiB
Markdown
Executable File
184 lines
7.2 KiB
Markdown
Executable File
### 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 the 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
|
|
3. Execute docker commands to build system.
|
|
4. Restore the 3 database backups
|
|
5. Add the host file entries
|
|
6. execute ``` docker-compose up -d or sail up -d``` to start the docker system.
|
|
7. 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, the .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.
|
|
|
|
2. 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
|
|
|
|
3. You are responsible for your own code, if you generate merge conflicts YOU sort them out to ensure no DATA LOSS
|
|
4. 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 !!
|
|
|
|
|
|
|
|
|
|
|