= WorkingGuideLines =

This document represents Guidelines for our workflows. Also see [wiki:/Hacking Hacking] for coding guidelines and ReleaseGuidelines for understanding how we make releases.

== Workflow ==
It is divided into several parts:
 * creating ticket
 * creating branches
 * reviewing patch
 * applying patch
 * code indentation

== Examine repo ==

update local repo cache
{{{
git remote prune origin
}}}

get list of branches
{{{
git branch -r
}}}

== Creating Ticket Guidelines ==
Here are some useful tips for creating tickets:
 * If some mc developer want to be responsible for a ticket, he set yourself as owner and status to accepted. He should to have a look if this ticket already contains a patch. Then he creates a remote branch for working in. 
 * Bugfixes are allowed to go to the latest stable branch and new features and restructuring are allowed only for full releases. Stable branches are called: mc-X.Y (e.g. mc-4.6). Please also choose the correct milestone for this ticket: for a bugfix choose the latest milestone from the stable branch (e.g. 4.6.2), and for a new feature choose the default (which is atm 4.7). 
 * Please note that Changelog is frozen and mustn't be modified. All the modifications should be drawn in the commit message.
 
== Direct commits ==
Next stuff may be directly applied into 'master' branch:
 * translations
 * documentation (doc/*)
 * skins (misc/skins/*); except defailt.ini skin
 * keymaps (misc/mc.keymap.*); except mc.default.keymap and mc.emacs.keymap
 * editor's syntax color highlight files

== Creating branches ==

Simple example to create branch:
{{{
  $ git checkout master
  $ git pull                           // pull last changes
  $ git checkout -b 123_branch_name    // create local branch
}}}

Add changes and commit:
{{{
  $ git add file.1 file.2 file.3          // add files to commit 
  $ git commit -s                         // commit changes
  $ git push -u origin 123_branch_name    // pub branch
}}}

 * Each branch should follow some easy naming rules: XYZ_<something_descriptive_here>. XYZ is here the ID of the ticket. The patch is not directly applied to the parent branch as we would like to review it beforehand.
 * Each branch is created on the top of the other one. If this is a bugfix you should use stable branch, if not then master branch or branch where this bug (e.g for a bugfix create a branch on top of mc-4.6). Please create your branches upon a last master/another_parent_branch, it will simplify future merge process. 

 * After creating the branch, you shouldn't forget to set "Branch state" field to the "on review" state if it ready for review, since now your ticket will pop up on [http://www.midnight-commander.org/report/9 this page] and can be reviewed by other developers. Also don't forget add link to changeset in ticket it should speed up review process. 
 
Standard format is:
{{{
branch: branch_name (parent: parent_branch_name)
changeset:changeset_hash
}}}

== Reviewing Ticket Guidelines ==

As there are some guidelines for creating tickets, there are of course also some guidelines for reviewing tickets.
 * Tickets which needs a review are located here: http://www.midnight-commander.org/report/9
 * You can directly test the patch in git, simply checkout this branch and test and review it (or test merge with current local master branch or another branch which should be merged for check to conflicts).

{{{
 $ # simple test case:
 $ git checkout origin/123_branch_name
 $ <build and test>
}}}
{{{
 $ # best test case:
 $ git checkout master
 $ git reset --hard origin/master
 $ git pull
 $ git merge --log --no-ff --no-edit origin/123_branch_name
 $ <build and test>
}}}

 * This should be reviewed when looking at a patch:
   * is the patch straightforward or a somehow hackish fix for an issue?
   * is the patch looking well? (see [wiki:Hacking Coding Guidelines])
   * is the patch doing what it should?
   * the patch mustn't introduce new bugs!
 * If you're fine with this patch, add your login to the "Votes for changeset" field, else if the patch is not okay, remove votes and set the "Branch state" field to "on rework" as keyword and describe whats problems with this patch.
 * Currently one vote are needed in order to get a patch into the parent branch. If you are successfully reviewed this patch then you also set the "Branch state" field to "approved".

== Applying Patch Guidelines ==

The last part is about applying a accepted patch to it's parent one
 * The owner of the ticket will now merge the fix (located in the XXY_<something_descriptive_here> branch) into the parent branch. For this he eventually has to rebase this branch on the parent one. If the fix was a bugfix, then the fix would be now in the mc-X.Y branch. 
 * In this case the fix is still missing in the master branch. Please '''NEVER(!!!)''' rebase the stable release branch mc-X.Y in order to get a fix merged. If the merge failed because of conflicts fix them manually. 
 * Don't forget add correct commit message. Standard format is:
 {{{
    Ticket #<ticket_number>: ticket summary

    changeset description, e.g.
    add: some description
    fix: some description
 }}}
 Some examples to merge your changes.
 Rebase to merge commits in one:
{{{
 # in you working branch
 $ git rebase -i HEAD~4  // if you add 4 commit (you can check it with 'git log')
}}}
  Preparing to merge with master:
{{{
 $ git checkout master
 $ git pull                         // don't forget update your master
 $ git checkout 123_branch_name     // checkout your working branch
 $ git rebase origin/master         // rebase you working branch to "master"
 $ git checkout master              // againt to master
}}}
  Merge process:
{{{
 $ git merge --log --no-ff --no-edit 123_branch_name  // merge "123_branch_name" to "master"
}}}
   --log option adds the merged patches list to the commit. --no-ff option allows create the merge commit in case where branch isn't child branch for current head, it should simplify understanding commit relation (use --no-ff option even you have one commit in branch). --no-edit option is used to accept the auto-generated message.

 Now you ready to update master branch on server: 
{{{
 $ git push origin master           // update central repository
 $ git push origin :123_branch_name // delete bracnh 123_branch_name on server
 $ git branch -d 123_branch_name    // delete local branch 123_branch_name on your host
}}}

 If you have any problems in merge process you should fix it manually and continue merge process, but try to check merge process before start to push or you can break branch.

 * Now you can close the ticket and the ticket will change into the testing state, and rewrite 'Votes for changeset' to 'committed-master' text. Also, change value of 'Branch state' field to 'merged'. In ticket comment you must describe how get summary patch. For example:
{{{
fixed: 111111111111111^...222222222222222 # for multipatch
fixed: 111111111111111                    # for one changeset
}}}
 where 111111111111111 - first commit; 222222222222222 - last commit
Or you may describe just merge commit like:
{{{
Merge changeset:111111111111111
}}}

 * Update current NEWS page. Add a one-line short description and ticket number to a proper part of NEWS page
 * Change ticket state from 'testing' to 'close'

If you are unfamiliar with git, please have a look before working in our GitGuideLines. 

Release process is described [wiki:ReleaseGuidelines here].

{{{#!comment

== Backporting to stable branch ==

Sometimes the change needs to backported to latest stable branch (like '''4.8.1-stable''').
Such changes are marked as '''keywords: stable-candidate'''.

In order to merge them you need to:

 * git checkout 4.8.1-stable
 * git cherry-pick commit-id '''every needed changeset'''
 * git push origin 4.8.1-stable
 * change bug status accordingly:

     Drop '''keywords: stable candidate''' and add'''committed-stable''' to '''Votes for changeset:'''.
     {{{
     fixed: 111111111111111^...222222222222222 # for multipatch
     fixed: 111111111111111                    # for one changeset
     }}}

}}}