diff --git a/CHANGELOG.md b/CHANGELOG.md index 670ab37..0669a9e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,52 +1,43 @@ -
Changelog for the official Arctic Ice Studio Git Style Guide.
# 0.2.0 -- Release Date: *2017-07-24* - Milestone - Project Board -
-- Release Date: *2017-07-22* - Milestone - Project Board -
-The Arctic Ice Studio Git Style Guide.
+The official Arctic Ice Studio Git Style Guide.
---- +To present Git [commits][git-docs-commit] and [branches][git-docs-branch] in an organized, standardized, and easy-to-read manner, this style guide describes how the content should be structured, spelled and formatted in all official _Arctic Ice Studio_ projects. -To present Git [commits](https://git-scm.com/docs/git-commit) and [branches](https://git-scm.com/docs/git-branch) in an organized, standardized, and easy-to-read manner, this official style guide describes how the content should be structured, spelled and formatted in all Arctic Ice Studio projects. - -There are only some strict rules but mostly guidelines since we are more interested in content than formatting and the review process may help contributors to conform to this guide later on. +There are only some strict rules but mostly guidelines since we are more interested in content than formatting while the review process might help contributors to conform to this guide later on. ## Introduction -Commit messages are important parts of communication between contributors and for the lifecycle of the project: its past and its future. It is the only place that captures not only what was changed, but why. +Commit messages are important parts of communication between contributors and the lifecycle of a project: its past and its future. It is the only place that captures not only what was changed, but why. -For open source project communities it is important to maintain good habits of communication in all forms. A well-crafted commit message can save a lot of time and overhead and helps to speed up development processes. +For open source project communities it‘s important to maintain good habits of communication in all forms. A well-crafted commit message can save a lot of time, overhead and helps to speed up development processes. ## Structural Split of Changes -> If a code change can be split into a sequence of patches/commits, then it should be split. *Less is not more.* +> If a code change can be split into a sequence of patches/commits, then it should be split. +> _Less is not more_. The cardinal rule for creating good commits is to **ensure there is only one logical change** per commit. There are many reasons why this is an important rule: -* **The smaller the amount of code** being changed, **the quicker and easier it is to review** and identify potential flaws. -* **Revert broken commits is much easier if there are not other unrelated code changes entangled with the original commit** if a change is found to be flawed later. -* **Small well defined changes will aid in isolating exactly where the code problem was introduced** when troubleshooting problems using Git's `bisect` capability. -* **Small well defined changes aid in isolating exactly where- and why a piece of code came from** when browsing history using Git `annotate` or `blame`. +- **The smaller the amount of code** being changed, **the quicker and easier it is to review** and identify potential flaws. +- **Revert broken commits is much easier if there are not other unrelated code changes entangled with the original commit** if a change is found to be flawed later. +- **Small well defined changes will aid in isolating exactly where the code problem was introduced** when troubleshooting problems using Git‘s `bisect` capability. +- **Small well defined changes aid in isolating exactly where- and why a piece of code came from** when browsing history using Git `annotate` or `blame`. ### Bad Practices -* **Mixing whitespace changes with functional code changes**. The whitespace changes will obscure the important functional changes, making it harder for a reviewer to correctly determine whether the change is correct. - * The change should be split into two commits, one with the whitespace changes, one with the functional changes. -* **Mixing two unrelated functional changes**. Without a structural split of changes it will be harder to identify flaws if two unrelated changes are mixed together. If it becomes necessary to later revert a broken commit, the two unrelated changes will need to be untangled, with further risk of bug creation. -* **Sending large new features in a single giant commit**. The code for a new feature is only useful when all of it is present, but this does not imply that the entire feature should be provided in a single commit. - * New features may entail refactoring existing code so it is highly desirable that any refactoring is done in commits which are separate from those implementing the new feature. This helps reviewers and test suites validate that the refactoring has no unintentional functional changes. - * Newly written code can often be split up into multiple pieces that can be independently reviewed. For example, changes which add new internal APIs/classes, can be in self-contained commits leading to easier code review and allows other developers to cherry-pick small parts of the work, if the entire new feature is not immediately ready for merge. - * Code that affects public APIs should be done in commits separate from the actual internal implementation. This will encourage the author and reviewers to think about the generic API design, and not simply pick a design that is easier for their currently chosen internal implementation. +- **Mixing whitespace changes with functional code changes**. The whitespace changes will obscure the important functional changes, making it harder for a reviewer to correctly determine whether the change is correct. + - The change should be split into two commits, one with the whitespace changes, one with the functional changes. +- **Mixing two unrelated functional changes**. Without a structural split of changes it will be harder to identify flaws if two unrelated changes are mixed together. If it becomes necessary to later revert a broken commit, the two unrelated changes will need to be untangled, with further risk of bug creation. +- **Sending large new features in a single giant commit**. The code for a new feature is only useful when all of it is present, but this does not imply that the entire feature should be provided in a single commit. + - New features may entail refactoring existing code so it is highly desirable that any refactoring is done in commits which are separate from those implementing the new feature. This helps reviewers and test suites validate that the refactoring has no unintentional functional changes. + - Newly written code can often be split up into multiple pieces that can be independently reviewed. For example, changes which add new internal APIs/classes, can be in self-contained commits leading to easier code review and allows other developers to cherry-pick small parts of the work, if the entire new feature is not immediately ready for merge. + - Code that affects public APIs should be done in commits separate from the actual internal implementation. This will encourage the author and reviewers to think about the generic API design, and not simply pick a design that is easier for their currently chosen internal implementation. ## Commit Messages -> The commit message must contain all the information required to fully understand & review the patch. *Less is not more*. +> The commit message must contain all the information required to fully understand & review the patch. +> _Less is not more_. -As important as the content of the change, is the content of the commit message describing it. The purpose of a commit message is to summarize a change, but the purpose of summarizing a change is to help to understand the code. The information to be put into a message should be valuable and useful for reviewers and the projects community. +As important as the content of the change is the content of the commit message describing it. The purpose of a commit message is to summarize a change, but the purpose of summarizing a change is to help to understand the code. The information to be put into a message should be valuable and useful for reviewers and the projects community. Having a story in the Git history will make a huge difference in how others perceive the project. Taking great care in commit messages will help to increase the long-term overall quality. -* **The first line is important**. The [message summary](#message-summary) of the commit has special significance. It is used in many places like the Git history headline, git annotate- and merge messages or email subject lines where space is at a premium. As well as summarizing the change itself, it should take care to detail what part of the code is affected. -* **Describe the intent and motivation behind the changes**. Describe *why* the code has been written this way and document the overall code structure in the [message body](#message-body), particularly for large changes. -* **Include the GitHub issue ID and additional references** in the [message footer](#message-footer). This will automatically fire some hooks to track the commit in related GitHub repository issues- and pull requests and is **required to contribute to a project**. -* **Reviewers can understand what the original problem was**. The commit message should have a clear statement as to what the original problem is. The GitHub issue ID is merely interesting historical background on *how* the problem was identified and has been discussed within the community, but it should be possbile to review a proposed patch for correctness without having to read the whole ticket. +- **The first line is important**. The [message summary](#message-summary) of the commit has special significance. It is used in many places like the Git history headline, git annotate- and merge messages or email subject lines where space is at a premium. As well as summarizing the change itself, it should take care to detail what part of the code is affected. +- **Describe the intent and motivation behind the changes**. Describe _why_ the code has been written this way and document the overall code structure in the [message body](#message-body), particularly for large changes. +- **Include the GitHub issue ID and additional references** in the [message footer](#message-footer). This will automatically fire some hooks to track the commit in related GitHub repository issues- and pull requests and is **required to contribute to a project**. +- **Reviewers can understand what the original problem was**. The commit message should have a clear statement as to what the original problem is. The GitHub issue ID is merely interesting historical background on _how_ the problem was identified and has been discussed within the community, but it should be possbile to review a proposed patch for correctness without having to read the whole ticket. -### Elements and their Structure +### Elements and their structure A Git commit message follows this format: -``` + +```rawCopyright © 2017-present Arctic Ice Studio and Sven Greb
- + -[arcver]: https://github.com/arcticicestudio/arcver -[gitflow]: http://nvie.com/posts/a-successful-git-branching-model +[git-docs-branch]: https://git-scm.com/docs/git-branch +[git-docs-commit]: https://git-scm.com/docs/git-commit +[github_flow]: https://guides.github.com/introduction/flow +[semver-2]: https://semver.org/spec/v2.0.0.html diff --git a/src/assets/styleguide-git-banner-typography-badge.svg b/assets/badge-typography.svg similarity index 97% rename from src/assets/styleguide-git-banner-typography-badge.svg rename to assets/badge-typography.svg index 4a4a013..4176823 100755 --- a/src/assets/styleguide-git-banner-typography-badge.svg +++ b/assets/badge-typography.svg @@ -1,4 +1,4 @@ -