-
Notifications
You must be signed in to change notification settings - Fork 1
APIHUB Frontend Development Guide
DRAFT
Setup GitHub NPM registry.
Learn how to run APIHUB locally
Learn basic concepts and functionality of APIHUB
- create private workspace
- publish package via portal (e.g. publish APIHUB Backend API)
- publish several versions of package
- compare packages
- see BWC analysis for the packages
Build components locally (at least APIHUB UI)
Learn how to run APIHUB UI from local sources using proxy development mode.
Learn how to run Playwright tests on APIHUB Portal (<TBD>).
Learn APIHUB Frontend branching and versioning strategy.
Familiarize yourself with the APIHUB Ticketing Guide
Create a branch from develop, named according to branching conventions. If there are changes required in several dependent components- create branch in each component, according to process described in Cross-cutting feature development
Work on implementation of required functionality/bugfix.
Run unit/screenshot/integration test as described in Testing.
Create a Pull Request to develop, assign to reviewers.
Make sure, you are following git messages conventions for commits and PRs
Iterate on the code to fix issues raised during review.
We use a classic Gitflow branching model with minor variations.
Here are the differences:
- only one release branch named
release(we do not have several releases happening simultaneously) - only one hotfix branch named
hotfix(again, there are no use cases for several hotfixes being prepared simultaneously) - topic branches could be named either
feature/*orbugfix/*
Regular development and bugfix mainly happens in develop and topic branches (i.e. feature/* or bugfix/*). Make sure you understand flows around those.
We use Semantic Versioning.
Version for a package in a main branch is set to release version (e.g. 2.10.0) during release process.
Versions for packages from development branches will have both release part (e.g. 2.10.1) and pre-release suffix. Base release part in develop branch is assigned by release manager during release. Pre-release suffix is added automatically by CI process during build. You do not need to add or modify pre-release suffix in development branches manually.
When package version is published from some branch, it will have corresponding NPM dist-tag assigned automatically. These should be used to specify dependencies between packages in development branches. See details in Cross-cutting feature development
| Branch | Version Example | NPM Dist Tag |
|---|---|---|
develop |
2.10.1-dev.20250317141223 |
dev |
feature/my-feature |
2.10.1-feature-my-feature.20250317141223 |
feature-my-feature |
release |
2.10.1-next.20250317141223 |
next |
hotfix |
2.10.1-hotfix.20250317141223 |
hotfix |
Use Conventional Commits conventions for commit messages and PR titles.
There's a Docker Compose file that allows to run APIHUB locally from Docker images.
Release Docker images are published with tags corresponding to version (e.g. 2.9.0) or you could use one of Docker image tags for development branches:
| Branch Name | Docker Image Tag |
|---|---|
develop |
dev |
feature/my-feature |
feature-my-feature |
release |
next |
You can always look-up packages available for the repository in the Packages section, e.g. here are APIHUB UI Docker Images.
It is useful to be able to run UI build from sources locally and connect to some APIHUB instance (it could be cloud instance or it could be APIHUB instance spin up on localhost). You can test and debug your latest changes without rebuilding the UI Docker image.
Running UI in proxy development mode allows to do just that.
- open
vite.config.tsfile of the package you want to run (e.g. Portal) - specify the instance you want to connect to in
proxyServerconst (e.g. `http://localhost:8081/) - run
proxyNPM script from corresponding (e.g. for Portal) - open login page in the browser
http://localhost:8081/loginand login using credentials for the instance
All APIHUB Frontend repositories are using NPM as a package manager.
We use GitHub NPM Registry for publishing packages.
GitHub NPM registry requires authentication for installing packages from it. So, create a Personal Access Token (classic) with a read:packages scope on a GitHub and specify it in per-user (or global) .npmrc file.
//npm.pkg.github.com/:_authToken="<GITHUB_PAT>"
All packages should be published by CI processes which are set up for the repositories.
Do not publish NPM packages manually.
APIHUB frontend components could have a unit tests, screenshot tests and E2E tests or combination of thereof.
Make sure existing tests are green and new tests of appropriate type are added before submitting PR.
We use Jest for unit testing.
Use NPM script test to run unit tests.
Several APIHUB UI components have screenshot (also called snapshot) tests.
These are
Use NPM script screenshot-test:docker to run screenshot tests locally.
Note, that you need to setup WSL with Podman Desktop in order to be able to run screenshot tests locally.
We use Playwright for E2E testing.
E2E tests are run automatically for Pull Requests in UI repository. If E2E tests failed, you can download reports from run artefacts to understand what went wrong.
You can run E2E tests manually on any APIHUB Docker images available in GitHub Packages repository via workflow in qubership-apihub repository.
If you want to run Playwright tests locally on you PC- see instructions in ui-tests.
<TBD>, move from https://github.com/Netcracker/qubership-apihub/issues/36