Development guide

In-development

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

This guide provides an overview for developers when contributing to HeartAI. Developers have access to an integrated development environment to support their endeavours. This environment should allow developers to gain access to preconfigured infrastructural services, in addition to service, application, and analytical software. Developers should feel comfortable that their development experience is productive and that their communication with HeartAI administrators and colleagues is supportive.

HeartAI welcomes contributions from HeartAI team members as well as collegial and voluntary efforts. External developers should coordinate with HeartAI administrators should they wish to learn more about development and gaining access to the HeartAI repository.

About HeartAI

Developers are encouraged to learn about the purpose and goals of HeartAI, the opportunities of deploying HeartAI to support digital health, and the general capabilities of HeartAI:

Deploying HeartAI to a local development environment

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.

The HeartAI development environment is designed to be modular, with developers deploying corresponding components to support their development objectives and use-cases. This typically includes integrated development framework components, such as Git, Git LFS, Docker Engine, and Docker Compose, such that the developer may interact with the HeartAI source respository. These integrated deployment components also support pre-declared software module packaging and deployment and a variety of backing services such as network, database, and identity services. The developer may require only a limited use of integrated HeartAI components if they are simply using these core functionalities. The developer may also wish to develop corresponding specific software components, such as service-level, application, or analytics software, which are deployable with relation to their corresponding component. For example, service-level deployments typically require a Java Development Kit (JDK) such as OpenJKD, to support development with the and Scala hybrid object-functional programming language, with also build management through the sbt build tool.

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 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 and remote environments.
  • Administrator and developer GitHub account management.
  • Utilities for software testing, analysis, and deployment.
  • Knowledge base management including error reporting and reference documentation.

HeartAI repository branches allow different aspects of the repository to be separated and developed independently. Developers will typically work within their own branches, and when a suitable level of development is achieved these branches will be requested to merge with the primary representative branches of the HeartAI source. 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 and documentation 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 one of the corresponding origin 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 and other remote 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. 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

Linux references

systemd

NetworkManager

neofetch

inxi

jq

virt-manager