# Contributing Code

Before contributing code, make sure you have followed [Prepare your environment](05-git-review.md).

## Python 3

All OSM contributions must use Python 3.10+.

```bash
python -V
# Python 3.10.x
```

You can manage Python versions with [pyenv](https://github.com/pyenv/pyenv).

## License Headers

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

```text
#######################################################################################
# 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:

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

Branch names should follow [conventional commits](https://www.conventionalcommits.org/) 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):

```bash
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:

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

This certifies compliance with the [Developer's Certificate of Origin 1.1](https://developercertificate.org/):

```text
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:

```bash
git pull --rebase origin master
```

Push your branch:

```bash
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:

1. Licence scan
2. Download test image
3. Unit tests (linting, unit tests, changelog check)
4. Build and push image
5. Trigger Common E2E Stage 2
6. 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:

1. Spawn remote VM
2. Checks before install
3. Install OSM
4. Deploy vCluster
5. 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:

```bash
./devops-stages/stage-test.sh
```

This is equivalent to running `tox` in most projects. See [Testing before committing](06-testing-before-committing.md) 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:

1. Get at least two approvals from other community members on the MR.
2. 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):

1. Pull the latest changes and rebase:
   ```bash
   git pull --rebase origin master
   ```
2. Fix the code and stage the files:
   ```bash
   git add <file>
   ```
3. Either amend the last commit or add a new one:
   ```bash
   git commit --amend   # update the last commit; keep the commit message if it was already reviewed
   # or
   git commit -s -m "<new commit message>"
   ```
4. 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`:
   ```bash
   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:

1. Fetch and check out the source branch from GitLab.
2. Fix the code, stage the files, and amend the commit:
   ```bash
   git add <file>
   git commit --amend
   ```
3. Push with `--force-with-lease`:
   ```bash
   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:

1. Start an interactive rebase over the relevant commits:
   ```bash
   git rebase -i HEAD~<N>
   ```
2. Mark the commit to fix as `edit`, leave the others as `pick`.
3. Fix the code, stage, and amend:
   ```bash
   git add <file>
   git commit --amend
   git rebase --continue
   ```
4. Resolve any conflicts that arise in subsequent commits, then continue:
   ```bash
   git add <file>   # after resolving conflicts
   git rebase --continue
   ```
   Repeat until the rebase completes. Use `git rebase --abort` to cancel at any point.
5. Push the updated branch:
   ```bash
   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](https://www.everythingcli.org/git-like-a-pro-rewrite-author-history/).