Development guide

In-development

This documentation is currently in-development. Please visit again soon, this section is actively updated.

Development environments

HeartAI developers are supported with development environments that encourage a positive and productive development experience. HeartAI instances are deployable to a developer’s local machine with automated installation steps, and these instances are secure, lightweight, and ephemeral.

Local machine deployments are orchestrated with the Docker Compose container specification tool, which provides transient instances of the message bus software Apache Kafka, the data server PostgreSQL, the identity and access management platform Keycloak, and the networking stack Traefik. The integration of these software components with local machine deployments allows developers to begin productive work readily, and reduces configuration drift between developer environments.

GitHub implementation

HeartAI source code, task and project management, and associated processes are administered through the Git version control software and the GitHub software development framework. Git and GitHub are the primary mechanisms to contribute to, manage, and deploy HeartAI. These frameworks provide structured and dynamic processes for administrators and developers to manage HeartAI, including support for:

  • Software, document, and process version control.
  • Project and product management tooling.
  • Functionalities to package and deploy software for both local machine and production environments.
  • Administrator and developer GitHub account management.
  • Utilities for software testing, analysis, and deployment.

HeartAI repository branches allow different aspects of the repository to be separated and developed independently. The following branches implement the primary functionality of HeartAI and are protected by default:

Branch name Description Restrictions Requirements
master Representative branch for HeartAI system deployment Must be merged into from a pull request. Pull request must have at least one administrator review
gh-pages Representative branch for HeartAI website deployment Must be merged into from a pull request. Pull request must have at least one administrator review

To apply source contribution to these branches, contributors must pull request their branch to merge with a corresponding origin branch, typically the protected branches noted above. Contributions to these branches are governed by an administrative review process as represented with the following figure:

review-process-for-source-contribution.svg

With administrative approval, the contributor’s branch may be merged with the nominated origin branch, and will become part of the representative branches of the HeartAI source. The representative branches, master and gh-pages, trigger downstream deployment behaviour following modification to the origin source. This includes unit and integration testing, publication of representative packages and images, and deployment to HeartAI instances of Red Hat OpenShift.

GitHub implementation

HeartAI source code, task and project management, and associated processes are administered through the Git version control software and the GitHub software development framework. Further information about the HeartAI implementation of GitHub may be found with following documentation:

HeartAI GitHub repository

The HeartAI GitHub repository is configured as a private repository. Please coordinate with HeartAI system administrators for access to the HeartAI system repository.

This repository will appear as a 404 page-not-found if the user does not have access to the HeartAI GitHub repository.

GitHub UI for repository overview

The following example shows the GitHub web interface for the repository overview. This page provides a high-level overview of the repository, and includes information such as:

  • The repository file structure, with detail about the most recent commit for the directory / file.
  • The rendered GitHub README documentation.
  • Repository metadata, including corresponding website(s) and most recent software version release.
  • Published repository packages.
  • Repository contributors.

Example: GitHub UI for repository overview

github-1-home.png

GitHub UI for commits

The following example shows the GitHub web interface for a Git commit, representing an incremental change to the repository history. For commits, GitHub provides functionalities such as:

  • Assignment of the commit with a repository Git commit ID as a unique SHA-1 hash of commit information.
  • What changes were made to the repository.
  • Who authored the changes.
  • Functionality and metrics to understand the extent of the changes.

Example: GitHub UI for repository commit

github-8-commit.png

GitHub UI for pull requests

The following examples show the GitHub web interface for a GitHub pull request, representing a request to merge one repository branch with another. For pull requests, GitHub provides functionalities such as:

  • Request process to submit an incremental update to a primary repository branch.
  • Ability to assign reviewers to review a pull request.
  • Ability to label pull requests, and associate pull requests to GitHub projects and GitHub milestones.
  • Enforcement of repository policies, such as requiring at least one administrator review and approval before accepting a pull request.
  • Integrated testing and event-driven behaviour through GitHub Actions capabilities.

Example: GitHub UI for repository closed pull requests

