Backlog Grooming

POs are primarily responsible for grooming all issues in their components’ backlog. Work with your principal engineer and engineering leadership to understand what stories need to be worked on for your component(s), then make sure that all stories, bugs, etc are up to date and ready for an upcoming sprint.

During PO meetings, it is critical that you take note of any recommendations and best practices that are discussed. Many of these are turned into epics, but not every task will be turned into an issue and is left to the PO to perform component maintenance at their own discretion.

It’s important to meet with your PE and other engineering leadership on a regular basis throughout the year to make sure backlog grooming includes high level VA plans, visions, etc.

Component Maintenance

Basic maintenance of the component in Bitbucket is also important. This includes tasks such as:

  • Clean up unused branches

  • Squash/Fast Forward option should always be used when merging a PR to prevent the commit history from being overbloated

  • Make sure each release has been tagged with a version

  • Release branches should not have changes that have not been merged back into main - if you are making Kustomize changes to a release branch, that is fine, but if it doesn’t make it back to main the next release would be missing these entries

  • Release branches should start with a capital “R” - Release/1.0

  • If there are multiple versions of the component, main will be the latest, main-v1 will be the branch for development of the first version and if there are more versions then you will use main-v2, etc.

  • Force pushing (pushing without merges) should never happen, this can leave branches in a weird state and changes can be lost

  • The changelog should contain entries for every version of the service, with no skipped versions

  • Reduce configuration complexity, if there are default values that apply to all environments, these defaults should be specified in code in the AppProperties. They can be overridden if needed, but by specifying defaults in code they do not need to be included in property files or in Kustomize files.

  • Ensure logging levels are correct for both SQA/PROD as well as builds, any level outside of INFO can create log files that are difficult to understand. If log levels were set in a build to hit coverage numbers, consider if the logging is actually necessary or if the coverage can be hit with a unit test instead

  • Builds should fail most of the time if there are compiler warnings - these are frequently due to use of deprecated APIs that may be removed at anytime

  • If main has unreleased changes, having "Next Release" or "Upcoming Release" for that version helps developers know which version to use

  • Follow the conventions for milestone and release candidates

  • TODO: A convention for having proof of concept/test releases that are deployed to SQA is currently being worked on

  • Ensure that the naming convention and location of different directories and configurations are consistent with other components

  • Keeping track of different information for each component can be difficult. Having an organizational system can help, see PO Bookmarks for an example of organizing components, there are also useful links to different dashboards in the bookmarks file.

Periodic In-Depth Service Review

As a product owner, I need to perform a periodic in-depth review of my service implementations to keep documentation, tooling, and source code consistent, maintainable, and aligned with current standards.

The review is organized into the focus areas below. Work through each one for every service you own.

Documentation

Review and identify inconsistencies in documentation. Cover all docs, starting with the README, Swagger/OpenAPI, and CHANGELOG:

Readability

  • Are they understandable?

Standards

  • Are we using the most up-to-date templates or standards?

  • Do the coding standards or best practices match what’s implemented?

  • Are common error responses well defined in the docs?

Build & Dependencies (pom.xml)

  • Latest Mobile Framework (MF) version?

  • Latest Maven Tiles version?

  • Preferably, dependencies should be managed by the Mobile Framework (MF).

  • JIB Maven plugins for builds present.

Implementation Consistency

Review and identify inconsistencies in implementations, APIs, etc.

Jenkinsfile

(see jenkins-shared-libs)

  • Are we using the latest templates?

Base package structure

Review for standards and consistency.

  • Client package (defined in the mobile-openapi-client module):

    gov.va.mobile.[feature].v[majorVersion]

  • Service package (defined in the mobile-service module):

    gov.va.mobile.[feature].v[majorVersion].service

Source Code

Review and identify complex code that makes the code hard to test and could be refactored.

Readability

  • Are code and function names descriptive?

Log levels

  • DEBUG for Devs

  • INFO for Testers

  • WARN for expected issues

  • ERROR for unexpected issues

Dead code

  • Are large blocks of code commented out or otherwise no longer used?

