Developer Workflow Guide

When working as a developer at Apothesource, it’s essential to follow a structured workflow to ensure code quality, collaboration, and efficient story management. This guide outlines the key steps and best practices for developers to follow to ensure success.

This document provides a general workflow guide for developers that is based on the process used by Next Generation Shared Services (NGSS). Specific projects or teams may have additional requirements or variations in their workflow. Always refer to project-specific documentation and communicate with your team for any deviations from this guide.

Prepare for Development

When you take on a new story, or it is assigned to you, ensure that you fully understand the required changes.

  • Review the story details, acceptance criteria, and any related documentation.

    • If you have questions or need clarification, reach out to the Product Owner and/or other related stakeholders.

  • Break down the story into smaller tasks if necessary, and estimate the time/effort required.

    • In Jira, we track both time estimates and story points. These are assigned by the Product Owner and the person doing the work.

      • Story points are a relative measure of complexity and effort. These are assigned by the developer before or during sprint planning.

      • Time estimates are assigned by the Product Owner and generally reflect the maximum amount of time the PO feels the story/task should take. These are negotiable during sprint planning and development.

  • Pull the latest code for the service from the main branch to ensure you are working with the most up-to-date codebase.

    • Execute a full build to ensure everything is functioning correctly before starting your work. If you encounter any issues, address them before proceeding or seek assistance.

Development

  • Create a new feature branch from the main branch for your story. Use a naming convention that reflects the Jira story ID and, optionally, a brief description (e.g., feature/CKM-XXXX or CKM-XXXX_add_login).

  • Implement the required changes according to the story requirements.

    • Ensure you fully understand the acceptance criteria before starting development.

  • Provide test coverage for your changes.

    • Write integration/unit tests for your code changes to ensure functionality and maintainability.

      • For services, integration tests are preferred whenever possible (client-based testing with live or mocked service dependencies). At a minimum, unit tests should be used to fill gaps where integration tests can’t test certain branches or exception handling in the code. Tests should cover as many happy path/positive and error response/negative scenarios as is reasonable, including but not limited to:

        • successes/errors documented in Swagger

        • security (with and without a JWT, with and without the correct role, resource, scope, etc.)

        • health indicator checks

    • Aim for a minimum of 80% code coverage on new code. Existing code should maintain or improve its current coverage.

  • Assess whether any service dependency updates are available.

    Dependency updates should only be performed for minor or major version changes. Patch releases need to remain stable, and dependency version updates for these releases should only be made if explicitly required by the acceptance criteria.

    • Use the service-lint tool (https://coderepo.mobilehealth.va.gov/scm/dhsss/service-lint.git) to identify any available updates to dependent services and libraries.

    • If you have questions about whether a dependency should be updated, reach out to the service PO for guidance.

      If a dependency version update causes a breaking change, the version should be updated to the latest non-breaking version, a comment should be added stating that the declared version is the latest non-breaking version, and the PO should be notified so that a new story can be created to upgrade the dependency to the latest version.

  • Make sure that all service artifacts have been updated appropriately.

    • Service version number in the pom file(s) should be incremented according to semantic versioning principles based on the nature of your changes (major, minor, patch).

    • CHANGELOG.md entries should be added to document the changes made in the new version.

      • Include any framework updates (mobile-framework, ngss-maven-tiles), as well as any service dependency versions managed in the pom file(s).

    • Review and update README.md as needed to reflect any changes made to the service.

    • If applicable, update the SRVDD.md file to document any new or changed endpoints, including their HTTP methods, paths, descriptions, request/response types, security roles, and any other relevant information.

    • Artifacts that are generated or updated during the build, such as those found in the kubernetes directory, should be included with your changes.

  • Verify that all acceptance criteria have been met and that your code is functioning as expected.

    • Conduct a full local build and run all tests to ensure everything is working correctly.

    • Address any code quality issues identified during the build by static analysis tools (e.g., CheckStyle, PMD, Spotbugs) before committing your changes.

    • Do not commit code that does not build or has failing tests.

    • Review the Definition of Done to ensure all necessary steps have been completed before submitting your code for review.

Peer / Code Review

Once all development work is complete and your code is ready for review, follow these steps:

  • Push your feature branch to the service’s Coderepo (Bitbucket) repository.

  • Kick off a build for your branch in sandbox Jenkins to ensure that it builds successfully in the CI environment. If you do not have access to the Jenkins UI (mapsandbox credentials), use the Jenkins CLI tool to trigger the build.

  • Create a pull request (PR) from your feature branch to the main branch in Coderepo. This can be done through the Coderepo web interface if you have your Crowd credentials, or you can utilize the Bitbucket Pro Plugin for IntelliJ.

    • Assign the service Product Owner and the sprint’s designated peer reviewer as reviewers for your PR.

  • Create a peer review (PR) subtask in Jira linked to the original story.

    • Use the Dev: Create Review/Acceptance Sub-task Jira automation rule found under the More tab in the Jira UI, which will automatically assign the subtask to the sprint peer reviewer. Alternatively, you can use the Jira CLI tool if you do not have access to the Jira UI.

      • If creating the subtask manually, ensure it is titled "Peer / Acceptance Review: <component_name>" and is assigned to the sprint’s designated peer reviewer.

    • Set the parent story to "Waiting" status to indicate that it is pending review. Leave the subtask in the "Open" status.

  • Address any feedback provided during the code review process.

  • Once all feedback has been addressed and approvals have been received, the service PO will be responsible for merging your PR into the main branch.

The scope of a Peer Review includes verifying the deployment readiness checks, ensuring integration test coverage, and providing feedback on readability, documentation and judicious use of language. The goal is that you clearly understand the change set and how it changes the operation of the component.

Additional Notes

  • If you have Crowd access, make sure your Crowd account email address has been updated to your Apothesource email (instead of your VA email) so that you will receive timely notifications related to code reviews and PRs.

  • This list may not be fully comprehensive, and required tasks may differ slightly between components and/or change over time. That is why communication with the product owner is critical to understanding the intended outcome of a story. At any point after picking up a story, contact the product owner directly with any questions or if there is a need to clarify anything on a story.