User Tools

Site Tools



This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
git-tutorial [2017/10/31 17:21]
bp oofem git repo updated to github
git-tutorial [2017/11/01 09:08]
Line 119: Line 119:
 ====== Contributing to OOFEM - Practical workflow ====== ====== Contributing to OOFEM - Practical workflow ======
-Contributing ​to oofem project is different. Typicallyyou don’t have the permissions ​to directly update branches ​on the project reference ​repository ​and you have to pass your contribution(s) to the maintainers in some wayIn OOFEM, these people ('​lieutenants'​) ​are in charge of specific subsystem of the project and they merge in all changes related to that subsystem and push them to the reference (blessed) repository that everyone can clone from again. In general, lieutenants prefer to accept contributed patches via e-mail.+For people without write permissions ​to the GitHub ​oofem repository, the preferred way is to create a pull requests to propose and collaborate ​on changes in repository. ​The changes ​are proposed ​in a separate branch.
-**Before contributing,​ please make sure you have followed ​[[coding-conventions|oofem coding conventions]].**+You can read more about [[https://​​articles/​creating-a-pull-request/|Creating a pull requests on GitHub help pages]].
-Firstyou’ll probably want to clone the main repository, create ​''​featureA''​ branch for the patch or patch series you’re planning ​to contribute, and do your work thereThe sequence looks basically like this:+Typicallyone have to create a fork, or copy, of the repository. Forks let you make changes to project without affecting ​the original repository. You can fetch updates from or submit changes ​to the original repository using pull requests. 
 +  * Read more about [[https://​​articles/​working-with-forks/​|working with forks on GitHub help]] 
 +  * [[https://​​articles/​creating-a-pull-request-from-a-fork/​|How to Create a pull request from a fork]]
-Clone reference ​repository ​from remote server. This creates ​only ''​master''​ branch in you local machine. 'oofem.git' is an arbitrary name of directory+If you have write access to the repository, you can also create branch directly within oofem repository. This should be reserved ​only to agreed, long-term, project-wide branchesFor day-to-day and personal development,​ the forks are recommended
-  ​$ git clone oofem.git +  ​* [[​|How to Create and delete branches within your repository]]
-  $ cd oofem.git+
-Note: when a repository is cloned, git automatically creates a master branch that tracks origin/​master branch, but there is no automatic update (need to use "​pull"​ command) 
-If you already ​have oofem.git directory from previous time, you can update ​''​master'' branch.+After you have created ​pull request, you can ask a specific person to review the changes you've proposed. 
 +In OOFEM, these people ('lieutenants') are in charge of a specific subsystem of the project and they merge in all changes related to that subsystem and push them to the reference (blessed) repository that everyone can clone from again
-   $ (git diff --name-only master origin/​master ​  ​or ​  $git diff master origin/​master) ​ //see the differences between local and remote masters +**Before contributingplease ​make sure you have followed [[coding-conventions|oofem coding conventions]].**
-   $ git checkout master +
-   $ git pull --rebase +
- +
-Normally, we do not want to modify ''​master''​ branch directly. For this reason, we create a new brach ''​featureA''​ for our development,​ which is a copy from an active previous branch ''​master''​ +
-  $ git checkout -b featureA +
-  $ (work) +
- +
-Locally modified files need to be uploaded to local server. Use option ''​-a''​ to upload all changed files which were included in the local repository. A message required on commiting will go also to a remote server. +
- +
-  $ git commit -a +
-  $ (work) +
-  $ git commit -a +
- +
- +
-Now, while you are working hard on your new feature, other developers complete theirs and push their changes to the remote ''​master''​ branch. When you're done with your project, you need to first get the most recent version of the project'​s code. Change to the ''​master''​ and pull out the most recent remote version. +
- +
-  $ git checkout master +
-  $ git pull --rebase +
-   +
-Now, to make merging your code easy, you should rebase your ''​featureA''​. What this does is add all the commits you just pulled in to your ''​featureA''​. Any conflicts that arise will happen in your ''​featureA''​ as well, leaving your master branch clean and in order. +
- +
-  $ git checkout featureA +
-  $ git rebase master +
- +
- +
-:!: **It is stronlgly recommended to use ''​rebase -i''​ to squash your work down to a single commitor rearrange the work in the commits to make the patch easier for the maintainer to review — see Git book for more information about interactive rebasing. +
-** +
- +
-Optionally, your branch can be merged into single ''​master''​ on a local machine and ''​featureA''​ can be deleted +
- +
-  $ git checkout master +
-  $ git merge featureA +
-  $ git branch -D featureA +
- +
-Now you have your commits that you want to send to the maintainers. You use git format-patch to generate the mbox-formatted files that you can e-mail — it turns each commit into an e-mail message with the first line of the commit message as the subject and the rest of the message plus the patch that the commit introduces as the body +
- +
-  $ git format-patch -M origin/​master +
-  0001-add-limit-to-log-function.patch +
-  0002-changed-log-output-to-30-from-25.patch +
- +
-The format-patch command prints out the names of the patch files it creates. The -M switch tells Git to look for renames.  +
-To e-mail this to a maintainers,​ you can either paste the file into your e-mail program or send it via a command-line program.  +
- +
-For those, who have write access to remote server, the local repository can be uploaded to remote server. Without any options, all branches, where local_name=remote_name will be pushed  +
- +
- $ git push +
- +
-To be sure pushing only ''​master''​ branch, use  +
- +
- $ git push origin master+
-===== Maintainers ===== 
-FIXME Here it would be nice to mention all lieutenants,​ with their e-mails. But perhaps better solution would be to create a mailing list, where the patches could be send (this will hide the individual e-mails). Then the work has to be distributed somehow .... Any ideas? 
 ====== Links ====== ====== Links ======
-  * Online version of [[|Git book]]. Higly recommended! +  * Online version of [[|GitHub help]]. Higly recommended! 
-  * Git-SVN ​[[http://​​svn.html|Crash Course]] +  * Online version of [[http://​|Git book]]. Higly recommended! ​
git-tutorial.txt · Last modified: 2017/11/01 09:08 by bp