WearableLearning Android Development Process

WearableLearning Android Development Process

Development on the WearableLearning Android app (shorthand: WLApp) is primarily driven by GitHub branch management. This wiki page provides information on the key git branches used for the WearableLearning Android app development, the development flow and processes followed for app development, and how to manage branches for local development.

WearableLearning Android App Repository

The main repository (shorthand: "repo") for WearableLearning Android app development is the wlcp-android-app repo. This is one of the repos within the wearable-learning-cloud-platform project and houses all the branches used for development by the WearableLearning Android app development team.

WearableLearning Android App Branches

There are three (3) main branches used for WearableLearning Android app development:

1. master

The master branch is the production-live branch. This means that the code on this branch is the current version of the app that is deployed live to users. As such, this branch should also be treated as the top-protected branch for development. All code pushed to this branch should have undergone review and testing through the dev-test and dev-predeploy branches (this is discussed more below).

2. dev-predeploy

The dev-predeploy branch is the production-like branch. This means that it is the branch closest to production quality as the master branch. All tested and stabilized development code (from dev-test) are pushed to this branch prior to merging to the master branch to ensure that the code and new features introduced are stable and will not break the user-facing version in master.

3. dev-test

The dev-test branch is the features testing branch. This means that all the features developed are pushed to this branch for testing by the team prior to merging the tested and stabilized features to the dev-predeploy branch for final review.

WearableLearning Android App Development Process

The Android app features development process for WearableLearning follows this workflow:

1. Create a development branch from the master or dev-predeploy branch (this will depend on the current status of the codebase and will typically be discussed with the team)
2. Write and commit code for features you are developing to the development branch
3. When the feature code is ready for review, push the development branch to the dev-test branch for code review and testing
4. When the feature code has been reviewed and stabilized within dev-test push the stable dev-test branch to dev-predeploy
5. When the dev-predeploy has completed final review and stabilization, push the dev-predeploy branch to master
6. Remove the development branch for cleanup once all pending updates and reviews have been cleared

Each of these steps are discussed in more detail below.

Step 1: Create a development branch

The first step to developing code for the WearableLearning Android app is to create a new development branch. All your code development will be committed to this development branch. Each WearableLearning Android app developer will have their own development branch.

To create a development branch, create a branch on GitHub from either the master or dev-predeploy branch (follow this GitHub Docs for creating new branches). Discuss with the team which would be the best branch to create a new development branch from. Depending on the current status of the codebase, there may be situations when creating a new development branch from dev-predeploy would be ideal instead of creating from master (e.g., when there are new stable features already in dev-predeploy).

When naming a development branch, the naming format to follow is: dev-<yourname>-<mmddyyyy_of_branch_creation>

Example: Francisco is a WearableLearning Android developer and wants to create a new development branch to write code for a new feature. He created a new development branch from the master branch on January 10, 2022. His new development branch is thus named dev-francisco-01102022.

Step 2: Write and commit code to the development branch

Once you've created your development branch (e.g., dev-francisco-01102022), you can now work on the WLApp code in your development branch. Typically, you would be developing your code in Android Studio wherein you can use the Git features of Android Studio to work with the WLApp project GitHub repository.

One key component of your development work are the code commits that you will be committing to your development branch. Your commits should always have a commit message. Your code commit messages should be descriptive of the changes you made so that the commits can be referenced later during testing and code review.

Some guidelines for effective code commit messages are as follows:

• Succinctly describes the changes/updates/additions for the code commit
• References the appropriate GitHub issue number (if any)
• Succinctly describes any existing issues for the code commit

Example: Francisco needed to add a new TextView element in the app interface that displays information to the user. After he finishes adding the code to successfully implement this, he commits his changes to his development branch (dev-francisco-01102022) with the commit message: Added the username TextView element to display the username on screen.

Additional information on code commits is available in GitHub Docs.