github-4b-pull-requests.png

Example: GitHub UI for repository pull request

github-4-pull-request.png

GitHub UI for networks

The following example shows the GitHub web interface for GitHub networks. This graph allows an interactive visualisation of repository development history. The GitHub web interface for networks provides:

  • A scrollable and interactive visualisation of repository development history.
  • Linking of network data points corresponding to a repository Git commit ID.
  • Popup information when interacting with network data points, displaying further information about the corresponding commit.

Example: GitHub UI for repository network

github-7-network.png

GitHub UI for issues

The following examples show the GitHub web interface for GitHub issues. This page provides functionalities to support project planning, task management, and team management. An issue typically represents a well-defined task or query in relation to the repository, and the issues web interface provides a centralised framework to manage these tasks. For issues, GitHub provides support for:

  • Issue creation with authorship corresponding to the GitHub user account.
  • Functionalities for labeling and tagging issues.
  • Assigning repository members to the issue.
  • Assigning issues to GitHub projects.
  • Assigning issues to GitHub milestones.

Example: GitHub UI for repository open issues

github-2-issues.png

Example: GitHub UI for repository closed issues

github-2b-issues.png

GitHub UI for milestones

The following example shows the GitHub web interface for GitHub milestones. This page provides functionalities to support project planning over larger time epochs. A milestone typically bundles repository issues related to a major platform or project development goal. For milestones, GitHub provides support for:

  • Documenting milestone purposes and goals.
  • Linkage between repository issues and a milestone.
  • Providing an overview of milestone development progress.

Example: GitHub UI for repository milestone open issues

heartai-software-github-milestones

GitHub UI for projects

The following example shows the GitHub web interface for GitHub projects, providing Kanban-like functionalities to manage projects and product. For projects, GitHub provides functionalities such as:

  • Project tasks that are linkable to corresponding repository issues, with inheritance of issue features such as web interface interactivity integrations.
  • Inheritance of GitHub issue assignees and labels.
  • Customisable board columns.

Example: GitHub UI for repository project board

github-3-projects.png

GitHub UI for releases

The following example shows the GitHub web interface for GitHub releases. This feature provides functionalities for tagging, packaging, and delivering repository software. Releases are typically created in relation to a major repository milestone. GitHub releases support:

  • Linking of the release at a point in time of the repository history corresponding to a repository Git commit ID.
  • Tagging the release. GitHub provides additional support for tags that are structured as software versions.
  • The repository source and software may be bundled and downloaded through the release page. Typical bundles are composed as zip and tar.gz files.
  • The release version is displayed on the web interface repository overview.

Example: GitHub UI for repository release

github-5-release.png

GitHub UI for GitHub Actions

The following example shows the GitHub web interface for GitHub Actions. This feature allows general event-driven behaviour to occur following interaction with GitHub as a Git commit, such as behaviour driven by a Git push to the GitHub repository, or as part of a GitHub pull request process. These capabilities are backed by Microsoft Azure cloud resources, and include broad access to compute services. This is particularly suitable for performing unit- and integration-testing of repository software and for deployment processing generally. The GitHub Actions web interface provides:

  • An overview of all GitHub Actions workflows and jobs that have been registered with the repository.
  • Linking of the GitHub Actions workflow with a repository Git commit ID.
  • The ability to view the GitHub Actions workflow in real-time, including logging functionality through backing Microsoft Azure cloud resources.

Example: GitHub UI for repository GitHub Actions workflow

github-actions.png

Useful terminal commands

Display system information

