Latest revision as of 10:50, 14 March 2019

Pre-requisites

In the following we will assume you successfully

followed the Getting started guide,
(Optional) Configured your git environment.
(Optional) Cloned the repository.

Upload your contribution

1) Create a working branch for your contribution

Advanced users: forking will work as well but you will need to setup your CI environment

A Git repository is organized in branches, each containing slightly different versions of the project built on others. A working branch is the location for you code contribution to be reviewed.

To create a new branch using the web interface:

Visit the project page
In the menu on the left click Repository and then Branches
Click the New Branch button and fill in the required information

IMPORTANT: Make sure that you are creating a branch on top of the latest version of your target branch.

E.g. if you want to contribute on the master branch, your newly created branch needs to be based on the latest commit in master.

In GIT commands: $ git checkout <target-branch> $ git pull origin <target-branch> $ git branch <your-branch-name> $ git checkout <your-branch-name>

2) Create/edit the content

Beginners: Use the online edit area or the Web Ide.

Advanced users: Edit and commit content in your local repository

3) Save your change in your working branch on the server

Web Interface

Using git

Assuming you want to push a local-branch onto a remote-branch, you want to use the command:

 git push origin local-branch:remote-branch

4) Create a Merge request against master or your target branch

5) Notify the project leaders

6) Accept and merge the contribution

Users with role Master in the repository will be able to accept Merge Requests into the master branch or any of the protected branches.

Roles are mandated by the technical group who manages the repository and applied by the ETSI Staff.

More information on accepting Merge Requests may be found at Accept Merge Request.

Warning:
The rest of the page needs revision. Some of the information in the page may be deprecated.

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.

git pull --rebase

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

git config --local pull.rebase true

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

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.

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

git pull --rebase

Then, send your contribution to gerrit:

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

Jenkins builds, tests the new contribution, and reports the result on its web interface.
Jenkins votes on the contribution using “Code-Verif” (-1, +1) on Gerrit.

Code Review

Other contributors and MDG Committers can comment the new contribution and vote using “Code-Review” (-1, 0, +1) on Gerrit.
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:

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

Amending your last change/commit pushed to Gerrit

1. Fix the code.

2. Add all updated files to the index.

git add <file>

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

git commit --amend

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

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.

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

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:

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

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.

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

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.

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.

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

git pull <url> <ref>

4. Fix the code.

5. Add all updated files to the index.

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.

git commit --amend

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

git push origin HEAD:refs/for/master

Amending a change of another author using git-review

1. Follow the instructions in this link to install and configure git-review.

2. Download the change with git-review

$ 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:

$ 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:

$ git branch -D review/garciadeblas/1280

Merging the contribution

The MDG Leader can "Submit" the change only if +1 "Code-Verif" (from Jenkins) and at least one +2 "Code-Review".
Gerrit reports the result of the code review to the corresponding bug in Bugzilla

Template:Feedback

@@ Line 1: / Line 1: @@
 __TOC__
