Contributing Code - magma/magma GitHub Wiki

This page describes the steps and setup needed to be able to contribute code changes to any of the project repositories.

Development Environment

Essentially there are two different Integrated Development Environments (IDEs) used within the project, IntelliJ and Visual Studio Code (VSCode).

Where to start?

You can use the good first issue tag on our GitHub repository to search for good starter tasks. As you are working on your starter task, refer to the subsections of this page for guidance on how to author a pull request (PR) and Code Contributing Conventions for code conventions in Magma. Once your PR is approved and merged, you're now an official contributor to the Magma project!

Also join our community Slack channel via the link from the Community page and say hello in the #general channel. We can point you toward a good starter task or guide you choosing appropriate tasks given your skill set and the Magma roadmap.

Next to the GitHub Wiki also consider the documentation in DocuSaurus as a valuable information source.

Coding Guidelines

As coding guidelines are quite extensive, you can find them in the separate page about Code Contributing Conventions.

Developing Workflow

Magma follows the standard "fork and pull-request" development workflow. For more information on this workflow, consider the following resources:

Once your PR has been approved and passed all CI checks, use the ready2merge label to indicate the maintainers can merge it.

Commit and pull-request guidelines

Required

Signed-off commits

You must sign-off all commits on the originating branch for a PR, which certifies that you wrote it or otherwise have the right to pass it on as an open-source contribution. The rules are pretty simple: if you can certify the below (from developercertificate.org):

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or

