gistfile1.asciidoc

Patching in the YP

1. Basics Git commands

2. Table of YP’s Repositories

3. Patch’s creation

4. Patch’s submission

5. Post-patch submission

6. Good OpenSource practices

7. Scritps

8. Links

Git basics

Configuration

git config --global user.email "your.email@linux.intel.com"
git config --global user.name "Your Name"
git config --global core.editor emacs
git config --global sendemail.from "your.email@linux.intel.com"
git config --global sendeemail.smtpserver "fm-out.intel.com"

Tip	You can also edit manually the file ~/.gitconfig

Basics

Creating a repo and tracking files

DIR=newrepo; mkdir $DIR
cd $DIR
git init							# Creates a repo, no content yet
touch {README,INSTALL,LICENSE,sample-product.c,Makefile}
git status							# untracked files are shown
git add {README,INSTALL,LICENSE,sample-product.c,Makefile}
git status							# files on "stage", still not tracked
git commit
-----

WARNING: If the newly created `.git` folder is somehow corrupted and you have not push your changes *upstream*, then you may have loss your repository

.Cloning a Repo: Two ways

Using `git clone`, easiest and recommended

git clone git://git.openembedded.org/openembedded-core

NOTE: If the above comman hangs, make sure you have the right proxy enviroment variables. For example the bellow settings are the ones by default on
`yctb05`

[source, bash]

NO_PROXY=localhost, 127.0.0.1, 10.0.0.0/8, .jf.intel.com http_proxy=http://proxy.jf.intel.com:911/ ftp_proxy=http://proxy.jf.intel.com:911/ GIT_PROXY_COMMAND=/usr/local/bin/git-proxy gopher_proxy= https_proxy=http://proxy.jf.intel.com:911/ no_proxy=localhost, 127.0.0.1, 10.0.0.0/8, .jf.intel.com

Using `git remote`

mkdir openembedded-core && cd openembedded-core git init git remote add origin git://git.openembedded.org/openembedded-core git remote update

NOTE: When you clone/remote update, you are getting the whole repository on your hard disk (yes, every branch and tag), so what this really means is that
development is not centrallize, it is DISTRIBUTED.

==== Development

.Branching
NOTE: Definitions: A *branch* is an area you can work, no damage done outside. A *tag* is just a human-friendly way to name a specific commit.

git branch # By default, when you clone, a branch is created, called "master" # You should not work on master, unless you own the repo. # So, branch, do not be afraid.

git branch hotfix master # origin is the default name of the remote repository # you got all branches from the latter on your hard disk, so to refer to them using # origin/<branch name>

git branch

git checkout my-fido

vi .. # Edit your files and then stage & commit. # The triad: EDIT & STAGE & COMMIT = ESC

.Merging
NOTE: If branches diverges, merging creates a new commit after the merge, creating non-linear repositories. However, there is something called *rebase*, which is
explained bellow.

[source, bash]

git checkout -b hotfix master # a short-cut for git branch & checkout; # you can branch from any branch/tag shown on git branch -a or git tag

EDIT, STAGE & COMMIT

git checkout master # think of git checkout as the command 'cd'

git merge hotfix # We should not merge local branches into master, but this is just for 'educational' purposes # The merge process may cause 'merge conflics'. There are visual tools to help you with these, but for the moment edit the conflics # and remove them manually

git branch -d hotfix # You can safely remove this branch, because it was merged into master

.Rebase
NOTE: *Rebase* means "place my commits on top"; keeps the repository linear, cleaner, so strongly suggested

[source, bash]

git checkout -b another-hotfix master

EDIT, S…​ & C..

git rebase master # Again, merge conflics could happend on this task

git checkout master # move to master

git merge hotfix # merge. Because hotfix commits are on top of master, merging just moves master linearly, which is call as 'Fast-Forward'

git branch -d hotfix

