WWW-www.enlightenment.org pushed a commit to branch master. http://git.enlightenment.org/website/www-content.git/commit/?id=98f4e273e29619fced2c2ce80fd5a7ba49fe6382
commit 98f4e273e29619fced2c2ce80fd5a7ba49fe6382 Author: Gareth Halfacree <[email protected]> Date: Fri Nov 3 08:17:33 2017 -0700 Wiki page git-guide.md changed with summary [created] by Gareth Halfacree --- pages/contrib/devs/git-guide.md.txt | 314 ++++++++++++++++++++++++++++++++++++ 1 file changed, 314 insertions(+) diff --git a/pages/contrib/devs/git-guide.md.txt b/pages/contrib/devs/git-guide.md.txt new file mode 100644 index 00000000..91787282 --- /dev/null +++ b/pages/contrib/devs/git-guide.md.txt @@ -0,0 +1,314 @@ +--- +~~Title: Git Best Practices~~ +--- + +# Git Best Practices # + +This document provides advice and guidance on using and contributing to the Enlightenment Project git repositories. Please read through this document before providing pull requests, patches, or working on a repository for the first time. + +A web interface to the Enlightenment Foundation repositories is available at [git.enlightenment.org](https://git.enlightenment.org/). + +## Prerequisites ## + +You will require ``git`` to be installed. Linux distributions using the ``apt`` package manager can install this prerequisite with the following command: + +``` +sudo apt install git +``` + +You are also expected to already possess a working knowledge of git; for more information see the [Git User Manual](https://git-scm.com/docs/user-manual.html). + +## Submitting and Reviewing Patches ## + +For information about the patch review process see the [Patch Submission and Review with Arcanist guide](arcanist-guide.md) + +## Rebase Instead of Merge ## + +Ensure that you have git set to rebase, rather than merge, by running the following command against your copy of the Enlightenment repository. + +``` +$ git config branch.master.rebase true +``` + +You can also make this configuration globally, but be aware this applies to all git repositories you access: + +``` +$ git config --global branch.master.rebase true +``` + +## Commit Messages ## + +Commit messages should be detailed rather than terse and include as much information about the commit as is reasonable. Please use the imperative form in the commit message in order to be consistent with the commit messages generated by git merge and revert. Write "Fix text bug", rather than "Fixed text bug". + +### Message Layout ### + +The general layout of a commit message should be as follows: + +* **Line 1:** {Module or Working Area}: A brief/short description of why the change has been made. This should be a single line with a maximum of 76 characters - like a NEWS entry. +* **Line 2:** Leave this line empty. +* **Line 3+:** The body text with a detailed description of the change. Explain why and how you have changed or fixed something in as much details as possible. Wrap lines at 76 characters. + +### Message Tags ### + +Depending on the nature of your commit some of the following tags might apply: + +* **@fix** - To be used when you fixed a bug which also applies to a released version (i.e. is not exclusively code from this development cycle). This tag is used as a marker for backports, although commits can be tagged as @fix but not backported if the backport is too "dangerous" to be in the stable branch - for example a fix that required some core rewrites. +* **@feature** - To be used when your commit introduces a new feature. Make sure your summary line is in really good shape and descriptive as this will be used in the NEWS file for the release. If this change consists of more than one commit only put it once - or, better yet, put it in the merge commit. +* **CID: XXXXX** - To be used if you fixed a issue discovered by a Coverity scan. It gives credit to them and helps us to see which commit relates to which issue. +* **Fixes TXXX** - Add a Phab ticket number if you fix a bug being tracked in [Phab](https://phab.enlightenment.org/). + +All these tags should live in the commit body with the detailed description, and not in the summary line. It is preferred if the tags are added as a separate line at the end of the commit message, though they will function from anywhere in the commit body. + +### Commit Message Example 1 ### + +``` +eet data: guarantee double-word alignment for temporary stack buffer. + +The code was giving enough memory to store doubles and longs, but they +could be unaligned as "unsigned char" allows 1-byte alignment while +double may require 8 bytes. + +By specifying the array as "long long" we force certain alignment in a +platform independent way. As this array is small enough and +short-lived the number of items were not changed. This results in +more bytes on the stack but it shouldn't matter. +``` + +### Commit Message Example 2 ### + +``` +spinner: Uncomment ctype.h inclusion because isspace is used. + +It looks like ctype.h is included in some other headers by luck but it +is recommended to explicitly include the necessary header. +Confirmed by glima as he commented this out. +``` + +### Commit Message Example 3 ### + +``` +evas textblock: Fix buffer overflow in anchor code + +If we set the anchor on a long text block the buffer might overflow. +Take string len into account. Long-standing bug. +@fix +CID: 123456 +``` + +### Commit Message Example 4 ### + +``` +eina: Add purple/yellow cherry tree algorithm implementation + +Newest research shows that the purple/yellow cherry tree algo is +way more efficient memory wise. Add a implementation to eina +so we can try it out in the real world. +@feature +``` + +### Commit Message Example 5 ### + +``` +genlist: Allow for more than 5 entries. + +It has been requested that we allow for more than 5 entries in the list. +I'm not sure if this is really needed but at least allow for it. +Fixes T2222 +``` + +## Merging Changes Back into Master ## + +Use cherry-pick for small changes if you don't want to push everything into master. If you did work into your own branch and worked on some big feature then you should push to master using the following workflow: + +1. Create a branch, either local or remote, for your change. +2. Work on that branch. +3. When ready, instead of pushing to master, rebase over master: ``git fetch; git rebase -p origin/master``. +4. If the commit history does not follow the [Commit Message guidelines](#Commit_Messages) ``rebase interactive`` to make sure all your pending patch notes are meaningful; merge them and change their commit messages as necessary. +6. Switch to master: ``git checkout master`` +7. ``git merge --no-ff your-feature-branch-name`` +8. Describe your feature in the commit message. +9. Push to master using ``git push`` or ``git push origin master``. + +## Repository layout ## + +The Enlightenment git repository is laid out in the following manner. + +### Main Branches ### + +The official branches are: + +* master - This is where all new work goes. +* {name}-{version} (e.g. "efl-1.8") - The stabilization branch for a specific version. + +### Developer Branches ### + +Every developer can create their own branches inside a repository. The naming must be ``devs/{devname}/*`` where ``{devname}`` is your user name (the directory name in the devs repository). + +These branches can be used if you're implementing a larger feature and want to share your progress with other developers. + +The branch named ``devs/{devname}/jenkins`` has a special meaning: Jenkins will automatically try to build this branch for you and report any warnings and errors. The results are available [from the Jenkins BYOB page](http://jenkins.enlightenment.org/view/BYOB/). + +#### Creating a Developer Branch #### + +Create a developer branch by pushing it to the remote repository: + +``` +$ git push --set-upstream origin devs/{devname}/{branch} +``` + +#### Deleting a Developer Branch #### + +Pass the ``--delete`` option to ``git-push`` to delete a developer branch: + +``` +$ git push origin --delete devs/{devname}/{branch} +``` + +## Developer Repositories ## + +If you are starting a new project, or just trying something out that doesn't belong to any of the existing repositories, you can create your own developer repository. + +### Creating a Developer Repository ### + +Create a new develop repository by using ``git clone``: + +``` +$ git clone ssh://[email protected]/devs/{devname}/foo.git +``` + +### Setting the Description ### + +In order for the [Repository Web Interface](https://git.enlightenment.org) to show a meaningful description set it with ``gitolite``'s ``desc`` command: + +``` +$ ssh [email protected] desc devs/{devname}/foo "Foo repository does bar" +``` + +### Deleting a Developer Repository ### + +Delete a developer repository using ``gitolite``'s ``trash`` command: + +``` +$ ssh [email protected] D trash devs/{devname}/foo +devs/{devname}/foo moved to trashcan. Please run the 'help' adc for more info. +``` + +Please note you need to use the repository name without .git at the end when running the ``trash`` command. + +### Listing Deleted Developer Repositories ### + +To list the currently deleted repositories type: + +``` +$ ssh [email protected] D list-trash +devs/{devname}/foo/2017-02-18_09:48:08 +``` + +### Restoring Deleted Developer Repositories ### + +To restore a previously deleted repository: + +``` +$ ssh [email protected] D restore +devs/{devname}/foo/2017-02-18_09:48:08 +``` + +### Gitolite Help ### + +Access ``gitolite``'s general help by typing: + +``` +$ ssh [email protected] help +``` + +Drill down to command-specific help with -h: + +``` +$ ssh [email protected] desc -h +``` + +## Useful Aliases ## + +The following git aliases can be used on any project and are designed to help with working on a central git repository. These aliases can be set in your global configuration by running the command ``git config``. + +### up ### + +Update the current branch. + +``` +$ git config --global alias.up "pull --rebase" +``` + +This alias makes git work like svn: it will fetch and rebase your code on the current branch. + +### up-master ### + +Update master without checking it out. + +``` +$ git config --global alias.up-master "fetch origin master:master" +``` + +This alias updates the master branch from upstream even if the currently checked out branch is not master. This is useful when you work on a branch and want to rebase on top of upstream's master. + +### wu ### + +"What's up" report. + +``` +$ git config --global alias.wu "log --reverse --stat @{upstream}..HEAD" +``` + +This alias shows the commits you're about to push upstream. + +### wup ### + +"What's up" report with patch information. + + +``` +$ git config --global alias.wup "log --reverse --stat -p @{upstream}..HEAD" +``` + +This alias shows the commits you're about to push upstream and their contents. + +### wus ### +Shortened "what's up" report. + +``` +$ git config --global alias.wus "log --reverse --oneline @{upstream}..HEAD" +``` + +A terse version of the "what's up" alias which shows the commits to push using single-line formatting. + +### safepush ### + +Push after reviewing which commits will be sent. + +``` +$ git config --global alias.safepush '![[ `git wus |wc -l` > 0 ]] && ( git wus && echo -n "Push to `git rev-parse --symbolic-full-name @{upstream}` [y/N]\\ " && read y && ( [[ $y =~ [yY] ]] && git push ) || true ) || echo "Nothing to push."' +``` + +This alias tells you what commits you're about to push and asks for confirmation before pushing. This can help you avoid mistakes when pushing stuff out in the wild. + +## Further Reading ## +[git.enlightenment.org](https://git.enlightenment.org/) +: A web interface to the Enlightenment git repositories. + +[https://phab.enlightenment.org/w/arcanist/](https://phab.enlightenment.org/w/arcanist/) +: Information on the patch submission and review process. + +[[email protected]](mailto:[email protected]) +: The mailing list for git assistance requests. + +[phab.enlightenment.org](https://phab.enlightenment.org/) +: The Enlightenment Phab ticket tracking system. + +[wiki.openstack.org/wiki/GitCommitMessages#Summary_of_Git_commit_message_structure](https://wiki.openstack.org/wiki/GitCommitMessages#Summary_of_Git_commit_message_structure) +: The Openstack Project's guide to what information should be in a commit message. + +[who-t.blogspot.de/2009/12/on-commit-messages.html](http://who-t.blogspot.de/2009/12/on-commit-messages.html) +: Peter Hutterer's guide to good commit messages. + +[wiki.videolan.org/Git](https://wiki.videolan.org/Git) +: The VideoLAN Project uses the same workflow as the Enlightenment Project. \ No newline at end of file --
