Contributing to to PAT Track

Hello! This page is for developers wanting to contribute to the code.

Pre-Contribution

Everyone must read the LICENSE before deciding to contribute to the code.

In addition, incoming contributers should contact one of us to let us know that you will be making pull requests for the project.

In addition, if you want to directly communicate with us, please notify us and we'll give you an invite to join our Slack Channel.

Instructions

After you have been given permission, you must have the following:

1. Retrieve API Keys and set them in </path/to/repo/root>/secrets.properties.... see secrets.example.properties as a template
   1. NOTE: Make sure to store these keys securely as secrets.properties may be deleted by git automatically as you change branches
   2. Port Authority TrueTime API Key
      1. requires a Port Authority TrueTime Account
      2. pat_api in secrets.properties
   3. Google Maps API Debug and Release Keys
      1. Debug Key -> google_maps_api_debug in secrets.properties
      2. Release Key -> google_maps_api_release in secrets.properties
   4. For older contributors: You must delete your old Google Maps res values... Locations:
      1. /app/src/debug/res/values/google_maps_api.xml -> Debug Key
      2. /app/src/release/res/values/google_maps_api.xml-> Release Key
2. install Android Studio
3. install Oracle Java JDK 8 -> Linux users, please use a package instead to install it
4. Install From the Android SDK using Android Studio
   1. Android SDKs from API 16 to present
   2. All Google Support libraries
   3. Latest Google Play Services
5. Open the Project as an "Existing Project"... You must follow the instructions below; otherwise, Android Studio won't open the project correctly
   1. File -> Open
   2. go to repo root
   3. open it using the repo's settings.gradle

Contribution Guideline

There are two release branches, and the rest are considered code branches, where code is updated to. All code that will be put into the default branch.

Language Guidelines

If making a new feature, it must be in Kotlin. Rules:

1. If you need to make a new class file, write in Kotlin. Otherwise, I won't accept the pull request.
2. If you want to add to existing classes, do 1 of two things:
   1. Rewrite class in kotlin (preferred, not required)
   2. write in existing java class, but create issue to write class in Kotlin
3. If making unit tests, either:
   1. Add to existing Kotlin test class
   2. If tests for specific suite is in java, either:
      1. rewrite test in Kotlin, then add test cases
      2. Create new Kotlin class, create ticket to move java test cases in Kotlin

Pushing Your Code to the App

It is in best practice that changes to the app from a fork should be in its own feature branch.

• for outside contributors, make changes on your own fork
• New code should be branched from the default branch; otherwise, we will reject everything from the pull request.
• Feature branches should stay up to date (merged) with the latest from the latest default branch pull.
• Code must be approved to be merged into the default branch
• When the feature is done, it is recommended to close the branch.

Default Branch Guidelines

• Never make pull requests from your fork's default branch.
• All features must be branched from here.
• All code from features will be...
  1. At least in the beta
  2. Must be pull requested
  3. Must be approved from the pull request
• After the above is met, the changes must be merged.

Release Branch Guidelines

Release branches are for Play Store releases.

1. master - This has the main code for release and perfectly stable versions of the app.
2. tags -> as of 5.0, we will be using tags based on the master branch for releases.