Skip to content

Development Management Guide

Jump to bottom
Aleksandr Agishev edited this page Aug 21, 2025 · 6 revisions

APIHUB Development Process in GitHub

This document outlines the development process for the APIHUB product in GitHub, covering:

  1. Work items (issues) and their lifecycle
  2. Iterative development process
  3. Release process

Table of content

Generic notes

The APIHUB application's source code is distributed across 20+ repositories: View the full list.

Each repository represents either:

  • A standalone sub-component (microservice, library)
  • A utility (autotests, workflow scripts, etc.)

The umbrella repository is: https://github.com/Netcracker/qubership-apihub.

This repository serves as the entry point for all GitHub issues and contains:

  • Application-level deployment descriptors
  • Application-level documentation

Development tracking is managed via the GitHub Project: qubership-apihub.

Project roles

  • Product owner (PO)
  • Technical manager (TM)
  • Dev Lead
  • Developer
  • QA
  • TA - Test automation

Branching model

We follow the Gitflow approach.

Reference: A Successful Git Branching Model.

Long story short

  • develop is the the top-forward integration branch. Default branch.
  • bugfix/X and feature/X branched from develop and merged after dev testing, review in the branch.
  • develop must be stable eventually
  • Stable means all AT are green
  • In the end of a sprint develop is stable, release branch created from develop
  • artifacts built from release branch are release candidates (docker tag: next). Can be provided for any customer who ready to onboard release candidates
  • If any critical issues found during acceptance - bugfix taking place in release branch
  • After acceptance, release branch merged into develop and main
  • A new tag is set on main branch. Build from this tag is our release.

Work Items (aka tickets, aka issues)

We have the following work items types:

  1. Epic
  2. User Story
  3. Bug
  4. Task

All work items are GitHub issues, categorized by type and labels.

  • Creation: Must be created in the umbrella repository (may be transferred later).
  • Tracking: Must be added to the qubership-apihub project.

Please find description and creation of each work item type below

Work items types

Epic

Epic is a huge umbrella work item describing some e2e functionality area.

Epic has child work items - User Stories

Epic planning horizon is a Quarter Release. Quarter Release - 3 months long development period

Epic definition of done (DoD): completion of all child User Stories

Epics statuses reviewed by Technical Manager on regular basis (once per month)

Mandatory fields:

  • Assignees: alagishev
  • Labels: Epic
  • Type: Feature
  • Projects: qubership-apihub
    • Priority: choose your option
    • Status: empty
    • Sprint: empty
  • Milestone: choose corresponding Quarter Release
  • Description: provide as much detailed description as you can

Examples:

User Story

User Story is an e2e functionality which can be delivered and tested

User Story is assigned to concrete developer and shown on team demo after completion

User Story definition of done: implemented, dev tested, demonstrated, merged to develop, QA tested, all bugs fixed, included in Release

Mandatory fields:

  • Assignees: empty
  • Labels: User Story
  • Type: Feature
  • Projects: qubership-apihub
    • Priority: Choose your option
    • Status: empty
    • Sprint: empty (exception: Dev Lead can create User Story directly to current Sprint)
    • Team: choose BE or FE
  • Relationships: choose corresponding Epic issue.

Example: User Story #7.

Bug

Bug is a defect in our product which needs to be fixed

Bug can be reported by anyone but typically reported by QA team

Bug definition of done: fixed, dev tested, merged to develop, QA tested, included in Release

Mandatory fields:

  • Assignees: empty
  • Labels: empty
  • Type: Bug
  • Projects: qubership-apihub
    • Priority: Choose your option
    • Status: empty
    • Sprint: empty (exception: Dev Lead can create a Bug directly to current Sprint; QA can create Bug directly to current Sprint if the Bug found during testing of a feature from current Sprint)
    • Team: choose BE or FE

Example: Bug #30.

Task

Task is a some job which is not a new feature and not a bug. Technical tasks, one-time activities, configuration, etc

Task definition of done: the task completed and accepted by Dev Lead/TM

Mandatory fields:

  • Assignees: empty/concrete person
  • Labels: choose your option
  • Type: Task
  • Projects: qubership-apihub
    • Priority: Choose your option
    • Status: empty
    • Sprint: empty (exception: Dev Lead can create Task directly to current Sprint; Developer can create Task for himself directly to current Sprint)
    • Team: choose BE or FE

Example: Task #33.

Design task, Documentation task

Used for tracking design changes (example: API specification changing), the rules is the same as for User Story (so, must be under Epic).

The difference is:

  • Labels: Design/documentation
  • Type: Feature/Task