(b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or

(c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.

(d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.

Then you just add a line to every git commit message:

Signed-off-by: Joe Smith [email protected]

You need to use your real name to contribute (sorry, no pseudonyms or anonymous contributions). If you set your user.name and user.email git configs, you can sign your commit automatically with git commit -s.

Pull-request and commit message title are following conventional commits format

Labeled backward-breaking pull requests

Backward-breaking PRs must use the breaking change label. All breaking changes and their mitigation steps will be aggregated in the subsequent release notes. A breaking change fits one or more of the following criteria:

  1. The change will require manual intervention on the next upgrade (e.g. a data migration script).
  2. The change will break the southbound interfaces between AGW and Orchestrator in a way that will require both components to upgrade in a coordinated way.

Further Guidelines

Convincing test plan

For non-trivial PRs, codeowners will require you to include a test plan detailing any manual verification steps you took.

Imperative mood for pull-request title and description

A simple way to check this is to mentally prepend the phrase "This commit will ..." to the title and each bullet point of your description.

Testing code locally

The Magma repository provides different integration tests, S1AP Integration Test and S1AP Federated Integration Test.

During their execution, the integration tests change the configuration in the Magma VM. If the tests are not completed successfully, the changes are not removed and the VM may show a different behaviour. In this case, the VM must be reset to restore the original state.

In order to avoid this situation, you should always run the sudo tests first. Subsequently, the integration tests can be executed. If you swap the execution order, the sudo tests would fail.

Workaround: A VirtualBox snapshot of the Magma VM can be created after provisioning the VM but before running the integration tests.

Code Review Process

If you create a pull request against the Magma master branch, a codeowner will automatically be assigned to the PR for review. Make sure you know and understand the "Re-Request Review" functionality of GitHub and to not ping people on Slack. (A personal message on Slack should only be the last resort, if there is no response on a pull request after a week's time. In such cases, the GitHub-to-Slack mapping may be useful.) In addition, most pull requests will be tested by an extensive set of CI checks (see below). Once all required CI checks have passed and you have at least one approval from the respective codeowners, you can set the ready2merge label and a maintainer will get your changes landed.

Continuous Integration (CI) / Continuous Deployment (CD)

When a PR is submitted to the Magma repository, a suite of CI tests and analysis is executed. Checks marked as required (blocking checks) must pass for a PR to be merged.

Most of the checks are implemented as GitHub Actions, which need to run successfully. Before adding or updating an action, familiarize yourself with the Secure Use of Github Actions.

See this page for a technical overview of magma CI workflows.

Overview of checks applied to a pull request

You can find a summary of the check results on the overview page of a pull request. All workflow runs can be found via the GitHub actions page, which can be filtered by branch name and user. Alternatively, you can use the GitHub CLI to get the same information (and more) from the command line. Some useful commands for the GitHub CLI are listed below.

List the last couple of pull requests:

gh pr list

List the executed checks on a pull request with results:

gh pr checks some_remote:branch_name

Same as above filtered by required checks:

gh pr checks --required some_remote:branch_name

List all workflows (including disabled workflows):

gh workflow list -a

See the yaml definition of a workflow:

gh workflow view "DP Lint & Test" --yaml

If you get stuck by a failing check it usually suffices to write a respective comment on the pull request. If necessary the approver group that owns the check can be mentioned. You can find the needed group in the workflow definition. This can be found, e.g., via:

gh workflow view "DP Lint & Test" --yaml | grep "^# owner:"

Get the purpose of a check:

gh workflow view "DP Lint & Test" --yaml | grep "^# purpose:"

Get additional information for the check:

gh workflow view "DP Lint & Test" --yaml | grep "^# remediation:"

There are a couple of checks that are not modeled by github workflows.

Check Name Purpose Owner Remediation Steps
mergefreeze Stop merges during a code freeze (required) @magma/approvers-infra N/A
Magma-OAI-Jenkins OAI's MME integration test run on OAI Jenkins (required) @rdefosse N/A
Codecov.io Evaluate code coverage data (not required) @magma/approvers-infra N/A

How to add a new CI check to Magma

Please add meta data to the workflow definition that can be parsed by the commands above, e.g.,

# owner: @magma/approvers-gw
# purpose: Linting various components in AGW
# remediation: https://magma.github.io/magma/docs/next/lte/dev_unit_testing#format-agw

To add a blocking check,

  1. File a proposal to outline the motivation and any relevant timelines and assign to a relevant codeowner or TSC (example proposal)
  2. Once the proposal is accepted, announce the plan in #dev and coordinate with one of the repo admins to make the switch.

Naming conventions

The convention for naming new workflows is as follows:

{component} {verbs} {additions}

with

  • {component} in AGW, CWAG, Docs, DP, FeG, Magma, NMS, Orc8r, PR
  • {verbs} in Analyse, Backport, Build, Check, Deploy, Format, Generate, Lint, Promote, Publish, Test
  • {addition} being a short descriptive addition

Rules and notes:

  • All words in the name should be capitalized.
  • {component}:
    • Exactly one component should be chosen for every workflow.
    • "Magma" is intended for workflows relating to multiple Magma components.
    • "PR" is intended for workflows that interact with pull requests.
  • {verbs}:
    • In the case that multiple verbs are applicable, the last separator should be an ampersand with one space each side, while any other separator should be a comma followed by one space, e.g. Build & Test, Lint, Build & Test

Backporting changes to release branches

The process for backporting code changes to release branches, such as v1.8, is as follows:

  • Create and merge a pull request to the master branch.
  • On the merged pull request, add the label apply-<branch_name>, e.g. apply-v1.8. This change triggers the backporting workflow, see backport-pull-request.yml.
  • A new (back-port) pull request is automatically created by the MagmaCIBot.
  • This new pull request should be reviewed and posted in the #magma-releases Slack channel, where the managers of the release need to approve the change for backporting.
  • Once the pull request is approved it can be merged.

For example, the pull request https://github.com/magma/magma/pull/14763 was merged to the master branch. The label apply-v1.8 was added and the backport pull request https://github.com/magma/magma/pull/14945 was created and merged.

:warning: The above steps apply to code changes that are also merged to the master branch. If a change is only needed for a release branch, but should not be applied to the master branch, then a regular pull request on the release branch should be opened and announced in the #magma-releases Slack channel.

:warning: Changes to the documentation in the docusaurus are never backported, because the docusaurus is deployed from the versioned docs on the master branch, see docs/docusaurus/versioned_docs and the contributing documentation page. Documentation in README.md files outside of the docusaurus can be backported if necessary.

Action on blocked CI

While the master branch is protected by (required) CI checks, merging PRs still bears the possibility of breaking the CI workflow, e.g. by not rebasing, failing post-merge workflows or changes in workflows with pull_request_target triggers. Reverting a merged PR accompanied by a discussion on Magma's Slack may prove a viable option to unblock the CI workflow if the amount of time for a proper fix is significant.