|
|
| (6 intermediate revisions by 3 users not shown) |
| Line 1: |
Line 1: |
| THIS IS A DRAFT, DO NOT USE! | | {{Out of date|This page that shows up high in search results in 2025 was last updated in 2016 and marked "THIS IS A DRAFT, DO NOT USE!". Instead read '''[[Infrastructure/GitLab]]'''.}} |
|
| |
|
| = Feature Branch Workflow =
| | :''View history if you want to see what this page originally said, but don't bother discussing it.'' |
| | |
| This Git Workflow is the recommended KDE Git Workflow for smaller projects where new features are developed in local and/or remote feature branches before being reviewed and merged back into the master branch.
| |
| | |
| This workflow is designed to be used after initial use of the [[Infrastructure/Git/Simple_Workflow|Simple Workflow]]. It is assumed you have read and mastered the basic concepts as outlined in that Workflow, such as unstaged and staged changes, committing, rebasing and pushing.
| |
| | |
| Note that each module may choose to adopt a more complex workflow, in particular the Integration Branch Workflow, and you should check with your modules maintainers if this is the case.
| |
| | |
| More detailed information can be found on the main [[Infrastructure/Git|KDE Git page]]. More details on the various commands can be found on the [[Infrastructure/Git/Recipes|KDE Git Recipes]] page.
| |
| | |
| == Set-up ==
| |
| | |
| See the [[Infrastructure/Git/Simple_Workflow#Set-up|Simple Workflow Set-up]] section for instructions on configuring Git and Cloning your Repository
| |
| | |
| == Local Feature Development ==
| |
| | |
| By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.
| |
| | |
| === Create a Local Work Branch ===
| |
| | |
| To see what local branches you have:
| |
| | |
| git branch
| |
| | |
| This will initially appear as follows, with the * indicating your current working branch:
| |
| | |
| * master
| |
| | |
| To see all local and remote branches:
| |
| | |
| git branch -a
| |
| | |
| This will initially look something like:
| |
| | |
| * master
| |
| remotes/origin/HEAD -> origin/master
| |
| remotes/origin/KDE/4.5
| |
| remotes/origin/KDE/4.6
| |
| remotes/origin/kdecore/klocale-win
| |
| remotes/origin/kdeui/kdatetimeedit
| |
| | |
| To create a new local branch:
| |
| | |
| git branch <new-branch>
| |
| | |
| Now running <tt>git branch</tt> will show:
| |
| | |
| * master
| |
| my-new-branch
| |
| | |
| To change to the new branch to work on it:
| |
| | |
| git checkout <new-branch>
| |
| | |
| Now running <tt>git branch</tt> will show:
| |
| | |
| master
| |
| * my-new-branch
| |
| | |
| This sequence will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.
| |
| | |
| You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' a remote branch and is recommended for most work branches:
| |
| | |
| git branch --track <local-branch> <remote-branch>
| |
| | |
| For example to develop a new feature called 'bar' based on the central repository master branch:
| |
| | |
| git branch --track new-bar-feature origin/master
| |
| | |
| === Making Changes ===
| |
| | |
| You can now make [[Infrastructure/Git/Simple_Workflow#Making_Local_Changes_and_Commits|local changes and commits]], and [[Infrastructure/Git/Simple_Workflow#Pushing_Your_Changes_To_The_Central_Repository|push them to the central repository]] exactly as described in the [[Infrastructure/Git/Simple_Workflow|Simple Workflow]].
| |
| | |
| Your project may require changes to be reviewed before pushing to the central code repository. All projects on git.kde.org automatically have a [[Infrastructure/Review_Board|Review Board]] group created for them which you can use for this purpose. It is recommended that you use the [[Infrastructure/Review_Board#Using_post-review_to_post_changes_for_review|post-review script]] to automatically generate and upload the diff of your changes.
| |
| | |
| === Deleting Local Branches ===
| |
| | |
| Once you have finished with a local feature branch and pushed all your commits to the central repository you can delete the local branch if you no longer require it.
| |
| | |
| First, you have to change to a different branch:
| |
| | |
| git checkout master
| |
| | |
| Then you can delete the feature branch:
| |
| | |
| git -d <local-branch>
| |
| | |
| == Remote Feature Development ==
| |
| | |
| This example workflow is for working on new features in a feature branch hosted on the central repository.
| |
| | |
| This workflow is recommended for larger features or where there are many developers on a project.
| |
| | |
| The main disadvantage of local feature branch development is no-one else can see your code changes or help you until the finished feature is pushed to the central repository.
| |
| | |
| TODO: Finish this.
| |
| | |
| == Local Bug Fixing ==
| |
| | |
| This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.
| |
| | |
| In Git, stable branches are just regular branches that have special meaning to a project and a possibly a special naming scheme to distinguish them. For example, kdelibs includes the following branches on the central repository:
| |
| | |
| origin/HEAD -> origin/master
| |
| origin/KDE/4.5
| |
| origin/KDE/4.6
| |
| origin/kdecore/klocale-win
| |
| origin/kdeui/kdatetimeedit
| |
| origin/master
| |
| | |
| Here origin/KDE/4.6 is the 4.6 release of kdelibs.
| |
| | |
| Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to push the bug fix to both the stable and unstable branch in the central repository.
| |
| | |
| In the [[Infrastructure/Git/Simple_Workflow#Local_Bug_Fixing|Simple Workflow bug fixing]] section we describe a simple way to perform bug fixes for both stable and unstable branches in the same repository clone.
| |
| | |
| The basic workflow works fine except switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem, but in most cases this constant rebuilding will be a waste of time.
| |
| | |
| One alternative is to have two separate clones using two separate build environments, but this wastes disk space and causes problems with keeping the separate clones in sync.
| |
| | |
| A better alternative is to use the [[Infrastructure/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for the stable and unstable branches using the same repository clone. This depends on you setting different up KDE Environments for the separate builds.
| |
| | |
| TODO: Finish this.
| |
