gistfile1.txt

== Patching in the YP

. <<anchor-git-basics,Basics>> Git commands 
. Table of YP's <<anchor-yp-repositories, Repositories>>
. Patch's <<anchor-patch-creation,creation>> 
. Patch's <<anchor-patch-submission,submission>>
. <<anchor-post-patch, Post-patch>> submission
. <<anchor-good-os-practices,Good OpenSource practices>>
. <<anchor-scripts, Scritps>>
. <<anchor-links, Links>>

[[anchor-git-basics]]
=== Git basics

==== Configuration

---------------------------------------------------------------------
git config --global user.email "[email protected]"
git config --global user.name "Your Name"
git config --global core.editor emacs
git config --global sendemail.from "[email protected]"
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/|[email protected]
|Documentation|documentation|http://git.yoctoproject.org/cgit/cgit.cgi/yocto-docs/|[email protected]
|Yocto|meta-yocto|http://git.yoctoproject.org/cgit/cgit.cgi/meta-yocto|[email protected]
|OpenEmbedded Core|meta,scripts|http://git.openembedded.org/openembedded-core/|[email protected]
|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. '[email protected]'

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