Contributing Code¶

Before contributing code, make sure you have followed Prepare your environment.

Python 3¶

All OSM contributions must use Python 3.10+.

python -V
# Python 3.10.x

You can manage Python versions with pyenv.

License Headers¶

New source files must include the following Apache 2.0 license header:

#######################################################################################
# Copyright ETSI Contributors and Others.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#    http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
# implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#######################################################################################

Make a change — Git Flow¶

OSM follows a Git Flow model. The master branch and version branches (e.g. v14.0, v16.0, v18.0) are protected. All contributions must go through a Merge Request.

Start from an up-to-date local copy of the target branch:

cd <osm_project_local_folder>
git checkout master
git pull
git checkout -b <branch_name>

Branch names should follow conventional commits notation, e.g. feat/add-new-vim, fix/fix-ro-crash, docs/update-readme.

Make your changes, then commit with the -s flag (required — it adds the Signed-off-by line):

git add <files>
git commit -s -m "<commit_message>"

Developer's Certificate of Origin¶

The -s flag certifies that you wrote the contribution or have the right to submit it as open source, by adding:

Signed-off-by: Random J Developer <random@developer.example.org>

This certifies compliance with the Developer's Certificate of Origin 1.1:

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.

Push your contribution to GitLab¶

Before pushing, rebase on top of the latest target branch to avoid conflicts:

git pull --rebase origin master

Push your branch:

git push --set-upstream origin <branch_name>

Then open a Merge Request on GitLab targeting master (or the appropriate version branch).

Continuous Integration¶

Every push to a branch with an open Merge Request triggers a two-stage pipeline.

Stage 1 — Per-module¶

A Jenkins job named <repo>-stage_1-mb (e.g. osmclient-stage_1-mb) runs automatically. Steps:

Licence scan
Download test image
Unit tests (linting, unit tests, changelog check)
Build and push image
Trigger Common E2E Stage 2
Promote image (on success)

Monitor the job at https://osm.etsi.org/jenkins/job/<repo>-stage_1-mb/.

Stage 2 — Common E2E¶

Triggered by Stage 1; runs in the devops repo pipeline:

Spawn remote VM
Checks before install
Install OSM
Deploy vCluster
Run E2E tests (Robot Framework)

Jenkins reports the result back to the Merge Request. If the pipeline fails, fix the issue, push a new commit or an amended one, and push again.

The recommended way to validate locally before pushing is:

./devops-stages/stage-test.sh

This is equivalent to running tox in most projects. See Testing before committing for details.

Code Review¶

Once the pipeline passes, other contributors and MDG Committers can review and comment on the MR. The MDG Leader (MDL) gives the final approval and merges the MR.

Approval from TSC¶

Explicit TSC approval is required for code changes that affect: - Repositories controlled by the TSC (e.g. IM, NBI and SOL005 repos in the IM/NBI module) - Any repository without an active MDL (e.g. because the MDL stepped down and there is no interim MDL)

To get TSC approval:

Get at least two approvals from other community members on the MR.

Send an e-mail to OSM_MDL@list.etsi.org with subject [TSC APPROVAL] {change summary} and body:

1. **Change(s)**
   Link to the MR(s) in GitLab.

2. **Purpose**
   Purpose and benefits of the change (brief, one line is ok)

3. **References**
   Including references to the related bug or feature.

4. **Other modules impacted**
   Other modules that will/might be impacted (or None).
   This is not only for impact due to code dependencies,
   but any impact in OSM functionality.
   This is important to evaluate the risks of the change(s),
   communicate them and coordinate mitigation.

NOTE:

Indicate if any other MRs need to be merged before or at the same time as this one.
Indicate if due to the complexity of the change a dedicated branch is recommended (this requires an extra process, therefore, use only when required).
Indicate if the change needs to be applied to other branches, and include the cherry-picks in the Change(s) section.
TSC will not cherry-pick to specific branches — if you need the changes in several branches, include those in the approval request.

TSC will review and approve via the GitLab MR.

Amending a contribution¶

If you need to update a change after pushing (e.g. to address review comments):

Pull the latest changes and rebase:
```
git pull --rebase origin master
```
Fix the code and stage the files:
```
git add <file>
```

Either amend the last commit or add a new one:

git commit --amend   # update the last commit; keep the commit message if it was already reviewed
# or
git commit -s -m "<new commit message>"

Push the updated branch. After a rebase or --amend, the history has been rewritten, so a regular push will be rejected — use --force-with-lease:
```
git push --force-with-lease
```

Note: --force-with-lease is safer than --force — it rejects the push if someone else has pushed to the same branch in the meantime, preventing accidental loss of their work.

Amending a change from another author¶

When amending a contribution from a different author, coordinate with them to avoid overwriting each other's work. Work on a fresh local branch:

Fetch and check out the source branch from GitLab.
Fix the code, stage the files, and amend the commit:
```
git add <file>
git commit --amend
```
Push with --force-with-lease:
```
git push --force-with-lease
```

Amending a change with dependent commits¶

If you have a stack of commits and need to amend one that is not the last:

Start an interactive rebase over the relevant commits:
```
git rebase -i HEAD~<N>
```
Mark the commit to fix as edit, leave the others as pick.

Fix the code, stage, and amend:

git add <file>
git commit --amend
git rebase --continue

Resolve any conflicts that arise in subsequent commits, then continue:
```
git add <file>   # after resolving conflicts
git rebase --continue
```
Repeat until the rebase completes. Use git rebase --abort to cancel at any point.
Push the updated branch:
```
git push --force-with-lease
```

Fixing the author name / email¶

Did you commit your changes with a wrong user name? Don't panic, see how this can be fixed.