Latest revision as of 10:36, 5 November 2015

This page describes how to contribute a patch to a Mer package and how to resubmit corrected patches. It is the user facing part of the Mer change control process

Nov 2015: we've migrated from gerrit to gitlab and will follow a more github-like 'merge request' approach. The guide below is a WIP and mainly useful as an editing baseline. Talk to lbt or Stskeeps in #mer for more details.

[edit] Initial setup

Mer uses GitLab to store the code used in Mer Core (and other related areas) packages.

The first thing you should do is to register yourself on the Mer Bugzilla and then use your new username to login to Mer's GitLab

You then need to generate yourself a SSH key and upload it to the SSH keys page

Mer's git is accessed on port 2222 so the easy way to ensure it 'just works' is to add this to your ~/.ssh/config file:

  Host git.merproject.org
    User git
    ProxyCommand none
    Compression no
    Port 2222
    ForwardX11 no
    IdentityFile ~/.ssh/id_rsa_gitlab

It assumes you've setup and are using the Platform SDK

[edit] Preparation

You'll need git and osc setup and a Mer account to use the Mer git repos. You also need to be able to perform a trial build on the Mer Community OBS.

[edit] Configure osc

The first time you try to access one of those using osc ( for example osc -A https://api.merproject.org ls ) osc will ask for a username and a password, and it will save them in the config file, which is very well commented to describe various advanced options.

For the rest of this guide you should use "osc -A https://api.merproject.org" whereever osc is mentioned in a command. See Osc_Setup for more information.

[edit] Submit a change

[edit] Summary

Branch the OBS package in either your local OBS or the community OBS. The public submission will need a public build.
Checkout the package from OBS
Incorporate a bare clone mer/git package from Mer master repo into the osc directory.
Clone the mer/git package from Mer master repo (The OBS and mer/git package should be identical.)
Unpack the source and apply patches (usually in a local build root)
Optionally take a snapshot of chroot (for later diff)
Hack in chroot until ready (potentially needing to install new pkgs for new BRs)
Create a patch
Modify packaging
Submit to OBS to verify build
Build and test and image or other appropriate QA
Submit to gerrit for CI and review

[edit] Branch the package to work on it

osc branch mer:mds2:Core:i486:master systemd (FIXME: explain when/why use :arch)

A bug in the OBS means that the new branch project will not have the correct repos so add them manually. Even if you add them through the OBS web interface they will miss the arch field.

osc meta prj home:YOURNAME:branches:mer:mds2:Core:i486:master -e

Add the following under the <project> root tag as the last element (after 'person' element):

  <repository name="Mer_Core_i486">
   <path repository="Core_i486" project="mer:mds2:Core:i486:master"/>
   <arch>i586</arch>
  </repository>

The repository needs to be set to publish too. (FIXME: How/where to do this publish?)

Checkout:

  osc co home:YOURNAME:branches:mer:mds2:Core:i486:master/systemd
  cd home:YOURNAME:branches:mer:mds2:Core:i486:master/systemd
  osc build i586

Note: If the build failed with a BuildService API error, add --no-verify to the command.

[edit] Pull the latest Mer version from the gerrit git repo

Clone the git repo metadata into your OSC checkout using git's --bare option :

  cd home:YOURNAME:branches:mer:mds2:Core:i486:master/systemd
  git clone --bare ssh://your_username@review.merproject.org:29418/mer-core/systemd .git
  git config -f .git/config core.bare false

Check out the latest content from git:

  git reset --hard

[edit] Hack

You can now edit the code and packaging

[edit] Build

Of course you'll need to do one or more builds to verify the code in a cycle like this:

 specify *yaml
 osc build i586 *.spec
 osc chroot i586 *.spec

If you're working on a different architecture such as armv7hl then see the OBS architecture naming page to explain why you need "osc build armv8el *.spec"

Then a server-side build:

 osc ar
 osc ci

[edit] Create image

Use a suitable .ks with mic2

If you use IMG, it supports a feature called "Extra repositories and packages". This allows you to use a standard kickstart and add a specific repository to use for overrides.

Select the OBS and enter the repository/repo eg:

 home:Admin:branches:mer:mds2:Core:i486:master/Mer_Core_i486

Build a suitable image, install and test

[edit] Edit Changelog

In the obs/mer package directory:

  cd home:Admin:branches:mer:mds2:Core:i486:master

If the version has changed or if you've otherwise edited the yaml file, re-run specify.

Make a note in the .changes file about the modification made.

If you are closing a bug then add a line like

- Fixes MER#XYZ : Summary of bug

[edit] Push for review

Ensure your git username is set correctly

  git config --global user.name "first last"

Ensure you have done a git add/rm on any files that have been affected.

If this is a new change (ie it hasn't been rejected and corrected) then:

  git commit -s

When you're satisfied:

  git push origin HEAD:refs/for/master

You should get back a message like:

remote: New Changes:
remote:   http://review.merproject.org/XXX

This will now be scheduled for a CI build and test; then it will be manually reviewed and hopefully, accepted.

If you are fixing a bug/request in BugZilla, include a comment to BugZilla with a link to the review URL and mark the bug as fixed.

[edit] Re-submit if original change was rejected

If your changes is rejected for some reason (a frequent occurence) then you should address the issues and resubmit.

[edit] Summary

For Mer this is done by:

Address the issue
Finding the Change-Id
amending the commit
adding a Change-Id: line
resending the change

[edit] Address review issues

The gerrit tool is used to permit reviews of your code. If the change is rejected then the tool should have a comment explaining what needs to be done to resolve the issue. Make these changes and re-test your code.

[edit] Obtain Change-Id:

When you are ready to submit go to the gerrit page for your change

 http://review.merproject.org/XXX

In the top left is gerrit's Change-Id: field. Adding this to the commit message will allow gerrit to replace the original commit and retain a history of reviews and responses.

Copy the Change-Id: value including the text "Change-Id:"

[edit] Prepare an amended commit

The commit should now be committed using:

 git add <changed files>
 git commit -s --amend

and the commit message should have the "Change-Id:" as the last line after the signed-off line.

[edit] Push commit for re-review

Now push the commit to gerrit using

 git push origin HEAD:refs/for/master

[edit] New Packages

Occasionally a new package is required in Mer.

[edit] Summary

The process is similar to the normal contribution with some minor variations.

Build your package in the community OBS
Propose a new package on irc, mailing list or via a bug to Mer Core/.Project-core
Wait for the git repo to be created
Checkout your package from your OBS project
Prepare a git repo and add your code. Then do a signed-off commit.
Link your local git repository to the remote mer-core/gerrit repository
Push your code for review and CI

[edit] Prepare your new package

So having prepared and built your package on OBS, go to the osc package directory

osc co <PRJ> <PKG>
cd <PRJ>/<PKG>

[edit] Prepare a git repo

Then prepare the git repo (skipping the .osc/ dir)

git init .
git add *
git commit -s

Now add the Mer git repository (using your name/package)

git remote add gerrit ssh://<yourlogin>@review.merproject.org:29418/mer-core/<packagename>

A quick way to check all is well is

git remote update

[edit] Send for review

Finally, to push the new code and start a CI run:

git push gerrit HEAD:refs/for/master

You should get back a message like:

remote: New Changes:
remote:   http://review.merproject.org/XXX

This will now be scheduled for a CI build and test; then it will be manually reviewed and hopefully, accepted.

[edit] Removing / Renaming Packages

Mer doesn't yet have a process to remove or rename packages.

(aside: Any process must consider the impact on recreating releases that contain the package.)

[edit] Handling rejection

If changes are needed at this point, the code is already in gerrit so it follows the normal modification process above.

[edit] What goes wrong

There are a lot of ways to get package submission wrong. We're working on automatically detecting these but here are things to check:

Ensure you follow the Packaging guidelines especially for formatting, bug references and Mer versioning
Commit comments should have enough content to explain the issue - bear in mind the audience may read this message well in the future.
make sure all your files are added to git (currently git and osc can have different files under change control - 'osc ar' won't ensure they get added to git and sent for review)
Your package should be minimal - don't require or build-require packages you don't need
Your package should follow best practice - eg use PkgConfigBR where possible
Pay attention to rpmlintian (though we have not fully tuned it for Mer yet)

[edit] Feedback

The people reviewing your code (and yes, they are people, not sadistic monsters who enjoy laughing at your contributions ... apart from Sage) will try to give you concise and honest feedback.

Usually they'll address all the issues they see in the code so (provided no new problems are introduced) a second submission correcting the points raised should be accepted. Sometimes a second review will reveal issues missed the first time around - annoying but it happens.

Over time you will become more familiar with the review process and eventually you may start to comment on contributions yourself.

Contribution in detail

Latest revision as of 10:36, 5 November 2015

Contents

[edit] Initial setup

[edit] Preparation

[edit] Configure osc

[edit] Submit a change

[edit] Summary

[edit] Branch the package to work on it

[edit] Pull the latest Mer version from the gerrit git repo

[edit] Hack

[edit] Build

[edit] Create image

[edit] Edit Changelog

[edit] Push for review

[edit] Re-submit if original change was rejected

[edit] Summary

[edit] Address review issues

[edit] Obtain Change-Id:

[edit] Prepare an amended commit

[edit] Push commit for re-review

[edit] New Packages

[edit] Summary

[edit] Prepare your new package

[edit] Prepare a git repo

[edit] Send for review

[edit] Removing / Renaming Packages

[edit] Handling rejection

[edit] What goes wrong

[edit] Feedback

Views

Personal tools

Navigation

Search

Tools

@@ Line 1: / Line 1: @@
-= Local build of current version =
+This page describes how to contribute a patch to a Mer package and how to resubmit corrected patches. It is the user facing part of the [[process| Mer change control process]]
-Need prerequisites for osc and build
+Nov 2015: we've migrated from gerrit to gitlab and will follow a more github-like 'merge request' approach. The guide below is a WIP and mainly useful as an editing baseline. Talk to lbt or Stskeeps in #mer for more details.
+=== Initial setup ===
+Mer uses [https://about.gitlab.com/ GitLab] to store the code used in Mer Core (and other related areas) packages.
+The first thing you should do is to register yourself on [http://bugs.merproject.org/ the Mer Bugzilla] and then use your new username to login to [https://git.merproject.org/ Mer's GitLab]
+You then need to generate yourself a SSH key and upload it to [https://git.merproject.org/profile/keys the SSH keys page]
+Mer's git is accessed on port 2222 so the easy way to ensure it 'just works' is to add this to your <code>~/.ssh/config</code> file:
+   Host git.merproject.org
+     User git
+     ProxyCommand none
+     Compression no
+     Port 2222
+     ForwardX11 no
+     IdentityFile ~/.ssh/id_rsa_gitlab
+It assumes you've setup and are using the [[Platform SDK]]
+= Preparation =
+You'll need git and osc setup and a Mer account to use the Mer git repos. You also need to be able to perform a trial build on the Mer Community OBS.
+== Configure osc ==
+The first time you try to access one of those using osc ( for example osc -A https://api.merproject.org ls ) osc will ask for a username and a password, and it will save them in the config file, which is very well commented to describe various advanced options.
+For the rest of this guide you should use "osc -A https://api.merproject.org" whereever osc is mentioned in a command. See [[Osc_Setup]] for more information.
+= Submit a change =
+== Summary ==
+# Branch the OBS package in either your local OBS or the community OBS. The public submission will need a public build.
+# Checkout the package from OBS
+# Incorporate a bare clone mer/git package from Mer master repo into the osc directory.
+# Clone the mer/git package from Mer master repo (The OBS and mer/git package should be identical.)
+# Unpack the source and apply patches (usually in a local build root)
+# Optionally take a snapshot of chroot (for later diff)
+# Hack in chroot until ready (potentially needing to install new pkgs for new BRs)
+# Create a patch
+# Modify packaging
+# Submit to OBS to verify build
+# Build and test and image or other appropriate QA
+# Submit to gerrit for CI and review
 == Branch the package to work on it ==
-  osc -A https://obs:444/ branch Mer.org:Core:i586 systemd
+  osc branch mer:mds2:Core:i486:master systemd (FIXME: explain when/why use :arch)
 A bug in the OBS means that the new branch project will not have
-the correct repos so add them manually
+the correct repos so add them manually. Even if you add them through the OBS web interface they will miss the arch field.
-    <repository name="Mer_Core_i586">
+ osc meta prj home:YOURNAME:branches:mer:mds2:Core:i486:master -e
-     <path repository="Core_i586" project="Mer.org:Core:i586"/>
+Add the following under the <project> root tag as the last element (after 'person' element):
+    <repository name="Mer_Core_i486">
+     <path repository="Core_i486" project="mer:mds2:Core:i486:master"/>
      <arch>i586</arch>
     </repository>
-The repository needs to be set to publish too.
+The repository needs to be set to publish too. (FIXME: How/where to do this publish?)
 Checkout:
-    osc -A https://obs:444 co home:Admin:branches:Mer.org:Core:i586/systemd
+    osc co home:YOURNAME:branches:mer:mds2:Core:i486:master/systemd
-    cd home:Admin:branches:Mer.org:Core:i586/systemd
+    cd home:YOURNAME:branches:mer:mds2:Core:i486:master/systemd
     osc build i586
-== Pull the latest Mer version and .git ==
+Note: If the build failed with a BuildService API error, add --no-verify to the command.
-Clone the mer git repo too:
+== Pull the latest Mer version from the gerrit git repo ==
-    cd home:Admin:branches:Mer.org:Core:i586
+Clone the git repo metadata into your OSC checkout using git's --bare option :
-    git clone ssh://lbt@review.merproject.org:29418/mer-ore/systemd tmp
-    mv tmp/.git systemd/
+    cd home:YOURNAME:branches:mer:mds2:Core:i486:master/systemd
-   rm -rf tmp
+    git clone --bare ssh://your_username@review.merproject.org:29418/mer-core/systemd .git
-   cd systemd
+    git config -f .git/config core.bare false
-    git status
+Check out the latest content from git:
+    git reset --hard
 == Hack ==
-You can now edit the code and packaging.
+You can now edit the code and packaging
 == Build ==
-Of course you'll need to do one or more builds to verify the code.
+Of course you'll need to do one or more builds to verify the code in a cycle like this:
-   osc ar
+  specify *yaml
-   osc ci
+  osc build i586 *.spec
-   osc chroot
+  osc chroot i586 *.spec
-   osc build
+If you're working on a different architecture such as armv7hl then see the [[OBS architecture naming]] page to explain why you need "osc build armv8el *.spec"
+Then a server-side build:
+  osc ar
+  osc ci
 == Create image ==
-Use a suitable .ks
+Use a suitable [[:Category:kickstart|.ks]] with [[:Category:mic2|mic2]]
-IMG supports a feature called "Extra repositories and packages"
+If you use [[:Category:IMG|IMG]], it supports a feature called "Extra repositories and packages".
 This allows you to use a standard kickstart and add a specific
 repository to use for overrides.
@@ Line 55: / Line 115: @@
 Select the OBS and enter the repository/repo eg:
-   home:Admin:branches:Mer.org:Core:i586/Mer_Core_i586
+   home:Admin:branches:mer:mds2:Core:i486:master/Mer_Core_i486
-Build a suitable image, install and test
+Build a [[:Category:image|suitable image]], install and test
-  DEVICE=/dev/sdh
+== Edit Changelog ==
-  curl http://imgw1/images/web/root/1-20111110-090037/meego-nemo-trial-1.2.90.20111110.1000.iso | sudo dd of=$DEVICE bs=4M oflag=direct && sudo eject $DEVICE
-Diagnostic note:
+In the obs/mer package directory:
+   cd home:Admin:branches:mer:mds2:Core:i486:master
-Package SOMETHING.rpm is damaged:
+If the version has changed or if you've otherwise edited the yaml file, re-run specify.
-  /var/tmp/cache/packages/mer-core-i586/noarch/filesystem-2.4.31-1.1.noarch.rpm
-This means a checksum mismatch was seen and the package was re-downloaded.
+Make a note in the .changes file about the modification made.
+If you are closing a bug then add a line like
+ - Fixes MER#XYZ : Summary of bug
 == Push for review ==
-In the obs/mer build directory:
+Ensure your git username is set correctly
-    cd home:Admin:branches:Mer.org:Core:i586
-    git commit -s --amend
+    git config --global user.name "first last"
+Ensure you have done a git add/rm on any files that have been affected.
+If this is a new change (ie it hasn't been rejected and corrected) then:
+    git commit -s
+When you're satisfied:
     git push origin HEAD:refs/for/master
+You should get back a message like:
+ remote: New Changes:
+ remote:   http://review.merproject.org/XXX
+This will now be scheduled for a CI build and test; then it will be
+manually reviewed and hopefully, accepted.
+If you are fixing a bug/request in BugZilla, include a comment to BugZilla with a link to the review URL and mark the bug as fixed.
+= Re-submit if original change was rejected =
+If your changes is rejected for some reason (a frequent occurence) then you should address the issues and resubmit.
+== Summary ==
+For Mer this is done by:
+# Address the issue
+# Finding the Change-Id
+# amending the commit
+# adding a Change-Id: line
+# resending the change
+== Address review issues ==
+The gerrit tool is used to permit reviews of your code. If the change is rejected then the tool should have a comment explaining what needs to be done to resolve the issue. Make these changes and re-test your code.
+== Obtain Change-Id: ==
+When you are ready to submit go to the gerrit page for your change
+  http://review.merproject.org/XXX
+In the top left is gerrit's Change-Id: field. Adding this to the commit message will allow gerrit to replace the original commit and retain a history of reviews and responses.
+Copy the Change-Id: value including the text "Change-Id:"
+== Prepare an amended commit ==
+The commit should now be committed using:
+  git add <changed files>
+  git commit -s --amend
+and the commit message should have the "Change-Id:" as the last line after the signed-off line.
+== Push commit for re-review ==
+Now push the commit to gerrit using
+  git push origin HEAD:refs/for/master
+= New Packages =
+Occasionally a new package is required in Mer.
+== Summary ==
+The process is similar to the normal contribution with some minor variations.
+# Build your package in the community OBS
+# Propose a new package on irc, mailing list or via a bug to Mer Core/.Project-core
+# Wait for the git repo to be created
+# Checkout your package from your OBS project
+# Prepare a git repo and add your code. Then do a signed-off commit.
+# Link your local git repository to the remote mer-core/gerrit repository
+# Push your code for review and CI
+== Prepare your new package ==
+So having prepared and built your package on OBS, go to the osc package directory
+ osc co <PRJ> <PKG>
+ cd <PRJ>/<PKG>
+== Prepare a git repo ==
+Then prepare the git repo (skipping the .osc/ dir)
+ git init .
+ git add *
+ git commit -s
+Now add the Mer git repository (using your name/package)
+ git remote add gerrit ssh://<yourlogin>@review.merproject.org:29418/mer-core/<packagename>
+A quick way to check all is well is
+ git remote update
+== Send for review ==
+Finally, to push the new code and start a CI run:
+ git push gerrit HEAD:refs/for/master
+You should get back a message like:
+ remote: New Changes:
+ remote:   http://review.merproject.org/XXX
+This will now be scheduled for a CI build and test; then it will be
+manually reviewed and hopefully, accepted.
+= Removing / Renaming Packages =
+Mer doesn't yet have a process to remove or rename packages.
+(aside: Any process must consider the impact on recreating releases that
+contain the package.)
+= Handling rejection =
+If changes '''are''' needed at this point, the code is already in gerrit so it follows the normal modification process above.
+== What goes wrong ==
+There are a '''lot''' of ways to get package submission wrong. We're working on automatically detecting these but here are things to check:
+* Ensure you follow the [[Packaging guidelines]] especially for formatting, bug references and Mer versioning
+* Commit comments should have enough content to explain the issue - bear in mind the audience may read this message well in the future.
+* make sure all your files are added to git (currently git and osc can have different files under change control - 'osc ar' won't ensure they get added to git and sent for review)
+* Your package should be minimal - don't require or build-require packages you don't need
+* Your package should follow best practice - eg use PkgConfigBR where possible
+* Pay attention to rpmlintian (though we have not fully tuned it for Mer yet)
+== Feedback ==
+The people reviewing your code (and yes, they are people, not sadistic monsters who enjoy laughing at your contributions ... apart from Sage) will try to give you concise and honest feedback.
+Usually they'll address all the issues they see in the code so (provided no new problems are introduced) a second submission correcting the points raised should be accepted. Sometimes a second review will reveal issues missed the first time around - annoying but it happens.
+Over time you will become more familiar with the review process and eventually you may start to comment on contributions yourself.