Example: Design Task #28.

Work items workflow

User Story workflow

  1. Issue created. Hint: It has Status=Empty, so on the project board it is placed it the very left column - it makes it subject for review by Leads on regular Leads sync-up
  2. The issue is reviewed by Dev Lead, the Dev Lead set Status=Backlog/Ready for Dev, set Sprint. The issue could be Transferred to concrete GitHub repository
    1. Issues without Sprint but with not empty status - are in a Backlog
  3. When time is come, Dev Lead assign the issue to Developer
  4. Developer start working on the story and set Status=In Progress
  5. When Developer finish implementation and dev testing - he creates Pull Request (PR) to develop and set Status=In Review
    1. PR must have a link to the issue in Development field
    2. PR must have empty Projects field
    3. PR must have reviewers (team members)
    4. PR must be assigned to Dev Lead
    5. PR must have "green" CI workflow (no failed AT). If your PR breaks AT - see "Special cases" section.
  6. Dev Lead reviews PR. When review is done and all comments addressed - PR is accepted. Dev Lead updates corresponding Issue and set Status=In Test and add QA to the Issue asignees
  7. QA validates the User Story and after succesfull testing set Status=Done
    1. If any bugs are found during testing, QA creates new issues and set the User Story as a parent for them.
      1. If all found bugs has Priority <= Major, the User Story is closed by QA by set Status=Done
      2. If Critical+ issues found, QA set Status=In BugFix and notify Dev Lead
        1. QA does retest (go to step 7) of the User Story then all Critical+ issues are resolved

Bug workflow

Steps 1-6 are the same as for User Story

Step 7: QA validates the Bug fixed and after succesfull testing set Status=Done

If the fix is not accepted - QA set Status=In Progress and notify Developer

PR review process and rules

todo

Special cases

Fast track

Some issues can be marked with label fast track because of various reasons (critical issue on production, escalation from customer, urgent request from sales, etc). Such issues must be processed with the highest priority and included to the nearest release if possible.

Delivery to QA from develop/feature branch

In most cases User Stories and Bugfixes delivered to QA from develop branch. I.e. after accepting PR to develop.

It is a common process and QA knows how to take develop build.

But in case of complex risky features which involves several sub-components - it makes sense to deliver it for testing from feature branches.

Criteria for definition of such cases - common sense.

Release delay because of Critical+ issues

If it is time for release creation (Sprint timeline is over), but one or another User Story (already merged to develop) from the Sprint scope still has open Critical+ issue(s) - the release can be delayed for 1-2-3 days.

My PR brokes AT

If you PR brings changes which breaks auto tests (AT) either FE or BE, you have the following options:

  1. Fix AT by yourself (preferred option)
  2. Ask AT engineers to adopt tests to your changes

AT adaptation must be implemented in a separate branch which will be merged to develop simultaniously with your PR.

Pull Request without issue

If PR is created without any corresponding issue (small technical improvements, cosmetic changes, etc) - it must be added into project.

Development process

APIHUB product follows scrum development process.

High level flow is the following:

  1. Tactical planning horizon called Quarter Release. It is 3 months (12 weeks) period. Scope for it is subject for planning with Product Owner. This scope is defined by business needs and strategic roadmap. Work items: Epics
  2. Operational development iteration called Sprint. Sprint is 2 weeks long. Work items: User Stories and Bugs
  3. Development team creates deliverable (Release) in the end of each Sprint

Quarter Release

Before start of new Quarter Release (each 3 months) Product Owner prepares prioritized list of Epics.

These Epics are reviewed with TM and Dev Leads in order to define technical and resource ability for implementation.

Finalized list of Epics is a scope for development.

TM and Dev Leads responsibility to make each Epic decomposition to User Stories

Sprint

Sprint is 2 weeks long development iteration

Sprints are pre-created in project by TM

Sprint start and end happen automatically accroding to start/finish dates

  • Sprint scope (included issues) need to be defined and agreed before Sprint start. It is TM and Dev Leads responsibility
  • Keeping Sprint board be always up to date - TM responsibility
  • Implementation of Sprint scope in time - TM and Dev Leads responsibility
  • If Sprint is over but there are still not completed issues in it - they are manually moved to the next Sprint/no Sprint (Backlog) by TM
  • Release is created right after Sprint completion

Release

Release is a deliverable of APIHUB application.

Release has unique name. We are following semver approach.