Keywords

Are the following present in the code?

  • TODO, magic, miracle, regex, fix

Tests

  • Are unit and integration tests defined?

  • Execute the test suite:

    mvn clean verify

  • Were there any interesting "warnings" or "errors" displayed in the output?

Spring probes

  • Specify Readiness dependencies (no stars or wildcards present).

Overuse of utility classes

Is the class really a utility? Or has the code been written in such a way that business logic is hidden behind a static method? Consider refactoring the "Utility Class" into a Component/Service class and using dependency injection.

Service Packaging & Class Names

Review service packaging and class names.

Package structuring

  • Can you group related classes by feature instead of by layer? Consider moving the code around. Benefits: you keep related feature code together and you can scope class access more appropriately (package access).

  • Are classes used across features, such as utility classes? Consider making a support package and putting the classes in there. (This is usually called the utils package, but consider that some classes may be shared and yet not be utilities — the name support is broader.)

Integration test location

  • Keep "remote" integration tests (ones that rely on Skaffold) in the root package, while keeping unit tests in the appropriate package.

  • Break down larger integration test classes into multiple classes where appropriate. A 3000-line integration test class can make things very difficult to read or navigate. Tests are also code and can be written with more base classes than just the standard BaseITCase copied everywhere.

  • Abstract external connection information for integration tests to make the code easier to maintain. For example, from vista-note-service (clone URI: https://coderepo.mobilehealth.va.gov/scm/vdsms/vista-note-service.git):

Class naming

Use names that match the functionality.

  • Annotated with @RestController? Prefer MyController over MyResource.

  • Annotated with @Service? Prefer MyService over MyClass.

Performance

  • Analyze for possible performance bottlenecks.

Service Lint

  • Is the service-lint plugin added to the service’s pom? If not, and if there is a reason why, start a discussion on why not.

  • Are there common issues that have come up in the past that would be prevented with a service-lint rule? Start a discussion so new rules can be created.

General Cleanup

  • Remove the legacy site directory in the service module.

  • Remove the sandbox environment from services that don’t deploy to Sandbox.

  • Remove the Kustomize folder.

  • Remove the Skaffold config (but not the build config).

  • Remove the Spring Profile properties file.

  • Revisit the .gitignore file to check it matches the maintained archetype projects: mobile-archetypes (clone URI: https://coderepo.mobilehealth.va.gov/scm/dhsss/mobile-archetypes.git)

AI Prompts

The following prompts can be used with an AI assistant pointed at a service’s source code to help generate a backlog of improvement stories. Treat the output as suggestions to review and refine, not as work to apply blindly.

  • Make suggestions for stories to improve the service’s performance.

  • Make suggestions for stories to take advantage of more Spring and Lombok features.

  • Make suggestions for stories to address technical debt and fix potential bugs.

  • Make suggestions for stories to improve test coverage, including unit and integration tests for untested or poorly tested code paths.

  • Make suggestions for stories to improve observability, including logging, metrics, tracing, and Actuator health/readiness probes.

  • Make suggestions for stories to harden security, including input validation, secrets handling, authentication/authorization, and dependency vulnerabilities.

  • Make suggestions for stories to improve API design and consistency, including the Swagger/OpenAPI contract and error responses. Be aware that breaking changes should be avoided as much as possible, and if they are necessary, they should be clearly documented in the story to create a new major version of the service.

  • Make suggestions for stories to improve readability and maintainability, including better naming, refactoring complex methods, and removing dead code.

  • Make suggestions for stories to restructure packages by feature instead of by layer and to scope class access more appropriately.

  • Make suggestions for stories to improve documentation, including the README, CHANGELOG, and inline code documentation.

  • Make suggestions for stories to improve resilience, including timeouts, retries, circuit breakers, and graceful handling of downstream failures.

  • Make suggestions for stories to reduce configuration complexity by moving defaults into AppProperties and trimming redundant property and Kustomize entries.

Reach out to your leadfor questions or ideas on improving services or for major functionality changes.