Moved files of Developer Guide

# What to read next

[latest-hackfest]: https://osm.etsi.org/wikipub/index.php/8th_OSM_Hackfest#Hackfest_Material

[developer-guide]: https://url-to-be-inserted-when-published

If you want to learn more, these additional contents are highly recommended:

- **[VNF Onboarding Guide](http://osm-download.etsi.org/ftp/Documentation/vnf-onboarding-guidelines).** This guide includes all that you might need to onboard your VNF or applications in OSM.

- **[OSM Developer Guide][developer-guide].** If you want to contribute to OSM development, it is highly recommended reading this guide first.

- **[Contents from latest edition of OSM Hackfest][latest-hackfest].**

- **Sample VNF Packages.** This page is under elaboration, but you can find relevant contents in these locations:

  - **[Examples from OSM Hackfests][latest-hackfest]**

# Workflow with OSM tools

## Login to OSM portal

1. Go to OSM portal: https://osm.etsi.org/

2. Login using your username and password

**Note:**

- If you are [contributing on behalf of your company](15-participate.md), 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/welcome/#join)**

- If your company has **already joined OSM but you do not have an EOL account** yet, you can **[request an EOL account](http://webapp.etsi.org/createaccount/)**

- If you are an **individual contributor**, you can **[create your OSM account online](https://osm.etsi.org/index2.php?page=page_register.php)**.

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

## Report 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)

## Clone your project

1. Clone a git repository, for example:

```bash

git clone https://osm.etsi.org/gerrit/osm/RO.git 

```

2. Enter your username

3. Enter you password

4. It is mandatory to install the Gerrit commit-msg hook for the cloned repository in order to automatically insert a Change-Id tag in commit messages. You can install it by entering the following command for RO repository

```bash

 curl -Lo RO/.git/hooks/commit-msg http://osm.etsi.org/gerrit/tools/hooks/commit-msg 

```

You then need to make the hook executable

```bash

 chmod u+x RO/.git/hooks/commit-msg 

```

More information about the Gerrit commit-msg hook can be found [here](https://git.eclipse.org/r/Documentation/cmd-hook-commit-msg.html).

**Note**:

- You can find all the project repository URLs on [Gitweb](https://osm.etsi.org/gitweb/) or on [Gerrit](https://osm.etsi.org/gerrit/)

  - On Gitweb

    1. Click on **Gitweb** menu on the portal menu bar.

    2. Select a product to see the available cloning URLs

- On Gerrit

    1. Click on **Gerrit** menu on the portal menu bar.

    2. Click on "Projects" menu on the Gerrit menu bar.

    3. Click on "List" menu.

    4. Select a product to see the available cloning URLs.

## 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

```

```text

Note: Your email address will be visible on commits to Git.

If you'd like to keep your email address private, you can mask your email as follows:

if your email is <name@company.com> you can set user.email to <hidden@company.com>

This allows other users to identify you as a contributor (with your user name) and

Git Stats to keep track of your company's contributions (with the email 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

New Python contributions to Open Source Mano must support Python 3+. Python 2.7 reaches an End of Life status on 1 January 2020 and will no longer be supported with bug fixes or security patches.

## License Headers

Newly contributed Source Code should be licensed under the [Apache 2.0 license](https://www.apache.org/licenses/LICENSE-2.0). A [LICENSE](https://osm.etsi.org/gitweb/?p=osm/LCM.git;a=blob_plain;f=LICENSE;hb=HEAD) file shall exist at he root of the repository and all source files should have the following LICENSE header:

```text

# Copyright {yyyy} {name of copyright owner}

#

# 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.

```

Please update the template’s first line

```text

                 # Copyright {yyyy} {name of copyright owner}

```

- If you are adding a license header to an existing file, you can add

```text

                 # Copyright 2019 ETSI

```

- If you are adding a license header to a new file, you can add

```text

                 #  Copyright 2019 MyOrgName Inc

```

## Commit changes to your local project

1. Go to the "RO" folder

```bash

cd osm/RO

```

2. Make some changes on the source (e.g. add a line to the "example-file")

3. Stage the change.

```bash

 git add example-file

```

4. Commit the change to your local repository. You can add a bug id in your commit message to link the bug to your contribution

```bash

 git commit -s -m "Bug 2 fixed!!"  

```

5. You can see your commit message and update it, if needed, using the following command:

```bash

git commit --amend

```

### Developer's Certificate of Origin

- The `-s` parameter enables to Sign the contribution. It adds the following line at the end of your commit message:

```text

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

```

- The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to pass it on as a open-source patch. The rules are pretty simple: signing a contribution means that you can certify the below:

```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 Gerrit

### Push your contribution to Gerrit using `git push`

1. To avoid merge conflicts, it is recommended to do a pull with rebase before pushing your contribution in order to merge latest changes made by other users.

```bash

git pull --rebase

```

**Note**: you can force git to use always the `--rebase` option with:

```bash

git config --local pull.rebase true

```

2. Push your commits to **Gerrit** for Code Review using the following command:

```bash

git push origin HEAD:refs/for/master

#use 'v1.0' instead of 'master' for contributing to v1.0 branch

```

**Note**: you can also configure git to push always to the desired branch.

```bash

git config --local remote.origin.push HEAD:refs/for/master

git config --local remote.origin.push HEAD:refs/for/v1.0

```

3. Enter your username.

4. Enter your password.

5. You can review your contribution on **Gerrit** web interface

**Notes:**

- The following actions are execution automatically after pushing any contribution to Gerrit:

  - **Gerrit** reports the new contribution state to the corresponding bug in **Bugzilla**

  - **Gerrit** notifies **Jenkins** to build the new contribution.

### Push your contribution to Gerrit using git review

Instead of using "git push", you could use "git review". Follow this guide ([Using git-review to push and review changes](09-01-04-git-review.md)) to install and configure git-review. You will also have to set the SSH URL for your remote and copy the `commit-msg` hook.

- To avoid merge conflicts, it is recommended to do a pull with rebase before pushing your contribution.

```bash

git pull --rebase

```

- Then, send your contribution to gerrit:

```bash

git review -c

```

## Gerrit Notifications

Gerrit sends email notifications to:

- Owner of the change

- Reviewers of the change

- Project watchers

Each user can configure his own watched projects and branches in the "settings/watched project" menu. Email notifications can be sent for New Changes, New Patch Sets, All Comments, Submitted Changes and Abandoned Changes.

Link: <https://osm.etsi.org/gerrit/#/settings/projects> (you can navigate there from the Gerrit console by clicking on the arrow by your login on the top right corner)

## Continuous Integration

1. **Jenkins** builds, tests the new contribution, and reports the result on its web interface.

2. **Jenkins** votes on the contribution using **“Code-Verif”** (-1, +1) on **Gerrit**.

## Code Review

1. Other **contributors** and **MDG Committers** can comment the new contribution and vote using **“Code-Review”** (-1, 0, +1) on **Gerrit**.

2. The **MDG Leader** can comment the new contribution and votes using **“Code-Review”** (-2, -1, 0, +1, +2) on **Gerrit**.

## Amending a contribution in Gerrit

Before amending, make sure that you have the commit-msg hook installed in your local repo. For instance, if your user is "user" and the repo is the "devops" repo, the command to install the commit-msg hook would be:

```bash

$ scp -p -P 29418 user@osm.etsi.org:hooks/commit-msg devops/.git/hooks/

```

In that way, all patches will use the same Change Id, thus guaranteeing that they will be associated to the same change.

NOTE: If you don't setup your environment as above, and would like to update a gerrit review with your new/updated code, you MUST have the Change-Id (of the existing gerrit review) inside the commit message. If the commit update does not contain the Change-Id, the commit will will end up creating a new gerrit review, and your subsequent gerrit review will need to be abandoned (not ideal).

### Amending your last change/commit pushed to Gerrit

1. Get the latest changes from the repo and rebase your changes on top.

```bash

git pull --rebase

```

2. Fix the code and any conflicts that might have appeared after pulling the code.

3. Add all updated files to the index.

```bash

git add <file>

```

4. Amend your commit. **NOTE**: Don't use the -m flag to specify a commit message, since it will override the previous message and regenerate the Change-Id. Instead, use the text editor to change the commit message if needed, and keep the Change-Id line intact.

```bash

git commit --amend

```

5. Submit your change back to the repository. **NOTE**: use the appropriate branch instead of master, if you are working on a different branch.

```bash

git push origin HEAD:refs/for/master

```

### Amending one of your changes which has dependencies on subsequent changes

This procedure will only work if you are the only person working on a set of commits and you don't expect others to push commits and rebase them to be dependent on yours.

1. Run `git status` on the branch to know how many commits you are ahead of origin. **NOTE**: use the appropriate branch instead of master, if you are working on a different branch.

```bash

git status

On branch master

Your branch is ahead of 'origin/master' by 3 commits.

```

2. Do an interactive rebase over the last X commits and specify which commit you want to amend by changing the command of the commit from `pick` to `edit`. Use `drop` to abandon. Re-order the lines to put commits on a different order.

```bash

git rebase -i HEAD~3

 edit 0ab17ad Change in file1

 pick 4995f46 Second change

 pick baa85bf Third change

```

3. Fix the code in the commit, add the files, amend the commit, and continue rebasing:

```bash

vi file1.txt            #Fix the code

git add file1.txt

git commit --amend

git rebase --continue

```

4. In case of conflicts with subsequent commits, you will have to solve them, and continue rebasing

```bash

vi file1.txt            #Fix the conflict

git add file1.txt       #Add the files to the staging area; no commit is required.

git rebase --continue

```

5. Repeat step 4 as many times as required, until rebase finishes. You can cancel the whole operation at any moment with `git rebase --abort`

6. Rebase your contribution before pushing

```bash

git pull --rebase

```

7. Push your changes to gerrit. **NOTE**: use the appropriate branch instead of master, if you are working on a different branch.

```bash

git push origin HEAD:refs/for/master

```

### Amending a change of another author using git

When amending code from a different author, reviewer and original author should be coordinated in order to make sure that changes made by the reviewer are not reverted by the original author later. For that reason, it is recommended to avoid using the local copy of the branch. Instead, it is recommended to create a new local branch to work on every specific change, following the procedure below:

1. Get the last code from the repository.

```bash

git fetch origin

```

2. Create a new branch to work on the code from the remote branch. You can use the review number and patchset as name. **NOTE**: use the appropriate branch instead of master, if you are working on a different branch.

```bash

git checkout -b <review-number>-<patchset> origin/master

```

3. Pull the patch on the created branch. (To find the command to execute you can open the corresponding change page on Gerrit UI, click on download menu, then copy the "pull" command.)

```bash

git pull <url> <ref>

```

4. Fix the code.

5. Add all updated files to the index.

```bash

git add <file>

```

6. Amend the commit. **NOTE**: Don't use the -m flag to specify a commit message, since it will override the previous message and regenerate the Change-Id. Instead, use the text editor to change the commit message if needed, and keep the Change-Id line intact.

```bash

git commit --amend

```

7. Rebase your contribution before pushing

```bash

git pull --rebase

```

8. Submit your change back to the repository. **NOTE**: use the appropriate branch instead of master, if you are working on a different branch.

```bash

git push origin HEAD:refs/for/master

```

### Amending a change of another author using git-review

1. Follow the instructions in **[this link](09-01-04-git-review.md)** to install and configure git-review.

2. Download the change with git-review

```bash

$ git review -d 1280

Downloading refs/changes/80/1280/1 from gerrit

Switched to branch "review/garciadeblas/1280"

```

This will download the change, put it in a branch called review/AUTHOR/change (if the change has no tag, the sequence number will be used instead), and switch to that branch.

3. After that, you can amend the downloaded change to improve it. Finally, push it again:

```bash

#$ git add                         # add the changes

#$ git commit --amend              # do not touch the Change-Id. The Change-Id is the way for gerrit to keep track what belongs to what development stream as a new patch set.

#$ git commit --amend --author     # if you want to mark the changes as yours.

#$ git review -c -R                # The -R is important, since it tells git-review to not rebase your change against master.

```

**NOTE**: Don't use the -m flag to specify a commit message, since it will override the previous message and regenerate the Change-Id. Instead, use the text editor to change the commit message if needed, and keep the Change-Id line intact.

4. Delete the branch once you have finished:

```bash

$ git branch -D review/garciadeblas/1280

```

## Merging the contribution

1. The **MDG Leader** can "Submit" the change only if +1 **"Code-Verif"** (from **Jenkins**) and at least one +2 **"Code-Review"**.

2. **Gerrit** reports the result of the code review to the corresponding bug in **Bugzilla**

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

## 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)

# Using `git-review` to push and review changes

## Introduction

This page explains how to use `git-review` to resolve manually merge conflicts in gerrit. `Git-review` is a tool, developed in Openstack Infra, to make easier the review process through command line. More details on `git-review` can be found [here](09-01-04-git-review.md). Optionally, you can use git, as described in this [link](09-01-05-merge-conflicts.md).

## Install and configure `git-review`

```bash

$ sudo apt-get install git-review

```

Optionally, you could install it through pip:

```bash

$ sudo apt-get install python-pip

$ sudo easy_install pip

$ sudo pip install git-review

```

Configure `git-review`. These options are required to work easily with OSM:

```bash

$ git config --global gitreview.remote origin

$ git config --global gitreview.username myusername

$ git config --global gitreview.track true

```

## Prepare your repo

For `git-review` to work properly, it is recommended to clone the repo via the SSH URL and to copy the commit-msg hook. If your user is "user" and the repo is the devops repo, the command would be:

```bash

$ git clone ssh://user@osm.etsi.org:29418/osm/devops && scp -p -P 29418 user@osm.etsi.org:hooks/commit-msg devops/.git/hooks/

```

**NOTE**: HTTP and HTTPS URLs might work by setting the variable `gitreview.scheme` to "http" or "https" respectively, although it has not been tested.

If you have your repo already cloned (e.g. devops), you can use the following commands to set SSH URL and get the commit-msg hook:

```bash

$ cd devops

$ git remote set-url origin ssh://user@osm.etsi.org:29418/osm/devops

$ scp -p -P 29418 user@osm.etsi.org:hooks/commit-msg .git/hooks/

```

After cloning a repository, you need to set it up for `git-review`. This happens automatically the first time you submit a commit, but it's recommended to do it right after cloning.

```bash

$ git review -s

```

## Push your changes to gerrit

First, commit your files locally:

```bash

$ git add file2.txt

$ git commit -s -m "New file: file2"

[master b8efc98] New file: file2

 1 file changed, 1 insertion(+)

 create mode 100644 file2.txt

```

Then push your commits to gerrit, with `git review -c`.

```bash

$ git review -c

remote: Processing changes: new: 1, refs: 1, done

remote: Missing issue-id in commit message

remote: Commit b05fa3cf2a09cc6e27b14bed2c0403282ceba64d not associated to any issue

remote:

remote: Hint: insert one or more issue-id anywhere in the commit message.

remote:       Issue-ids are strings matching [Bb][Uu][Gg][ ]*([1-9][0-9]*)

remote:       and are pointing to existing tickets on its-bugzilla Issue-Tracker

remote:

remote: New Changes:

remote:   https://osm.etsi.org/gerrit/1267 New file: file2

remote:

To ssh://garciadeblas@osm.etsi.org:29418/test

 * [new branch]      HEAD -> refs/for/master

```

**Note**: The option `-c` is important because, otherwise, it won't work in OSM. The reason is that option `-c` makes pushes to `refs/for/*` instead of `refs/publish/*`, which allows to work with old versions of gerrit. Current gerrit version in OSM can work with both `refs/for` and `refs/publish`, but branches have been created in `refs/for`. Migrating to `refs/publish` is a major effort, so we will have to keep the old approach until we can migrate.

## Amending a change

First, download the change with `git-review`

```bash

$ git review -d 1280

Downloading refs/changes/80/1280/1 from gerrit

Switched to branch "review/garciadeblas/1280"

```

This will download the change, put it in a branch called `review/AUTHOR/change` (if the change has no tag, the sequence number will be used instead), and switch to that branch.

After that, you can amend the downloaded change to improve it. Finally, push it again

```bash

$ git add                         # add the changes

$ git commit --amend              # do not touch the Change-Id. The Change-Id is the way for gerrit to keep track what belongs to what development stream as a new patch set.

$ git commit --amend --author     # if you want to mark the changes as yours.

$ git review -c -R                # The -R is important, since it tells git-review to not rebase your change against master.

```

**NOTE**: Don't use the -m flag to specify a commit message, since it will override the previous message and regenerate the Change-Id. Instead, use the text editor to change the commit message if needed, and keep the Change-Id line intact.

## `Git-review` for administrators and reviewers

Besides the previous commands, there are useful commands for reviewers (MDLs, TSC, etc.).

**NOTE**: Option `-c` is always mandatory since we are using old schema for branches in gerrit.

### Listing open reviews

```bash

git review -l

```

### Submitting for review

- To add a topic:

```bash

git review -t topic/blahblahblah

```

- To add reviewers

```bash

git review --reviewers john@aaa.com tracy@bbb.com

```

- To submit for review and then remove the local branch:

```bash

git review -f

```

- To submit for review as a draft:

```bash

git review -D

```

### Reviewing

- To download a change using change number:

```bash

git review -d 1200

```

- To download a specific patchset:

```bash

git review -d 1200,2

```

- To compare two patches of the same change:

```bash

git review -m 1200,2-5

```

### Scoring code review

`Git-review` does not allow yet sending a -2/-1/+1/+2 for code review, and does not allow submitting a change. For that, you can use [gerrit command line](https://review.openstack.org/Documentation/cmd-index.html).

For using gerrit review command line, it is recommended that you configure your ssh config file located in `~/.ssh/config` and you add there our gerrit server:

```text

Host review

  Hostname osm.etsi.org

  Port 29418

  User youreolaccount

```

Then, to do a code review of a specific change, you can follow the instructions in [this link](https://review.openstack.org/Documentation/cmd-review.html). Some examples of the gerrit review command line below:

```bash

ssh review gerrit review --verified +1 ce7f5a0b

ssh review gerrit review --code-review +1 -m "'Looks good to me.'" ce7f5a0b

ssh review gerrit review --verified +1 --code-review +2 --submit --project osm/RO ce7f5a0b

ssh review gerrit review --label mylabel=+1 ce7f5a0b

ssh review gerrit review --abandon ce7f5a0b

```

You can also do other things with gerrit command line, such as querying the open changes:

```bash

ssh review gerrit query status:open project:osm/RO

ssh review gerrit query status:open project:osm/RO limit:5

```