[[anchor-yp-repositories]]
.Repositories
[options="header"]
|=====================
|Name|Layer(s)|Repo|Mailing List
|bitbake|bitbake|http://git.openembedded.org/bitbake/|bitbake-devel@lists.openembedded.org
|Documentation|documentation|http://git.yoctoproject.org/cgit/cgit.cgi/yocto-docs/|yocto@yoctoproject.org
|Yocto|meta-yocto|http://git.yoctoproject.org/cgit/cgit.cgi/meta-yocto|poky@yoctoproject.org
|OpenEmbedded Core|meta,scripts|http://git.openembedded.org/openembedded-core/|openembedded-core@lists.openembedded.org
|Other layers|meta-*|http://layers.openembedded.org/layerindex/branch/master/layers|Indicated on the README
|=====================


[[anchor-patch-creation]]
How to Create a Patch on the YP
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.Steps
* Clone the corresponding repository (see <<anchor-yp-repositories>>)
IMPORTANT: Do not download tarballs, otherwise you won't have the repository history

git clone git://git.openembedded.org/openembedded-core

* Go the the layer to be patched

cd openembedded-core

* Branch (make sure you are branching from origin/master and you got the latest)

git fetch origin git checkout -b hotfix origin/master

* Generate your commit(s)

vi …​ git status git add file1 file2 git commit -s

NOTE: All commits must be Signed-off-by (-s option to commit above). Check the <<anchor-links,links>> and browse the repo and learn the format from previous commits

[[anchor-patch-submission]]
How to Submit a Patch on the YP
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

There are two ways: 1) pull-request 2) git-send-email

pull-request
^^^^^^^^^^^^

git-send-email
^^^^^^^^^^^^^^

NOTE: you may need to install git-email package through your package manager

* Generate the patch

git format-patch --subject-prefix="OE-core][PATCH" -1

IMPORTANT: Make sure you are using the right prefix


* Send it to the list, i.e. 'openembedded-core@lists.openembedded.org'

git send-email --to=<list> --confirm=always -M <patch created above>

IMPORTANT: Make sure you sending it to the right list
TIP: before sending it, add the parameter --dry-run


[[anchor-post-patch]]
Post-patch submission
~~~~~~~~~~~~~~~~~~~~~

. Once sent, patch should be available on http://patches.openembedded.org/[OE patches]
. If you get feedback, do the proper modifications and create a new commit & patch. This time use `--subject-prefix="OE-core][PATCH vN"` where `N` is the number of
iterations you have had for this patch, i.e. `...][PATCH v2`
. Repet the above steps as neccesary, just make sure N does not tend to infinity...

TIP: In case of any feedback, just reply the email you got with your patch, with a "ping"/reminder


[[anchor-good-os-practices]]
Good Open Source Practices
~~~~~~~~~~~~~~~~~~~~~~~~~~

* Patch Atomicity: When adding multiple new recipes, each recipe should be added in a separate commit.
* Recipe Upgrades (not sure if this really holds now): For upgrades of existing recipes, the previous version should usually be deleted as part of the same commit to add the upgraded version.
* Avoid top-posting on emails (is there a way to do this automatically in every email we respond)


[[anchor-scripts]]
Scripts
~~~~~~

* https://gist.github.com/benjaesq/219a796a73603e6bc95e[prompt.sh]Indicate on your command prompt which branch you are currently on


[[anchor-links]]
Links
~~~~~~~

http://www.openembedded.org/wiki/How_to_submit_a_patch_to_OpenEmbedded[How to Submit a Patch to OE]
http://layers.openembedded.org/layerindex/branch/master/layers/[OE layers]
http://www.openembedded.org/wiki/Commit_Patch_Message_Guidelines[Commit Patch Message Guidelines]
http://git-scm.com[Pro Git book]
https://wiki.yoctoproject.org/collab/New_Employee_Setup_Guide#Development_Machine_Configuration[Development Machine Configuration at Intel]