GitForLunarDevs

From Lunar Linux
(Difference between revisions)
Jump to: navigation, search
(→Tracking a Lunar developer's moonbase repository)
(Rewritten to the new github workflow)
 
(One intermediate revision by one user not shown)
Line 1: Line 1:
−
=== Introduction ===
+
== GITHUB work flow ==
 +
Requirements a github account and a mindset to use git and github.
 +
To be able to push changes to github it is recommended by github to use https. But some prefer using ssh authentication keys. See https://help.github.com/articles/generating-ssh-keys
 +
Have your git config setup correct with your ''user.name'' and ''user.email''
 +
git config --global user.name "John Doe"
 +
git config --global user.name "john@doe.net"
  
−
This is a skeleton page based on a discussion with Ratler on #lunar. Git can be easier than the man pages would suggest as long as someone shows you the way.
+
=== Personal repo to work in ===
 +
To be able to send pull requests you need a personal repo on github which is a fork of the repo you want to work on.
  
−
The page name is a bit naff - how about [[Git 101 for Lunar Developers]] or [[Sharing Git Repositories with Lunar Developers]]? Other ideas?
+
On github navigate to https://github.com/lunar-linux and select the repo you wan to work on. click on the fork button near top right.
 +
Now you have your personal repo in github. Next step is to create a clone the repo to you pc. On github select your repo and you can see the pull url you need to use to have read+write access
  
−
Some git basics are also described in [[Module Submission for developers]].
+
git clone git@github.com/<username>/<reponame>
  
−
Please feel free to add comments/corrections both here and there - engelsman
+
For more information see https://help.github.com/articles/fork-a-repo
  
−
=== Creating a local copy of the central moonbase repository ===
+
'''note:''' all the next command assume you are in your local repo directory.
  
−
Git convention requires user name and e-mail address to appear in commit messages, etc. Note that the first two commands set these for all your repositories.
+
This repo is up to date with lunar-linux repo only because you just forked it. So the next step is to setup a upstream branch to help with keeping your repo up to date.
  
−
  satellite$ git config --global user.name "Full Name"
+
  git remote add upstream git://github.com/lunar-linux/<reponame>
−
  satellite$  git config --global user.email "username@domain.name"
+
git checkout -b upstream_master upstream/master
−
  satellite$  git clone git://lunar-linux.org/lunar/moonbase.git
+
  
−
If you are already a true Lunar developer, rather than an enthusiastic helper, you will need to do things slightly differently so that you can propagate your changes back to the central moonbase repository using your Lunar username and password ''[*]'':
+
'''note:''' with '''git checkout''' you can switch between branches. So, you'll end up in the ''upstream_master'' branch. To switch back to master: '''git checkout master'''
  
−
satellite$  git config --global user.name "Full Name"
+
=== Keeping your personal repo up to date ===
−
satellite$  git config --global user.email "username@lunar-linux.org"
+
After some time commits will have been push to lunar-linux/<reponame> and you want to have them in you repo too. This is where the ''upstream_master'' branch comes in useful.
−
satellite$  git clone ssh://username@lunar-linux.org/var/git/lunar/moonbase.git
+
  
−
''[*] Or is there a better way for setting the ssh username after the initial 'git clone git://...' ?''
+
git checkout upstream_master
 +
git pull
  
−
=== Tracking a Lunar developer's moonbase repository ===
+
'''note:''' In this guide there are a lot of '''git checkout''' <branchname> this it not required if you are already in that branch.
  
−
Some developers have made their copies of their personal repositories, with branches, available at a central URL. ''[How?]'' If you wanted to access florin's repository, for example, you would first have to tell your own moonbase repository about it:
+
'''note:''' Git could complain it you try to switch to another branch if you have local modifications. If you are switching temporarily you can use git stash to store your changes.
  
−
  satellite$ cd moonbase.git  
+
  git stash
−
  satellite$ git remote add florin git://foo-projects.org/florin/moonbase.git
+
  <...>
−
  satellite$ git fetch florin
+
git checkout <WIP branch>
 +
  git stash pop
  
−
=== Creating a local branch copy of a Lunar developer's branch ===
+
Now that your ''upstream_master'' is up to date you need to get these changes in your other branches. That would be at least ''master''. But you can repeat these instructions for every branch you have. Just replace ''master'' with <branchname> and optionally replace ''upstream_master'' with ''master''.
  
−
  satellite$ cd moonbase.git
+
  git checkout master
−
  satellite$ git branch -a              # should show remote/*/* branches
+
  git merge upstream_master
−
  satellite$  git checkout -b florin remotes/florin/florin
+
  
−
If you look in .git/config you should now see:
+
Now you have this locally you can push this to you personal github.
−
# You have a new remote section pointing at florin's url;
+
−
# You have a new branch named florin that refer to refs/heads/florin.  
+
  
−
=== Copying/updating files from a remote Lunar developer's branch ===
+
git checkout master
 +
git push
  
−
  satellite$  cd moonbase.git
+
=== Working with branches ===
−
  satellite$  git checkout florin
+
For the pull requests it is easier if you work with a concept called feature branches. In this concept you don't make changes directly into ''master'', but rather you create a branch and make your changes there. These changes can contain one or more commits. Unless you work with local only branches you won't merge these branches back into ''master'' yourself. These branches will be merged back into ''master'' when they are pulled into lunar-linux/<repo> and you update your personal repo.
−
  satellite$  git pull                  
+
  
−
=== Adding a new branch from a remote Lunar developer's repository ===
+
lunar-linux master:  --- A ---- D --- [BC]M --- E ------------
 +
                          \          /          \
 +
personal dev branch:      \  B --- C            \
 +
                            \ /                    \
 +
local master:        ------ [A] ------------------ [BDCME] ---
  
−
  satellite$  cd moonbase,git
+
A-E are normal commits.
−
  satellite$  git checkout florin
+
M is a merge commit.
−
  satellite$  git remote update florin   
+
Commits between [] is only pulled objects. This doesn't change these commits.
−
  satellite$  git branch -a              # should now show new 'xyz' branch
+
−
  satellite$  git checkout -b florin_xyz remotes/florin/xyz
+
  
−
=== Using your moonbase.git with the lunar tools ===
+
'''note:''' This means you can have multiple branches in parallel with all unrelated changes. Sometimes you need to have an extra local branch to merge multiple branches in to test some interactions. Since local branches can just be deleted with no fuzz, this can save you from polluting your ''master'' branch.
  
−
You can configure the package management tools to work with your moonbase.git instead of /var/lib/lunar/moonbase by setting an environment variable:
+
'''note:''' One feature branch doesn't mean one module change. This could contain multiple modules. These module changes are mostly related. Like changes to all dependencies when you bump a module.
  
−
  satellite$  lunar set MOONBASE /path/to/moonbase.git
+
=== Creating a development branch ===
 +
There are two types of development branches. Local and remote branches. Local branches only exist in your local repo. These are just for you and you can handle them as you like. Remote branches are branches on your personal github. These branches are public and might be used by others. This has some limitations but that is out of the scope of this guide.
  
−
The package management tools can't auto-detect that you are using a moonbase.git, so if you want to work with your moonbase.git, you will need to change your working habits slightly:
+
To create a remote branch you must first create it locally. It is most common to start a branch from your up to date local ''master''.
  
−
* you need to run '''git pull''' in moonbase.git instead of '''lin moonbase''' to download a new version;
+
git checkout master
−
* '''lunar update''' won't work, so you need to run '''git pull ; lunar renew''' in moonbase.git;
+
git checkout -b <branchname>
−
* you shouldn't have a '''zlocal''' directory in moonbase.git, but you can have a '''zlocal''' branch instead
+
  
−
If at any point you need to go back to using the standard non-git moonbase, simply reset the environment variable:
+
Now you end up in you new branch. Make you changes commit them. Make some more commits, maybe.
 +
Now you want your local branch to be on your personal github for the first time for this branch.
  
−
  satellite$ lunar set MOONBASE /var/lib/lunar/moonbase
+
  git checkout <branchname>
−
  satellite$ lin moonbase
+
  git push --set-upstream origin <local-branchname>:<remote-branchname>
  
−
Depending on your workflow, or your level of expertise and confidence with git, you may find it easier or safer to maintain a hybrid system where you use moonbase.git to share test versions with other developers, but keep the standard "vanilla" moonbase. Don't forget that you can always restore a "vanilla" moonbase at any time by running '''lin moonbase'''. If you wait an hour, there might even be updated modules...
+
'''note:''' In many cases you want the local and remote branch name to be the same.
 +
 
 +
On the remote branch you can send a pull request or others can see what you have done so far.
 +
If your branch is not complete and you made some extra commits on the branch in your local repo. You want to push these changes to your personal github too.
 +
 
 +
git checkout <branchname>
 +
git push
 +
 
 +
=== Working with pull requests ===
 +
It is preferred to send pull request even if you have access to lunar-linux/<repo>. By sending a pull request there is another developer looking at your changes. And if you have some doubts you can add a comment to the pull request.
 +
 
 +
There is no point in sending pull requests is you are going to accept them your self. This will only generate extra noise. For small changes you can omit a pull request. For bigger changes let another developer pull in your request.
 +
 
 +
=== Sending a pull request ===
 +
The easiest way to set a pull request in github is using feature branches. On github in you personal repo. Select the branch you want. And click on the pull request button on the top right.
 +
You will be prompted with a form and some fields might already be filled. You can add some extra description if care needs to be taken for the merge for example.
 +
With the commits and changes button you can see what your pull request will contain.
 +
When you're ready click the send pull request button on the bottom right.
 +
For more information see https://help.github.com/articles/using-pull-requests
 +
 
 +
Now wait for the pull request to be merged into lunar-linux/<repo> or be rejected.
 +
 
 +
=== Removing a development branch ===
 +
When you are done with a branch. It was pulled into lunar-linux/<repo> or you discontinued the feature. You want to delete the branch.
 +
To delete a remote branch you need to push the branch with a : in front if it's name.
 +
 
 +
git push origin :<branchname>
 +
 
 +
'''note:''' If a request is successfully pulled github will provide a button at the bottom of the pull request to delete your remove branch.
 +
 
 +
After removing a remote branch the local branch still exists. If you are also done with you local branch you can delete it too.
 +
 
 +
git branch -d <branchname>
 +
 
 +
=== What branches do I have? ===
 +
You can see all your remote branches on github. You can also use you local git to list them.
 +
 
 +
Show your local branches.
 +
 
 +
git branch
 +
 
 +
Show your remote branches.
 +
 
 +
git branch -r
 +
 
 +
=== Reference ===
 +
* https://help.github.com/articles/fork-a-repo
 +
* https://help.github.com/articles/using-pull-requests

Latest revision as of 22:54, 9 June 2013

Contents

GITHUB work flow

Requirements a github account and a mindset to use git and github. To be able to push changes to github it is recommended by github to use https. But some prefer using ssh authentication keys. See https://help.github.com/articles/generating-ssh-keys Have your git config setup correct with your user.name and user.email 

git config --global user.name "John Doe"
git config --global user.name "john@doe.net"

Personal repo to work in

To be able to send pull requests you need a personal repo on github which is a fork of the repo you want to work on.

On github navigate to https://github.com/lunar-linux and select the repo you wan to work on. click on the fork button near top right. Now you have your personal repo in github. Next step is to create a clone the repo to you pc. On github select your repo and you can see the pull url you need to use to have read+write access 

git clone git@github.com/<username>/<reponame>

For more information see https://help.github.com/articles/fork-a-repo

note: all the next command assume you are in your local repo directory.

This repo is up to date with lunar-linux repo only because you just forked it. So the next step is to setup a upstream branch to help with keeping your repo up to date. 

git remote add upstream git://github.com/lunar-linux/<reponame>
git checkout -b upstream_master upstream/master

note: with git checkout you can switch between branches. So, you'll end up in the upstream_master branch. To switch back to master: git checkout master

Keeping your personal repo up to date

After some time commits will have been push to lunar-linux/<reponame> and you want to have them in you repo too. This is where the upstream_master branch comes in useful. 

git checkout upstream_master
git pull

note: In this guide there are a lot of git checkout <branchname> this it not required if you are already in that branch.

note: Git could complain it you try to switch to another branch if you have local modifications. If you are switching temporarily you can use git stash to store your changes. 

git stash
<...>
git checkout <WIP branch>
git stash pop

Now that your upstream_master is up to date you need to get these changes in your other branches. That would be at least master. But you can repeat these instructions for every branch you have. Just replace master with <branchname> and optionally replace upstream_master with master. 

git checkout master
git merge upstream_master

Now you have this locally you can push this to you personal github. 

git checkout master
git push

Working with branches

For the pull requests it is easier if you work with a concept called feature branches. In this concept you don't make changes directly into master, but rather you create a branch and make your changes there. These changes can contain one or more commits. Unless you work with local only branches you won't merge these branches back into master yourself. These branches will be merged back into master when they are pulled into lunar-linux/<repo> and you update your personal repo. 

lunar-linux master:  --- A ---- D --- [BC]M --- E ------------
                          \           /          \
personal dev branch:       \   B --- C            \
                            \ /                    \
local master:        ------ [A] ------------------ [BDCME] ---

A-E are normal commits. M is a merge commit. Commits between [] is only pulled objects. This doesn't change these commits.

note: This means you can have multiple branches in parallel with all unrelated changes. Sometimes you need to have an extra local branch to merge multiple branches in to test some interactions. Since local branches can just be deleted with no fuzz, this can save you from polluting your master branch.

note: One feature branch doesn't mean one module change. This could contain multiple modules. These module changes are mostly related. Like changes to all dependencies when you bump a module.

Creating a development branch

There are two types of development branches. Local and remote branches. Local branches only exist in your local repo. These are just for you and you can handle them as you like. Remote branches are branches on your personal github. These branches are public and might be used by others. This has some limitations but that is out of the scope of this guide.

To create a remote branch you must first create it locally. It is most common to start a branch from your up to date local master. 

git checkout master
git checkout -b <branchname>

Now you end up in you new branch. Make you changes commit them. Make some more commits, maybe. Now you want your local branch to be on your personal github for the first time for this branch. 

git checkout <branchname>
git push --set-upstream origin <local-branchname>:<remote-branchname>

note: In many cases you want the local and remote branch name to be the same.

On the remote branch you can send a pull request or others can see what you have done so far. If your branch is not complete and you made some extra commits on the branch in your local repo. You want to push these changes to your personal github too. 

git checkout <branchname>
git push

Working with pull requests

It is preferred to send pull request even if you have access to lunar-linux/<repo>. By sending a pull request there is another developer looking at your changes. And if you have some doubts you can add a comment to the pull request.

There is no point in sending pull requests is you are going to accept them your self. This will only generate extra noise. For small changes you can omit a pull request. For bigger changes let another developer pull in your request.

Sending a pull request

The easiest way to set a pull request in github is using feature branches. On github in you personal repo. Select the branch you want. And click on the pull request button on the top right. You will be prompted with a form and some fields might already be filled. You can add some extra description if care needs to be taken for the merge for example. With the commits and changes button you can see what your pull request will contain. When you're ready click the send pull request button on the bottom right. For more information see https://help.github.com/articles/using-pull-requests

Now wait for the pull request to be merged into lunar-linux/<repo> or be rejected.

Removing a development branch

When you are done with a branch. It was pulled into lunar-linux/<repo> or you discontinued the feature. You want to delete the branch. To delete a remote branch you need to push the branch with a : in front if it's name. 

git push origin :<branchname>

note: If a request is successfully pulled github will provide a button at the bottom of the pull request to delete your remove branch.

After removing a remote branch the local branch still exists. If you are also done with you local branch you can delete it too. 

git branch -d <branchname>

What branches do I have?

You can see all your remote branches on github. You can also use you local git to list them.

Show your local branches. 

git branch

Show your remote branches. 

git branch -r

Reference

Retrieved from "http://doc.lunar-linux.org/index.php?title=GitForLunarDevs&oldid=3462"
Personal tools
Namespaces
Variants
Actions
Wiki Navigation
Project Sites
Toolbox