# Understanding the Workflow with OSM tools

## Login to OSM portal

To be able to use all the tools required in the development cycle, you need to be authenticated in ETSI portal.

1. Go to OSM portal: <https://osm.etsi.org/>
2. Log in using your username and password

**Note:**

- If you are contributing on behalf of your company, you should login with your ETSI Online Account (EOL).
  - If your company is not yet an **[OSM Member or Participant](https://portal.etsi.org/TBSiteMap/OSM/ListofOSMMembers.aspx)**, you can check here **[how to join OSM as an organization](https://osm.etsi.org/about/how-to-join)**
- If your company has **already joined OSM but you do not have an EOL account** yet, you can **[request an EOL account](https://portal.etsi.org/createaccount)**
- If you are an **individual contributor**, you can **[create your OSM account online](https://osm.etsi.org/register)**.

If you need any help, contact us at <OSMsupport@etsi.org>

## Reporting a bug on Bugzilla

1. Go to the OSM Portal and click on **Bugzilla** menu on the portal menu bar. Or simply go to [OSM Bugzilla](https://osm.etsi.org/bugzilla)
2. Click on "new" on Bugzilla menu bar.
3. Choose the product, e.g. "OSM".
4. Complete the bug form. If you know, choose the component, e.g. UI, SO, RO, Documentation/Wiki, etc.
5. Enter the bug summary, description, attachment, etc.
6. Click on the "Submit Bug" button to confirm.
7. A bug id is generated (e.g. Bug 6 -Small Error)

## Contributing code

### Prepare your environment

#### SSH key

Create an SSH key pair if you don’t have one:

```bash
ssh-keygen
```

Accept the default path (`~/.ssh/id_rsa`) and enter a passphrase if desired.

Add your public key to GitLab:

1. Go to [https://osm.etsi.org/gitlab/](https://osm.etsi.org/gitlab/) and sign in with your EOL account.
2. Under your profile, go to **Edit Profile → SSH Keys**.
3. Open `~/.ssh/id_rsa.pub`, copy its contents and paste them into the **Key** field.
4. Set a title and an expiry date (maximum one year).
5. Click **Add key**.

**Note:** `id_rsa.pub` is your public key and can be shared; `id_rsa` is your private key and must be kept secret.

#### SSH client configuration

Add the following to your `~/.ssh/config`:

```text
Host osm.etsi.org
  Hostname osm.etsi.org
  User git
  IdentityFile ~/.ssh/id_rsa
  PubkeyAcceptedAlgorithms +ssh-rsa
  HostkeyAlgorithms +ssh-rsa
```

Test your SSH connection:

```bash
ssh -p 29419 osm.etsi.org
```

#### Git configuration

Configure your git username and email to match your GitLab profile:

```bash
git config --global user.name <your_etsi_user>
git config --global user.email <email>
```

If you use the same machine for other projects, you can restrict these settings to a specific repository:

```bash
cd <osm_project_local_folder>
git config --local user.name <your_etsi_user>
git config --local user.email <email>
```

Verify your configuration:

```bash
git config -l
```

### Clone a project

Find all OSM projects at [https://osm.etsi.org/gitlab/dashboard/projects/member](https://osm.etsi.org/gitlab/dashboard/projects/member). Clone using SSH:

```bash
git clone ssh://git@osm.etsi.org:29419/osm/<project>.git
```

To clone all the main OSM projects at once:

```bash
mkdir -p ~/OSM/
cd ~/OSM
BRANCH=master
for PROJECT in common devops IM LCM MON N2VC NBI NG-SA NG-UI osmclient PLA POL RO tests
do
  git clone ssh://git@osm.etsi.org:29419/osm/${PROJECT}.git
  git -C ${PROJECT} checkout ${BRANCH}
done
```

### Configure your Git environment

1. Configure your git username globally:
   ```bash
   git config --global user.name <username>
   ```
2. Configure your git email address:
   ```bash
   git config --global user.email <email>
   ```
3. Check your git configuration:
   ```bash
   git config --list
   ```

**Note:** Your email address will be visible on commits. If you’d like to keep it private, you can mask it: if your email is `name@company.com`, set `user.email` to `hidden@company.com`. This lets other users identify you by username while Git stats still track your company’s contributions by domain.

In case you are using git in the same computer for other open source projects, you can restrict your git variables to the local folder:

```bash
git config --local user.name <username>
git config --local user.email <email>
```

### 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 Jenkins CI job named `<repo>-stage_1-mb` (e.g. `osmclient-stage_1-mb`). The pipeline runs:

1. Licence scan
2. Unit tests (linting + tests + changelog check)
3. Build and push image
4. Common E2E tests (spawns a remote VM, installs OSM, runs robot tests)
5. Promote image (on success)

You can monitor the job at `https://osm.etsi.org/jenkins/job/<repo>-stage_1-mb/`.

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/).

## Proposing a new Feature

Project Features go trough a discussion and approval process. To propose a new Feature, OSM uses [Gitlab](https://osm.etsi.org/gitlab).

1. Go to [https://osm.etsi.org/gitlab/osm/features/-/issues/new](https://osm.etsi.org/gitlab/osm/features/-/issues/new). You need to be authenticated.

2. Create a **new Issue for your feature**

   - Title: A high level description of your feature (see some other examples in Gitlab)
   - Type: Issue
   - Description: The feature description, following the auto-generated template.
     - A feature request is about functionality, not about implementation (that is the design)
     - Describe WHAT you are proposing, and WHY it is important.
     - DO NOT describe HOW to do it.

3. Pick **Labels**
   If you foresee the OSM modules that might be affected by the feature, pick labels for them. Otherwise, leave it empty.

4. **PLEASE:** Do not set the following:

   - EPIC
   - Asignee
   - Milestone
   - Weight
   - Due Date

5. **Submit Issue**

6. Interact with the TSC and the Community through the issue.
   TSC will review your Feature. If it makes sense and its purpose is clear, it will be approved. Otherwise, TSC will provide questions for clarification.

## Funnel of a feature

Once approved, the feature could transition through the following steps

- **Aproved**: Approved by TSC to be included in OSM
- **Design**: In the design phase, where HOW do to it will be discussed
- **Development**: It is being implemented
- **Testing**: Developer is testing it
- **Review**: Community s reviewing it
- **Completed**: It is completed, and merged
- **Abandoned**: It was abandoned

An approved features is not a guarantee for implementation. Implementing a feature requires resources, and resources come from the companies integrating the Community, which might have prioritized the development of other features instead base on their own interests and the interests expressed by the EUAG and the TSC.

Once a Feature is accepted for inclusion in a specific Release, the ticket will be included in the respective [EPIC](https://osm.etsi.org/gitlab/groups/osm/-/epics)

- **Release 1**
- ...
- **Release 10**
- **Release 11**
- ...

For instance, to see Features included in Release11, check EPIC [Release11](https://osm.etsi.org/gitlab/groups/osm/-/epics/11)

## Designing a feature

Once a feature has been approved, the design phase starts. A design pad can be created in [ETSI etherpad](https://osm.etsi.org/pad). The name of the pad must be "featureXXXX" where XXXX is the number of change in Gitlab. Once created, it is good practice to add the link as a comment to the feature in Gitlab.

For writing the design, you can check one of the previous designs, e.g. [feature 10593](https://osm.etsi.org/pad/p/feature10593), or use the design template below. 

```md
# XXXX FEATURE NAME

## CLARIFICATIONS TO EXPECTED E2E BEHAVIOUR

...

## REFERENCES

...

## ASSUMPTIONS

...

## IMPACTED MODULES

List of impacted modules: IM, RO, LCM, NBI, N2VC, common, MON, POL, NG-UI, osmclient, etc.

## MODULE1 IMPACT

...

## MODULE2 IMPACT

...

## TESTING

...
```

The design is expected to be socialized with the relevant stakeholders (e.g. MDLs and TSC). Dedicated slots can be allocated in the TECH calls on a per-request basis.

## OSM CI/CD

![OSM CI/CD Workflow](../assets/700px-OSM-CI-CD-workflow.png)

## Join the Community

- Join the [OSM Community Slack Workspace](https://join.slack.com/t/opensourcemano/shared_invite/enQtMzQ3MzYzNTQ0NDIyLWJkMzRjNDM0MjFjODYzMGQ3ODIzMzJlNTg2ZGI5OTdiZjFiNDMyMzYxMjRjNDU4N2FmNjRjNzY5NTE1MjgzOTQ)
- Subscribe the [OSM TECH](https://list.etsi.org/scripts/wa.exe?SUBED1=OSM_TECH&A=1) mailing list
- Get your organisation / project listed in the [OSM Ecosystem](https://osm.etsi.org/wikipub/index.php/OSM_Ecosystem)