Development
One of the overarching goals of the TNO project is to ensure the long-term maintainability and incremental enhance-ability of the solution. To support this, Docker containers will be used to allow developers to generate identical or similar local environments which will speed up development and testing.
VS Code supports the use of Development Containers which further enables the containerization of the development process. This enables developers to have identical development environments which ensures there are no missing dependencies or variations that result in external environments failing.
You should no longer need to worry about "it works on my computer, not sure why it doesn't work in yours".
Refer to the repo docs for more information - here.
Through the use of Docker most required components of the solution can be run locally to build and test each feature. There are a few cloud dependencies that are required for a few of the features. These require an Azure subscription to a few services, Storage, Cognitive Services, and Video Analyzer.
Some of these dependencies may/will change over the course of the project.
The source code is maintained as open-source on GitHub. All required dependencies are included in the source code as a mono-repo. The source code is organized to keep the many different parts and technology grouped with related components.
| Folder | Description |
|---|---|
| /.github | Configuration for GitHub, and GitHub Actions |
| /.vscode | Configuration for VS Code |
| /libs | Various dependency libraries required by the other projects |
| /libs/java/dal | Data Access Layer to connect to the database |
| /libs/java/core | Common library package for the java projects |
| /libs/npm/core | Common library package for the react web applications |
| /api | Backend RESTful APIs and associated projects projects |
| /api/editor | Backend RESTful API for the editor app |
| /api/subscriber | Backend RESTful API for the subscriber app |
| /app | Frontend web applications |
| /app/editor | Web application for editors |
| /app/subscriber | Web application for subscribers |
| /auth | Authentication services such as Keycloak |
| /db | Data storage services, such as PostgreSQL, Elasticsearch, Kafka, Azurite |
| /docs | Documentation related specifically to the code base, everything else should go into the wiki |
| /network | Network services such as Nginx |
| /openshift | Infrastructure as code, everything to setup Openshift |
| /test | Global testing tools for the solution. All other tests will be within each project |
| /tools | Tools that are used in the solution for development |
The source control workflow strategy is fairly simple, and follows common industry standards.
Developers will fork the repository into their own GitHub account.
Developers should create a separate branch by copying the dev branch for their work that is related to a Story.
All changes will be submitted to the bcgov/dev branch through a Pull Request.
A Pull Request should be made once a branch has been rebased to ensure the new commits are appended to the end (this will reduce conflicts).
Additionally, this branch should be squash merged before the PR is created.
During review of the Pull Request any new changes should not be rebased so that each commit can be compared and reviewed appropriately.
Each Pull Request will require at least one review and approval from a code owner.
When the Pull Request is ready to be merged with the bcgov/dev branch it should be squash merged so that it becomes a single commit.
When a release is ready to be handed off to UAT the dev branch should be merged with the master branch.
For those new to Git and rebasing, here is a short tutorial. We recommend you use VS Code as the Git editor as it has a nice UI to perform this task.
The following steps will rebase your branch on top of the selected branch.
- Fetch the latest commits for the branch you want to rebase onto
git fetch {remote} {source branch} - Checkout the branch you want to rebase (if you haven't already)
git checkout {destination branch} - Rebase the current branch on top of the other branch
git rebase {remote}/{source branch}
Before creating a PR you should squash all your intermediate commits into a single commit. To perform this first rebase (see above), then perform another rebase with the option to edit the commits.
- Rebase with intent to edit
git rebase -i {remote}/{source branch} - Using the VS Code editor it will display a UI form that will allow you to squash each commit down to your single commit. Note that you do not want to squash all the way down to the original source branch commit. You only want to squash your commits.
- Once you have selected which commits to squash VS Code editor will display a text file containing all the commit messages. Update the message appropriately and save the file and close it. Your local branch will now be squashed.