Release contains:

  1. Artifact of each sub component except libraries (libraries can be released at any time).
    1. For now we are delivering several docker images
    2. Each sub component can have it's own version
  2. Deployment descriptors (docker-compose, helm chart)
  3. Technical documentation (installation notes)
  4. Release notes (a list of all work items included into release)
  5. (optional) Known issues list

Release represented as a tag in umbrella repository.

TM is responsible for release quality.

TM is responsible for release creation.

Notes:

  1. BE and FE team responsible for releasing owned sub components
  2. Physically release is a tag in each repository which produces docker image

Release Example: https://github.com/Netcracker/qubership-apihub/releases/tag/1.2.0

Release delivery to customer cadence

Release creation process

This section describes High Level process of release creation.

  1. First step is to create Release Candidate. Release candidate is built from release branches. FE team has special process for this (please refer to guide). BE team simply create release branch from develop.
  2. CI build process for release branches produces docker images tag next. These images are subject for comprehensive testing either on Qibership side or loyal Customers side
  3. If any Critical+ issues are found during testing - they are fixed in release branch as well as in develop
  4. After succesfull testing it's time to finish release. FE team has semi-automated process, BE team does it manually. Physically we have to merge release to main and create a tag on main branch.
  5. Tag version follows semver approach.
  6. After all sub-components tags has been created - it's time to create overall tag in umbrella repository and write Release Notes.
  7. Release notes example: https://github.com/Netcracker/qubership-apihub/releases/tag/1.3.0
  8. The last step is to merge develop -> main in auto tests repositories and create tags with the same name as the tag in the umbrella repository

TODOs:

  • Automate Release Notes creation (partially automated by python scripts by @alagishev. Scripts are shared with Team Leads)
  • Automate release creation process e2e

AUX

Userful Links

Repositories list

Team Repo name Kind Artifacts Application Comment
BE qubership-api-linter-service microservice Docker image API Linter Extension
Mgmt qubership-apihub umbrella for apihub application Helm chart, docker compose, docs mds APIHUB
BE qubership-apihub-agent microservice Docker image APIHUB Agent
BE qubership-apihub-agents-backend microservice Docker image APIHUB Agents Extension
FE qubership-apihub-api-data-model Ts library Npm APIHUB QS
FE qubership-apihub-api-diff Ts library Npm APIHUB Fork, Damir
FE qubership-apihub-api-doc-viewer Ts library Npm APIHUB QS
FE qubership-apihub-api-processor Ts library Npm APIHUB QS
FE qubership-apihub-api-unifier Ts library Npm APIHUB Fork, Damir
FE qubership-apihub-api-visitor Ts library Npm APIHUB QS
FE qubership-apihub-apispec-view Ts library Npm APIHUB Fork, Spectral
BE qubership-apihub-backend microservice Docker image APIHUB
FE qubership-apihub-build-task-consumer microservice Docker image APIHUB
DevOps qubership-apihub-ci DevOps scripts Reusable workflows Common
FE qubership-apihub-class-view Ts library Npm APIHUB QS
QA (FE) qubership-apihub-compatibility-suites QA Npm QA
FE qubership-apihub-graphapi Ts library Npm APIHUB Fork, Damir
FE qubership-apihub-http-spec Ts library Npm APIHUB Fork, Spectral
FE qubership-apihub-jest-chrome-in-docker-environment QA Npm QA
FE qubership-apihub-json-crawl Ts library Npm APIHUB Fork, Damir
FE qubership-apihub-nodejs-dev-image Dev tooling Docker image Common
FE qubership-apihub-npm-gitflow DevOps scripts Npm Common
QA (BE) qubership-apihub-postman-collections QA Newman tests QA
FE qubership-apihub-protobufjs-research Ts library Npm RnD On hold, archived
FE qubership-apihub-rest-playground Ts library Npm APIHUB Fork, Spectral
BE qubership-apihub-sniffer-agent microservice Docker image APIHUB Sniffer
BE qubership-apihub-test-service QA Docker image QA
BE qubership-apihub-traffic-analyzer microservice Docker image APIHUB Sniffer
FE qubership-apihub-ui microservice Docker image APIHUB
QA (FE) qubership-apihub-ui-tests QA Playwright tests QA
FE qubership-apihub-vscode VS Code plugin Plugin pack APIHUB ecosystem
Processes description
Technical articles
Design Items

General Functionality

Package Version

Dashboard version editing/creation

Package/Dashboard Settings

Package Settings

Operation Content View

Comparison

Portal Global Settings

Portal User Settings

Custom OpenAPI Extensions

Global Search

Agent

VS Code Extension

E2E Regression

UI Regression

Clone this wiki locally