vcs:gitworkflow

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
vcs:gitworkflow [2017/09/22 13:28] – external edit 127.0.0.1vcs:gitworkflow [2023/08/31 08:55] (current) – Add --atomic flag ilutov
Line 1: Line 1:
 ====== Git Workflow ====== ====== Git Workflow ======
  
-**Also read [[vcs::gitfaq]] and [[http://git.php.net/?p=php-src.git;a=blob;f=README.GIT-RULES;hb=refs/heads/master|README.GIT-RULES]] which have other workflows and PHP git tips.**+**Also read [[vcs::gitfaq]] and [[https://github.com/php/php-src/blob/master/CONTRIBUTING.md|CONTRIBUTING.md]] which have other workflows and PHP git tips.**
  
-Git does not enforce a certain workflow. For php-src we will use a workflow that is described bellow.+Git does not enforce a certain workflow. For php-src we will use a workflow that is described below.
  
 We will use release branches for the php-src.git repository. We will have branches for actively maintained We will use release branches for the php-src.git repository. We will have branches for actively maintained
-versions. For example: **7.0**, **7.1**, **7.2**, and **master** . A patch will be applied to the oldest possible branch. +versions. For example: **7.4**, **8.0**, **8.1** and **master**. A patch will be applied to the oldest possible branch. 
-If the Release Manager of 5.6 accepts the change, commit it to the 5.6 branch. We will use regular merging between the release branches.+If the Release Manager of 7.4 accepts the change, commit it to the 7.4 branch. We will use regular merging between the release branches.
 Bigger features can use feature branches, but developers are encouraged to fork php on github and start implementing the Bigger features can use feature branches, but developers are encouraged to fork php on github and start implementing the
 feature there on the respective branch. feature there on the respective branch.
Line 15: Line 15:
  
 Core developers that have access to the php-src.git repository apply changes to the lower possible branch and then Core developers that have access to the php-src.git repository apply changes to the lower possible branch and then
-merge the change upwards. The repository is prepared in a way, that only new changes will be merged upwards. E.g. Git will not attempt +merge the change upwards. The repository is prepared in a way, that only new changes will be merged upwards. E.g. Git will not attempt to synchronize the whole 5.6 and 7.0 branch. //Only your commit will be merged//.
-to synchronize the whole 5.6 and 7.0 branch. //Only your commit will be merged//.+
  
 Here is a visualization of a standard //Patch Workflow// Here is a visualization of a standard //Patch Workflow//
Line 24: Line 23:
 Let's go through the process of setting it up and doing the merges. Let's go through the process of setting it up and doing the merges.
  
-==== Developing Patches Yourself ====+==== Initial Setup ====
  
-The initial setup: +  $ git clone git@github.com:php/php-src.git 
- +  $ cd php-src 
-  $ git clone git@git.php.net:php-src.git+  $ git config merge.NEWS.name "Keep the NEWS file" 
 +  $ git config merge.NEWS.driver 'touch %A' 
 +  $ git config merge.log true
      
 Please refer to [[gitfaq|Git FAQ]] for alternative cloning methods via HTTP or the Git Protocol. Please refer to [[gitfaq|Git FAQ]] for alternative cloning methods via HTTP or the Git Protocol.
  
-Then: +==== Patching a release branch ====
-   +
-  $ cd php-src +
-  $ git checkout -b PHP-7.0 origin/PHP-7.0 +
-  $ git checkout -b PHP-7.1 origin/PHP-7.1 +
-  $ git checkout -b PHP-7.2 origin/PHP-7.2+
  
-Patching the PHP 7.0 branch+Patching the PHP 7.4 branch:
  
-  $ git checkout PHP-7.0+  $ git checkout PHP-7.4
   ... hack hack ...   ... hack hack ...
   $ git commit <changed files>   $ git commit <changed files>
   ... USE A GOOD COMMIT MESSAGE ...   ... USE A GOOD COMMIT MESSAGE ...
   ... run tests ...   ... run tests ...
-  $ git checkout PHP-7.1 +  $ git checkout PHP-8.0 
-  $ git merge --no-ff --log PHP-7.0+  $ git merge PHP-7.4
   ... run tests ...   ... run tests ...
-  $ git checkout PHP-7.2 +  $ git checkout PHP-8.1 
-  $ git merge --no-ff --log PHP-7.1+  $ git merge PHP-8.0 
 +  ... run tests ... 
 +  $ git checkout PHP-8.2 
 +  $ git merge PHP-8.1
   ... run tests ...   ... run tests ...
   $ git checkout master   $ git checkout master
-  $ git merge --no-ff --log PHP-7.2+  $ git merge PHP-8.2
   ... run tests ...   ... run tests ...
   $ gitk master   $ gitk master
   ... review the merges ...   ... review the merges ...
-  $ git push origin+  $ git push --atomic origin PHP-7.4 PHP-8.0 PHP-8.1 PHP-8.2 master
   ... push to the official repository ...   ... push to the official repository ...
      
 When you use 'git push --all origin', make sure there are not any unwanted branches in local repository or set branch.<name>.remote properly via git-config. When you use 'git push --all origin', make sure there are not any unwanted branches in local repository or set branch.<name>.remote properly via git-config.
 +
 +Use the '--atomic' flag to ensure that no refs are updated if the update of any of them fails.
  
 ==== Reviewing and closing pull requests ==== ==== Reviewing and closing pull requests ====
 +
 Johannes has created a [[http://qa.php.net/pulls | tool]] to easily close pull requests. It requires a valid PHP account. Johannes has created a [[http://qa.php.net/pulls | tool]] to easily close pull requests. It requires a valid PHP account.
 +
 +You can also include ''Closes GH-NNNN.'' in the commit message to automatically close a pull request.
  
 ==== Merge a pull request ==== ==== Merge a pull request ====
  
-In case you want to merge a pull request that someone else opened on github into the 5.6 branch, use the following +Preferably, pull requests should not be merged, but rebased onto the target branch. Because it is common that PRs need to be applied to a different branch than the one it was originally created for, the easiest way to do this is using ''git am''. Patches for use by ''git am'' can be obtained by appending ''.patch'' to the GitHub URL. For example, to apply pull request #1234 onto branch PHP-7.4:
-commands:+
  
-  $ git checkout PHP-7.0 +  $ git checkout PHP-7.4 
-  $ git fetch git://github.com/php/php-src pull/23/head:pull-request/23 +  $ wget https://github.com/php/php-src/pull/1234.patch 
-  $ git log -p pull-request/23+  $ git am -3 1234.patch 
 +  $ git commit --am # Adjust commit message to add "Closes GH-1234."
   ... REVIEW IT ...   ... REVIEW IT ...
-  $ git merge --no-ff pull-request/23  
-  .. Merge it, add a GOOD commit message ... 
   $ make test                     $ make test                  
-  .. you better don't forget that ... +  .. you better not forget that ... 
-  $ git checkout PHP-7.1 +  $ git checkout PHP-8.0 
-  $ git merge --no-ff --log PHP-7.0+  $ git merge PHP-7.4
   $ make test   $ make test
-  $ git checkout PHP-7.2 +  $ git checkout PHP-8.1 
-  $ git merge --no-ff --log PHP-7.1+  $ git merge PHP-8.0
   $ make test   $ make test
   $ git checkout master   $ git checkout master
-  $ git merge --no-ff --log PHP-7.2+  $ git merge PHP-8.1
   $ make test   $ make test
-  $ git push origin master      +  $ git push origin PHP-7.4 PHP-8.0 PHP-8.1 master      
-  ... everything okay? good, let's push it ...+ 
 +Additionally, the history of pull requests often requires cleanup. For most pull requests, all commits can be squashed into one.
      
 === Note about moving patches from a newer branch === === Note about moving patches from a newer branch ===
-In case you have to merge a commit from a higher branch. E.g from PHP-7.2 into PHP-7.1 make sure you still merge upwards +In case you have to merge a commit from a higher branch. E.g from PHP-8.1 into PHP-7.4 make sure you still merge upwards 
-as described above afterwards:+as described above afterward:
  
-  $ git checkout PHP-7.1+  $ git checkout PHP-7.4
   $ git cherry-pick <SHA1-OF-PATCH-TO-MOVE>   $ git cherry-pick <SHA1-OF-PATCH-TO-MOVE>
-  $ git checkout PHP-7.2 +  $ git checkout PHP-8.0 
-  $ git merge --no-ff --log PHP-7.1+  $ git merge PHP-7.4 
 +  $ git checkout PHP-8.1 
 +  $ git merge PHP-8.0
   $ git checkout master   $ git checkout master
-  $ git merge --no-ff --log PHP-7.2+  $ git merge PHP-8.1
   $ git push   $ git push
  
-**TL;DR: Always try to merge PHP-7.0 into PHP-7.1, then PHP-7.2, and then into master. If you are unsure ask dsp**+**TL;DR: Always try to merge PHP-7.4 into PHP-8.0, then PHP-8.1, and then into master.**
  
 ==== Merge patches received per mail ==== ==== Merge patches received per mail ====
Line 112: Line 117:
  
 ==== Updating NEWS ==== ==== Updating NEWS ====
-If a patch is related to a bug ticket or is worth it a mention otherwise, the NEWS file need to be updated to reflect the change done. The NEWS entry has to be added manually in every branch, where the patch is applied. Whereby NEWS in master are being updated only for master only patches. More info is available in the corresponding section in [[http://git.php.net/?p=php-src.git;a=blob;f=README.GIT-RULES;hb=refs/heads/master|README.GIT-RULES]].+If a patch is related to a bug ticket or is worth it a mention otherwise, the NEWS file needs to be updated to reflect the change done. The NEWS entry has to be added manually in every branch, where the patch is applied. Whereby NEWS in master is being updated only for master only patches. More info is available in the corresponding section in [[http://git.php.net/?p=php-src.git;a=blob;f=README.GIT-RULES;hb=refs/heads/master|README.GIT-RULES]].
  
  
 ===== Feature Workflow for Core Developers ===== ===== Feature Workflow for Core Developers =====
-Feature development can take a lot of time. You might not know to which branch the feature will be commited or you want to combine commits before pushing the final bits. Therefore it is adviced to use a separate branch while you develop your feature. This approach is called a feature branch:+Feature development can take a lot of time. You might not know to which branch the feature will be committed or you want to combine commits before pushing the final bits. Therefore it is advised to use a separate branch while you develop your feature. This approach is called a feature branch:
  
 {{:vcs:php-merge-4.png?direct|}} {{:vcs:php-merge-4.png?direct|}}
  
-The workflows aims for a feature to be included into the master branch. So we branch of the master branch first:+The workflows aim for a feature to be included into the master branch. So we branch of the master branch first:
  
   $ git checkout -b feature/featurename master   $ git checkout -b feature/featurename master
Line 131: Line 136:
   $ git rebase master   $ git rebase master
      
-Once the feature is accepted merge it into master:+Once the feature is accepted, make sure your branch is up to date (see above) and then fast-forward merge it into master:
  
   $ git checkout master   $ git checkout master
-  $ git merge --no-ff --log feature/featurename+  $ git merge --ff-only feature/featurename
  
 ===== Workflow for external contributors ===== ===== Workflow for external contributors =====
Line 146: Line 151:
   $ git remote add upstream https://github.com/php/php-src.git   $ git remote add upstream https://github.com/php/php-src.git
   $ git fetch upstream   $ git fetch upstream
-  $ git branch --track issue-<issuenr> origin/PHP-7.1   (or use origin/master)+  $ git branch --track issue-<issuenr> origin/PHP-7.4   (or use origin/master)
   $ git checkout issue-<issuenr>    $ git checkout issue-<issuenr> 
  
 Do your stuff and add/commit your work accordingly. Do your stuff and add/commit your work accordingly.
 Optionally, you can rebase your work: Optionally, you can rebase your work:
-  $ git pull --rebase upstream PHP-7.1    (or use upstream master)+  $ git pull --rebase upstream PHP-7.4    (or use upstream master)
 Push your branch to your github repository: Push your branch to your github repository:
   $ git push origin issue-<issuenr>   $ git push origin issue-<issuenr>
Line 168: Line 173:
 If you prefer mail use git format-patch and send the created patch using mail: If you prefer mail use git format-patch and send the created patch using mail:
  
-  $ git format-patch origin/PHP-7.1+  $ git format-patch origin/PHP-7.4
   0001-bug-fix.patch   0001-bug-fix.patch
   ...    ... 
Line 177: Line 182:
      
 If you don't have an issue-number, just make the branch name self-descriptive (ie: "json_encoding_fix" instead of "branch-001").  If you don't have an issue-number, just make the branch name self-descriptive (ie: "json_encoding_fix" instead of "branch-001"). 
-As stated before, branch from the lowest version possible. When you want to create a patch that needs to be incorporated into several branches, like a security fix for something in PHP-5.5, PHP-5.6, PHP-7.0 and the master, make sure you checkout a branch from PHP-5.5. You don't need to create separate pull requests for PHP-5.6, PHP-7.0 and master.+As stated before, branch from the lowest version possible. When you want to create a patch that needs to be incorporated into several branches, like a security fix for something in PHP-7.4, PHP-8.0, PHP-8.1, and the master, make sure you checkout a branch from PHP-7.4. You don't need to create separate pull requests for PHP-7.4, PHP-8.0, PHP-8.1, and master.
  
  
vcs/gitworkflow.1506086901.txt.gz · Last modified: 2017/09/22 13:28 by 127.0.0.1

Page Tools