Skip to content

Mobile client applications

Jump to bottom
Ettore Pasquini edited this page Apr 20, 2022 · 28 revisions

Library Simplified is a collection of middleware, server software and mobile client applications for iOS and Android.

The pages below document various best practices and workflows important for anyone contributing to the mobile client applications. What's considered a best practice will no doubt evolve over time, as should this document.

But first, a bit of wisdom.

A style guide is about consistency. Consistency with this style guide is important. Consistency within a project is more important. Consistency within one module or function is the most important.

However, know when to be inconsistent -- sometimes style guide recommendations just aren't applicable. When in doubt, use your best judgment. Look at other examples and decide what looks best. And don't hesitate to ask! — PEP 8 -- Style Guide for Python Code

Git workflow

Historically, we've used git flow as our basis for branching and tagging releases.

We recommend installing Git Flow AVH Edition to automate some of the work of branching and tagging. Using gitflow-avh is not required, but by automating the underlying repository operations, it eliminates the possibility of making mistakes, and keeps the various branches consistent.

Android app

Code style

We use a mix of Java and Kotlin when developing applications for Android. New work should generally be done in Kotlin, where appropriate. When touching existing code do your best to match the code style of the file you're working on.

New Kotlin code should adhere to the Kotlin Coding Conventions and Android style guide.

We use a tool called ktlint to enforce a consistent code style. You can run this check against your code using the command ./gradlew ktlint.

The Google Java Style Guide is a good reference when writing new Java code.

Books we recommend

Release Process

  1. Get the sign off from QA for the build from Joseph Dalton
  2. Based on commit history, construct text to be shown in the Whats new field on Google Play. This text should be approved by Risa Wolf in Jira ticket or official email for visibility.
  3. Check with Risa Wolf to see if there are any new screenshots that should be added to the Google Play listing.
  4. Increment version name and number, tag release branch in Github.
  5. With product team approval, run Fastlane commands to upload build to Google Play, enter approved Whats new text and any new approved screenshots. Use the the release version as the internal release name.
  6. Resolve any new Google Play Console errors or warnings.
  7. Notify #Simplified channel in the NYPL Digital Slack workspace that the release has gone out.
  8. Respond to any negative Google Play Store reviews where their specific issues have been addressed in the latest release.

Building for Release

Technical release process can be found in the SimplyE Android Readme

iOS app

Dependent frameworks that we maintain

iOS Code Style

We use a mix of Swift and Objective-C when developing applications for iOS. New work should be done in Swift, whenever possible and appropriate. For example, if you need to write a significant amount of Objective-C code to fix a bug or extend a feature, we strongly prefer to write the same functionality in Swift, even if it costs a bit of refactoring work.

Swift code should adhere to Google's Swift Style Guide, which is based on Apple's Swift standard library style. Regarding API design and naming in particular, please follow Swift's API Design Guidelines.

Objective-C code should follow Apple's Conventions and more in detail Google's coding style.

When touching existing code, match the code style of the file you're working on, unless for some reason its code style differs greatly from the guidelines listed above. In that case, fix the formatting of the whole file if possible (filing a subtask on Jira) before adding new code to it.

iOS Release Process

  1. Get approval for Product team to freeze the code for a new release, making sure which main features and bug fixes need to be included.
  2. Based on commit history on the develop branch, compile a detailed list of all tickets that are going to be included in the release. A quick way to do this is by using GitHub Compare feature, as if you were to create a PR from develop to the most recent release tag.
  3. Ensure that all user stories and required tickets were individually QA'ed and marked Ready for Prod. Do not continue otherwise! Ideally all tickets should be Ready for Prod before starting a RC build, but it's acceptable if a non-critical bug-fix still needs QA.
  4. Build a first Release Candidate (RC) for TestFlight distribution. (Always use TestFlight for RC builds, because those will be the same exact binaries that will be distributed in the wild. You also avoid any late code signing issues by doing this.)
  5. Send out an email cc'ing Product owner, Project manager, QA, iOS eng + mobile lead letting everyone know that the given build (version + build number) is available for Regression testing. Mention all the tickets included in the build. Remind everyone that the code is frozen and we'll only accept critical bug fixes at this point. If needed, add any relevant testing information for the given release.
  6. If critical bugs are found, fix them on the release branch (per normal git flow process).
  7. Once the RC build passes the regression and all tickets are Ready for Prod, submit build to Apple for review. Select Phased release and Hold for manual developer release.
  8. Send an email to the same group notifying that the build has been submitted. Include the public release notes that were used.
  9. Once Apple approves it, and with Product owner approval, manually release build to the App Store.
  10. Send out an email cc'ing DLT leadership (at least Sr. Director of Product and Sr. Director of Engineering), Product owner, Project manager, mobile lead, mobile engineers, QA team informing that the release is now available publicly. In the email include the version+build number, the list of all tickets addressed, public release notes.
Clone this wiki locally