Another key component of your development work are the development practices to follow when developing code for the WLApp. These development practices include guidelines for writing consistent code documentation, object/variable naming practices, and others. You can read the development practices for our team from the WearableLearning Android App Development Practices wiki page.

Step 3: Push review-ready updates to the dev-test branch code review and testing

When the feature code you've developed is ready for review, push your development branch to the dev-test branch for code review and testing. Once you've successfully pushed your review-ready updates to dev-test, another member of the team will review and test your code.

Typically, testing consists of the following review items:

1. Reviewing the functionality of the feature or code change introduced
2. Reviewing the code structure and formatting according to the WearableLearning Android App Development Practices
3. Identifying potential bugs and security breaches in the code
4. Reviewing edge cases

If the code reviewer finds any items that need to be addressed such as bugs, broken functionality, potential security flaws, or code restructuring, the code reviewer will write up these concerns and review them with you to determine the best solutions to address these review items. You can then address these concerns in your development branch and repeat this step (i.e., push your updated development branch to dev-test) for another review until all review items have been addressed and the feature is stabilized and ready to be deployed to the dev-predeploy branch.

Step 4: Push reviewed and stabilized code updates into the dev-predeploy branch

When the feature code has been reviewed and stabilized within dev-test, the stable dev-test branch (or the stable development branch) is then pushed to the dev-predeploy branch. Discuss with the team which would be the best branch to merge into the dev-predeploy branch. Depending on the current status of the codebase, there may be situations when merging from the development branch would be ideal instead of merging from dev-test (e.g., when dev-test is unstable due to other merges, but the specific feature from the development branch is stablized).

Only code reviewed and stabilized within dev-test should be pushed to dev-predeploy to minimize breaking other stable code. As different WLApp developers push the different feature code they developed into dev-test, the merging of the code could introduce conflicts, bugs, and other critical concerns. The stabilization of the codebase is thus a key step within dev-test prior to pushing the feature code into dev-predeploy. Developers should collaborate to address these concerns, especially when feature code from different developers interact with each other.

Step 5: Merge reviewed and stabilized updates within the dev-predeploy branch into the master branch`

Because the dev-predeploy branch is the production-like branch, updates to this branch would be tested in an environment most similar to the production-live master branch. This includes (among others) testing with live production-like databases and API calls. This typically involves the process of dogfooding where the development team generates the APK (Android package file) from the dev-predeploy codebase, installs the APK in the test devices of the developers, and tests out the features that were introduced into the dev-predeploy branch.

The dev-predeploy branch is also the branch that would be used for user testing. This typically involves generating the APK from the dev-predeploy codebase and then installing the APK in test devices for non-developer testers to use and interact with. The developer of the features to be tested leads the development of the user testing processes and scripts, assisted by the development team (to at least ensure test coverage).

If any review items that need to be addressed such as bugs, broken functionality, potential security flaws, or code restructuring are found from the dogfooding and user testing sessions, the feature developers will write up these concerns and review them with the team to determine the best solutions to address the review items. The feature developers will then address the concerns in their development branches and repeat Step 2 onwards until all review items have been addressed and the features are stabilized and ready to be deployed from the dev-predeploy branch to the master branch for live deployment.

The dev-predeploy branch thus serves as a protective staging layer for different stable feature code that will later be pushed into the production-live master branch.

Step 6: Remove the feature development branches for cleanup after clearing all pending updates and reviews

Once the feature code has been reviewed, stabilized, tested, and merged into the master branch, the development branch can now be removed. Remove your branch from the WLApp GitHub repo (follow this GitHub Docs for deleting branches), as well as your local copy of the development branch.

You should then create a new development branch for new feature code you will develop and follow through Steps 1 to 6 of the WLApp development process.

Example: Francisco's work on adding a TextView element for displaying information to the user has been reviewed, stabilized, tested, and successfully merged into the master branch. He will now move to developing a different feature. Before doing so, he removes the development branch (dev-francisco-01102022) that he used to develop code for the TextView element from the WLApp GitHub repo, and then creates a new development branch to start developing on the next feature.