[[email protected] dir]$ neofetch
          /:-------------:\          [email protected] 
       :-------------------::        ------------------------- 
     :-----------/shhOHbmp---:\      OS: Fedora release 32 (Thir 
   /-----------omMMMNNNMMD  ---:     Host: Precision 7740 
  :-----------sMMMMNMNMP.    ---:    Kernel: 5.6.13-300.fc32.x86 
 :-----------:MMMdP-------    ---\   Uptime: 2 days, 2 hours, 39 
,------------:MMMd--------    ---:   Packages: 2823 (rpm) 
:------------:MMMd-------    .---:   Shell: bash 5.0.17 
:----    oNMMMMMMMMMNho     .----:   Resolution: 1920x1080 
:--     .+shhhMMMmhhy++   .------/   WM: i3 
:-    -------:MMMd--------------:    Theme: Adwaita [GTK2/3] 
:-   --------/MMMd-------------;     Icons: Adwaita [GTK2/3] 
:-    ------/hMMMy------------:      Terminal: urxvt 
:-- :dMNdhhdNMMNo------------;       Terminal Font: 7x14 
:---:sdNMMMMNds:------------:        CPU: Intel Xeon E-2286M (16 
:------:://:-------------::          GPU: NVIDIA Quadro RTX 3000 
:---------------------://            GPU: Intel CoffeeLake-H GT2 
                                     Memory: 22839MiB / 128577Mi 
[[email protected] dir]$ sudo inxi -Fxmz
System:    Kernel: 5.6.13-300.fc32.x86_64 x86_64 bits: 64 compiler: gcc v: 10.1.1 Desktop: i3 4.19.1-non-git 
           Distro: Fedora release 32 (Thirty Two) 
Machine:   Type: Laptop System: Dell product: Precision 7740 v: N/A serial: <filter> 
           Mobo: Dell model: 04RKY1 v: A00 serial: <filter> UEFI: Dell v: 1.7.0 date: 01/07/2020 
Battery:   ID-1: BAT0 charge: 77.7 Wh (88.2%) condition: 88.1/97.0 Wh (90.8%) volts: 11.8 min: 11.4 model: SMP DELL VRX0J8B 
           status: Discharging 
Memory:    RAM: total: 125.56 GiB used: 32.37 GiB (25.8%) 
           Array-1: capacity: 128 GiB note: est. slots: 4 EC: Single-bit ECC max-module-size: 32 GiB note: est. 
           Device-1: DIMM B size: 32 GiB speed: 2667 MT/s type: DDR4 
           Device-2: DIMM A size: 32 GiB speed: 2667 MT/s type: DDR4 
           Device-3: DIMM D size: 32 GiB speed: 2667 MT/s type: DDR4 
           Device-4: DIMM C size: 32 GiB speed: 2667 MT/s type: DDR4 
CPU:       Info: 8-Core model: Intel Xeon E-2286M bits: 64 type: MT MCP arch: Kaby Lake note: check rev: D cache: L2: 16 MiB 
           flags: avx avx2 lm nx pae sse sse2 sse3 sse4_1 sse4_2 ssse3 vmx bogomips: 76800 
           Speed: 900 MHz min/max: 800/5000 MHz Core speeds (MHz): 1: 900 2: 901 3: 900 4: 900 5: 900 6: 900 7: 900 8: 900 
           9: 900 10: 900 11: 900 12: 900 13: 900 14: 900 15: 900 16: 900 
Graphics:  Device-1: Intel CoffeeLake-H GT2 [UHD Graphics 630] vendor: Dell driver: i915 v: kernel bus-ID: 00:02.0 
           Device-2: NVIDIA TU106GLM [Quadro RTX 3000 Mobile / Max-Q] vendor: Dell driver: nvidia v: 460.67 bus-ID: 01:00.0 
           Device-3: Realtek Integrated_Webcam_HD type: USB driver: uvcvideo bus-ID: 1-11:3 
           Display: server: Fedora Project X.org 1.20.10 driver: loaded: modesetting,nvidia resolution: 1920x1080~60Hz 
           OpenGL: renderer: Quadro RTX 3000/PCIe/SSE2 v: 4.6.0 NVIDIA 460.67 direct render: Yes 
Audio:     Device-1: Intel Cannon Lake PCH cAVS vendor: Dell driver: snd_hda_intel v: kernel bus-ID: 00:1f.3 
           Device-2: NVIDIA TU106 High Definition Audio vendor: Dell driver: snd_hda_intel v: kernel bus-ID: 01:00.1 
           Sound Server-1: ALSA v: k5.6.13-300.fc32.x86_64 running: yes 
           Sound Server-2: JACK v: 1.9.14 running: no 
           Sound Server-3: PulseAudio v: 14.0-rebootstrapped running: yes 
           Sound Server-4: PipeWire v: 0.3.15 running: yes 
Network:   Device-1: Intel Ethernet I219-LM vendor: Dell driver: e1000e v: 3.2.6-k port: efa0 bus-ID: 00:1f.6 
           IF: eno1 state: down mac: <filter> 
           Device-2: Intel Wi-Fi 6 AX200 driver: iwlwifi v: kernel port: 3000 bus-ID: 6f:00.0 
           IF: wlp111s0 state: up mac: <filter> 
           IF-ID-1: br-07fe196180f8 state: down mac: <filter> 
           IF-ID-2: br-11c6da993cf9 state: up speed: 10000 Mbps duplex: unknown mac: <filter> 
           IF-ID-3: br-51fc3a16b480 state: down mac: <filter> 
           IF-ID-4: br-5a8901819c54 state: up speed: 10000 Mbps duplex: unknown mac: <filter> 
           IF-ID-5: docker0 state: down mac: <filter> 
           IF-ID-6: veth124855d state: up speed: 10000 Mbps duplex: full mac: <filter> 
           IF-ID-7: veth206318d state: up speed: 10000 Mbps duplex: full mac: <filter> 
           IF-ID-8: veth451454c state: up speed: 10000 Mbps duplex: full mac: <filter> 
           IF-ID-9: veth4da0a24 state: up speed: 10000 Mbps duplex: full mac: <filter> 
           IF-ID-10: veth762fcc9 state: up speed: 10000 Mbps duplex: full mac: <filter> 
           IF-ID-11: veth7bca5c1 state: up speed: 10000 Mbps duplex: full mac: <filter> 
           IF-ID-12: vetha44e6f0 state: up speed: 10000 Mbps duplex: full mac: <filter> 
           IF-ID-13: vethd9e22bb state: up speed: 10000 Mbps duplex: full mac: <filter> 
           IF-ID-14: vethf4b34ec state: up speed: 10000 Mbps duplex: full mac: <filter> 
           IF-ID-15: virbr0 state: down mac: <filter> 
           IF-ID-16: virbr0-nic state: down mac: <filter> 
Drives:    Local Storage: total: 1.86 TiB used: 371.32 GiB (19.5%) 
           ID-1: /dev/nvme0n1 vendor: Samsung model: PM981a NVMe 2048GB size: 1.86 TiB temp: 42.9 C 
Partition: ID-1: / size: 68.39 GiB used: 29.29 GiB (42.8%) fs: ext4 dev: /dev/dm-1 mapped: fedora_localhost--live-root 
           ID-2: /boot size: 975.9 MiB used: 302.5 MiB (31.0%) fs: ext4 dev: /dev/nvme0n1p2 
           ID-3: /boot/efi size: 598.8 MiB used: 20.4 MiB (3.4%) fs: vfat dev: /dev/nvme0n1p1 
           ID-4: /home size: 1.76 TiB used: 341.72 GiB (19.0%) fs: ext4 dev: /dev/dm-3 mapped: fedora_localhost--live-home 
Swap:      ID-1: swap-1 type: partition size: 4 GiB used: 0 KiB (0.0%) dev: /dev/dm-2 mapped: fedora_localhost--live-swap 
Sensors:   System Temperatures: cpu: 52.0 C mobo: N/A gpu: nvidia temp: 46 C 
           Fan Speeds (RPM): cpu: 1691 fan-2: 1712 
Info:      Processes: 609 Uptime: 12d 3h 56m Init: systemd runlevel: 5 Compilers: gcc: 10.3.1 Packages: 2840 Shell: Bash 
           v: 5.0.17 inxi: 3.3.03