+= Pre-requisites =
+In the following we will assume you successfully
+* followed the [[Get started|Getting started]] guide,
+* ('''Optional''') [[Configure your git environment|Configured your git environment]].
+* ('''Optional''') [[Clone a repository|Cloned the repository]].
-= Login to ETSI Forge =
+= Upload your contribution =
-# Go to the FORGE portal: https://forge.etsi.org/
-# Login using your username and password at https://forge.etsi.org/index.php/users/login/
-# If you are an ETSI Online Account (EOL) holder then please use the EOL credentials
-# Otherwise register for a local acocunt at https://forge.etsi.org/index.php/register
-'''Note:'''  http://webapp.etsi.org/createaccount/
+===1) Create a working branch for your contribution ===
+'''Advanced users''': forking will work as well but you will need to setup your CI environment
-<!--* If you are '''[[Participate|contributing on behalf of your company]]''', you should login with your '''ETSI Online Account (EOL)'''.
+A Git repository is organized in branches, each containing slightly different versions of the project built on others. '''A working branch is the location for you code contribution to be reviewed'''.
-** If your company is not yet an '''[https://portal.etsi.org/TBSiteMap/OSM/ListofOSMMembers.aspx OSM Member or Participant]''', you can check here '''[https://osm.etsi.org/welcome/#join how to join OSM as an organization]'''
-** If your company has '''already joined TDL but you do not have an EOL account''' yet, you can '''[http://webapp.etsi.org/createaccount/ request an EOL account]'''
-* If you are an '''individual contributor''', you can '''[https://osm.etsi.org/index2.php?page=page_register.php create your OSM account online]'''.
+To create a new branch using the web interface:
+# Visit the project page
+# In the menu on the left click Repository and then Branches
+# Click the New Branch button and fill in the required information
-If you need any help, contact us at [mailto:cti_support@etsi.org cti_support@etsi.org] -->
+IMPORTANT: Make sure that you are creating a branch on top of the latest version of your target branch.
-= Clone your project =
+E.g. if you want to contribute on the master branch, your newly created branch needs to be based on the latest commit in master.
-This is a procedure that should work in most of the cases and is good for starters with Git and Gerrit. Experienced users can rely on their preferred cloning procedures.
+In GIT commands:
+<code>
+$ git checkout <target-branch>
+$ git pull origin <target-branch>
+$ git branch <your-branch-name>
+$ git checkout <your-branch-name>
+</code>
-# Navigate to the project general page ([https://forge.etsi.org/gerrit/#/admin/projects/ List of all the projects]), for example the [https://forge.etsi.org/gerrit/#/admin/projects/playground Playground project].
+===2) Create/edit the content ===
+'''Beginners''': Use the online edit area or the Web Ide.
-# Now select the options "Clone with commit hook" and "anonymous http" (we suggest anonymous since it seems the only way to make it work with Windows Credential helper).
+'''Advanced users''': Edit and commit content in your local repository
-[[File:Forge-clone-options.PNG|frame|center|The options recommended to be selected]]
+=== 3) Save your change in your working branch on the server ===
-# Copy the command shown in the page into the clipboard.
+==== Web Interface ====
-# Open the folder on your PC where you want the files to be put.
+==== Using git ====
-# Right click on the white space and select "Git Bash Here".
-# Paste the command that you copied from Gerrit and hit "Enter"
-# You will be asked to insert user name and password by the WIndows Credential Helper. Insert your EOL user name and '''the HTTP password you generated in the Gerrit Settings'''. Check the "Git Bash". If it says "Unauthorized": try again the command (hit the Up key and it will be shown), this time in the Windows Credential Helper click "Cancel", then a new window will pop up where you should put again the EOL user name and the HTTP password.
-[[File:Windows-pass-man.PNG|frame|center|The Windows Credential Helper window]]
+Assuming you want to push a local-branch onto a remote-branch, you want to use the command:
-'''Note''':
+  git push origin local-branch:remote-branch
-* You can find all the project repository URLs on '''[https://forge.etsi.org/rep/ Gitweb]''' or on '''[https://forge.etsi.org/gerrit/ Gerrit]'''
-** On Gitweb
-**# Click on '''Gitweb''' menu on the portal menu bar.
-**# Select a product to see the available cloning URLs
-** On Gerrit
-**# Click on '''Gerrit''' menu on the portal menu bar.
-**# Click on "Projects" menu on the Gerrit menu bar.
-**# Click on "List" menu.
-**# Select a product to see the available cloning URLs.
-= Configure your Git environment =
+=== 4) Create a Merge request against master or your target branch ===
-# Configure your git username globally: <pre> git config --global user.name <username> </pre>
-# Configure your git email address:  <pre> git config --global user.email <email> </pre>
-# Check your git configuration:  <pre> git config --list </pre>
- '''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: <pre>git config --local user.name <username>
+=== 5) Notify the project leaders ===
-git config --local user.email <email> </pre>
-= Commit changes to your local project =
+=== 6) Accept and merge the contribution ===
-# Go to the project root folder <pre>cd project</pre>
-# Make some changes on the source (e.g. add a line to the "example-file")
-# Stage the change. <pre> git add example-file </pre>
-# Commit the change to your local repository. You can add a bug id in your commit message to link the bug to your contribution  <pre> git commit -s -m "Bug 2 fixed!!"  </pre>
-# You can see your commit message and update it, if needed, using the following command: <pre>git commit --amend </pre>
-==Developer's Certificate of Origin==
+Users with role '''Master''' in the repository will be able to accept Merge Requests into the '''master branch''' or any of the protected branches.
-* The "-s" parameter enables to Sign the contribution. It adds the following line at the end of your commit message:
-<pre>   Signed-off-by: Random J Developer <random@developer.example.org></pre>
-* 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:
+Roles are mandated by the technical group who manages the repository and applied by the ETSI Staff.
-<pre>
+More information on accepting Merge Requests may be found at [[Accept Merge Request]].
-        Developer's Certificate of Origin 1.1
-        By making a contribution to this project, I certify that:
+<br /><br /><br />
-        (a) The contribution was created in whole or in part by me and I
+{{Warning|The rest of the page needs revision. Some of the information in the page may be deprecated.}}
-            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
+= Using git push ==
-            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.
-</pre>
-= Push your contribution to Gerrit =
-== Push your contribution to Gerrit using git push ==
 . 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.
   git pull --rebase
@@ Line 142: / Line 102: @@
 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 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)
+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 =
@@ Line 210: / Line 170: @@
 . 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.)
-  git pull <url> <ref>
+  git pull <url> <nowiki><ref></nowiki>
 . Fix the code.

Navigation menu

Difference between revisions of "How to contribute"