Truckin-IT API

A centralised repository for the Truckin-IT application programming interface.

Please be aware that this repository is being mirrored from GitLab → GitHub

As a result, if you are viewing this repository on GitHub, we suggest that you rather navigate to the GitLab repository in order to view all issues as well as download the container image for this service from the GitLab Container Registry.

Team Enigma

This project is a product by team Enigma for the "COS301 - Software Engineering" (University of Pretoria) 2020 Capstone Project Assignment.

• For more information about the team, check out our website!
• For our other related project modules, see the following:
  • Mobile Apps (gitlab → github)
  • Cluster Deployment (gitlab → github)
  • Job Optimizer (gitlab → github)
  • Team Page (gitlab)

Setup

1. Clone this repository
2. Install Docker
   • If you are running Docker on WSL, follow this link to configure bind mounts
3. Install Docker Compose
4. Follow these instructions

Documentation

While this README serves as a guideline, our official workflow, goals and user guides are viewable with the below official documents:

• Requirement Specifications (link): Information on our functional requirements, quality standards, architectural goals and application use cases can all be found in our Software Requirement Specification (SRS)*. The contents of this document will be updated continuously during the development process as new factors and goals come to light.

• Coding Standards (link): Workflow rules and implementation standards have been defined in our Coding Standards Documents for the mobile and API teams. These documents are varied slightly to avoid unwanted or unnecessary standards for specific environments.

• Testing Policy (link): Internal rules followed by team members for writing and executing unit- and integration-tests are defined in our Testing Policy, as well as the technologies we use and the reasons we use them.

• User Manual (link): High-level information on the Truckin-IT system and user-friendly guides for each mobile app can be found in our User Manual. User guides will only represent currently implemented functionality, and as such may not fully reflect the contents of the SRS document above.

• Technical Installation Manual (link): Our Technical Installation Manual is a concise guide on configuring the necessary development and production environments for this project, as well as a technical approach to installing the mobile applications.

User stories are viewable in the Wiki. In the name of brevity, all points have been limited to a short title and user story with no implementational or motivational detail. For detailed discussion of features please use the SRS Document.

* Note: the above SRS Document is the latest version. See our version history below

• v1 (link)
• v2 (link)
• v3 (link)
• v4 (link)

Our Team

For more about us, check out our website!

	Malick Burger Systems Administration and Deployment Active on this repository (see profile)
	Daneel Nortier Machine Learning and Optimization (see profile)
	Francois Snyman Mobile & Web Development (see profile)
	Xander Terblanche UI/UX and Mobile Development (see profile)
	Preston van Tonder API Design and DevOps Active on this repository (see profile)

Milestones

• Capstone Demo 1 (12/06/2020)
  Initial Git management, CI/CD, documentation, and basic feature implementation
  Demo Video (link)

• Capstone Demo 2 (~26/06/2020)
  Updated SRS with architecture and quality requirements, user manual and continued implementation
  Demo Video (link)

• Capstone Demo 3 (~07/08/2020)
  80% feature implementation, installation manual and updated requirement documentation
  Demo Video (link)

• Capstone Demo 4 & Exam Demo (~11/09/2020)
  100% feature completion, with an additional feature
  Demo Video (link)

• Final Evaluation & Project Day (~05/10/2020)
  Requirements TBA
  (demo video not available)

Project Management

Issue Tracking

Project Management is centered in the GitLab Issue Tracker and Wiki. The Wiki tracks and categorises user stories, while issues are created to manage the implementation of those stories' implementations and dependencies.

Each issue is linked to a Milestone (see above) and assigned a label which categorises it into a Board for backlog and active task tracking. Task assignment is integrated into the issue tracker, with new issues being created and assigned at the start of each sprint (Thursday to Thursday).

Branching

The popular GitHub flow branch-control system has been adopted along with the Conventional Commits commit-naming standard. Branch protection rules and strict naming standards have been configured on the active GitLab repository as described below (if you are reading this on the mirrored GitHub repository, you will not see these rules).

GitHub flow adoption was straight-forward.

• The master branch may only be updated via reviewed merge requests from next. All automated unit- and integration tests in the pipeline are required to pass before commits can be accepted. This branch has been configured to only allow merge requests to be accepted once all three of the project owners — Albert Volschenk, Eduan Bekker and Hardu Nel — have reviewed the changes.

• The next branch may only be updated via merge requests from beta or any other development branch. Pipeline tests are run for each commit and are required to pass. Furthermore, at least one internal code review needs to occur before a merge request into this branch can be accepted.

• The beta pre-release branch may only be updated via merge requests from alpha or any other development branch. It also requires all tests to pass and at least one code review before a merge request can be accepted.

• The alpha pre-release branch may only be updated via merge requests from any other development branch. It also requires all tests to pass and at least one code review before a merge request can be accepted.

• Development branches, named <type>/#<issue no.>/<description> are the only branches in which active changes are allowed. Developers may update and break these branches as they wish during development, then initiate a merge request into the alpha, beta or next branches depending on the stage of development.

Development branches may have the following types,

Regex: (build|chore|ci|docs|feat|fix|perf|refactor|style|test)

Commit Control

Conventional Commits is used as a commit naming guideline for this repository. For more information on this, please visit the following link.
Note that GitLab automatically links commits to issues when an issue number is referenced with #<issue no.>

Each commit message follows the pattern:

Regex: (build|chore|ci|docs|feat|fix|perf|refactor|style|test)(\(#\d+\))?: (.+)((\n\n|.)+)

Simplified Pattern: <type>(<optional scope>): <description>

In order to indicate a breaking change or a closed issue, the following applies:

<type>(<optional scope>): <description>

BREAKING CHANGE: <description>

Closes #<issue no.>

Development and Operations

Continuous Integration

This project makes use of GitLab Runners in order to run automated builds and automated tests for each merge request into any of our protected branches (alpha, beta, master and next). As mentioned above, a merge request into any of these branches requires at least one internal review from another team member. An exception to this rule is the master branch. This branch is reserved for stable, quality-assured code that has been approved by all three of our project owners.

Continuous Delivery

In order to ensure continuous delivery, this project makes use of a utility called Semantic Release. After a successful merge request has been completed and depending on the changes introduced into the protected branch, a pipeline is started. This pipeline has two stages, release and deploy. For any changes starting with the pattern (feat|fix|perf|refactor|revert), the pipeline will run, otherwise, it will be skipped since these changes don't justify a new release.

Release

The release stage will parse the commit history from the most recent tag up to the commit for which the pipeline is running and will automatically bump the version based on the changes found in each commit. Version numbers follow the SemVer scheme for versioning (vX.X.X). The way in which the version is bumped is shown below:

• A fix changes will cause a patch release
• A feat changes will cause a minor release
• A BREAKING CHANGE will cause a major release
• A combination of feat and fix changes will cause a minor release
• A combination of BREAKING CHANGE, feat and fix will cause a major release

Once the release stage has determined a version number, a changelog is generated and populated with the changes introduced for that release. Finally, a new tag of the form vX.X.X is created and the source code for that release is packaged and uploaded to GitLab with its corresponding release notes.

This entire process is completely automated and requires no manual intervention! The only thing developers need to do is ensure that they adhere to the Coventional Commit standard, which is enforced by this repository.

Deploy

After the release stage has successfully run, the deploy stage will begin the process of building and tagging a Docker image. The image is named tapi:vX.X.X based on the new version and automatically pushed to the GitLab Container Registry for this project.

Note: we have decided that we will not run the deploy stage for any new changes introduced into the alpha branch because these are deemed as alpha pre-releases, however, the source code for these releases can still be downloaded from GitLab.