Software Engineering Documentation
We follow a sprint of two weeks, tracked via Github Projects. This is a snapshot of our Sprint board:
During our fortnightly meeting with our mentor, code reviews were done by the mentor and we worked on implementing changes based on the review.
We adhere to the Don’t Repeat Yourself (DRY) principle, which is highly utilised in React components. This allows us to reduce the possibility of introducing errors, and have more predictable code.
We use Jest and React Testing Library to ensure code functionality in our application. For more information, click here.
New pushes and pull requests are automatically tested with GitHub Actions
When a pull request is opened to merge to either the production (main) or development (dev) branch, a deploy preview is triggerred and Netlify attempts to build a preview which can be tested by the developer, before the changes are merged into the base branch. If the build fails, new commits can be pushed and the build is triggerred again.
Upon merging, the target branch is automatically built and deployed.
Good API documentation is good SWE practice for backend. It reduces ambiguity in API usage and is important for knowledge retention for when new developers come and old developers go. This industry standard also makes it possible for computers to know how to interface with the API. We documented the backend API using the OpenAPI3 specification.
Snippet of how the YAML OpenAPI3 specs look like:
paths:
/item:
post:
description: |
Add new Lost item to be put on Lookout on the database.
parameters:
- in: header
name: Authorization
description: Firebase ID token of user
required: true
schema:
type: string
example: "Authorization: my-firebase-idToken"
requestBody:
description: Callback item payload
content:
'application/json':
schema:
$ref: "#/components/schemas/NewItem"
responses:
'200':
description: Item registered into database
'400':
description: Rejected new item into database
'401':
description: Firebase credentials not invalid
This is not so human readable, so we made use of open source openapi to markdown generator to develop Human-friendly docs.
Code testing is covered in depth under the code test section. You can read more about it here.
We leveraged Github Actions and Docker to automate testing and continuously deploy our code.
This ensures that code works properly on a proper End to End environment before it goes live to production. Overall, CI/CD is used to (regressively) test code and automate the deployment process to smoothly deploy changes.
Snippet of all CI/CD workflows in action:
Continuous integration is done whenever a pull request is made to the UAT or Production environments. If a microservice has changes, it will run all available unit tests to ensure that changes in one portion of the microservice did not break everything else.
Example of Passing Unit Test:
Example of Failing Unit Test that helped us troubleshoot issues before deploying to a live environment:
Continuous delivery is done by pushing built Docker containers into Heroku’s docker registry. Various deployment parameters are configured using github actions, and a synchronised, common runtime is instantiated by building a docker container using dockerfiles
Continuous Delivery Sample Job
Heroku logs on deployment
