Commit 5d113ed1 authored by Utkarsh Ayachit's avatar Utkarsh Ayachit Committed by Kitware Robot

Merge topic 'update_docs'

77e2587a Add commit log guidelines
c2578746 Add guidelines for merge request logs.
Acked-by: Kitware Robot's avatarKitware Robot <kwrobot@kitware.com>
Acked-by: Dan Lipsa's avatarDan Lipsa <dan.lipsa@kitware.com>
Acked-by: Robert Maynard's avatarRobert Maynard <robert.maynard@kitware.com>
Merge-request: !1846
parents fc5780e3 77e2587a
Pipeline #22950 running with stage
......@@ -127,6 +127,31 @@ A reader should have a general idea of the feature or fix to be developed given
* If your change modifies third party code, see [its
documentation](../../../ThirdParty/UPDATING.md).
Guidelines for Commit logs
--------------------------
Remember to *motivate & summarize*. When writing commit logs, make sure
that there is enough information there for any developer to read and glean
relevant information such as:
1. Is this change important and why?
2. If addressing an issue, which issue(s)?
3. If a new feature, why is it useful and/or necessary?
4. Are there background references or documentation?
A short description of what the issue being addressed and how will go a long way
towards making the log more readable and the software more maintainable.
Style guidelines for commit logs are as follows:
1. Separate subject from body with a blank line
2. Limit the subject line to 60 characters
3. Capitalize the subject line
4. Use the imperative mood in the subject line e.g. "Refactor foo" or "Fix Issue #12322",
instead of "Refactoring foo", or "Fixing issue #12322".
5. Wrap the body at 80 characters
6. Use the body to explain `what` and `why` and if applicable a brief `how`.
Share a Topic
-------------
......@@ -228,6 +253,30 @@ Follow these steps:
7. Use the "**Submit merge request**" button to create the merge request
and visit its page.
Guidelines for Merge Requests
-----------------------------
Remember to *motivate & summarize*. When creating a merge request, consider the
reviewers and future perusers of the software. Provide enough information to motivate
the merge request such as:
1. Is this merge request important and why?
2. If addressing an issue, which issue(s)?
3. If a new feature, why is it useful and/or necessary?
4. Are there background references or documentation?
Also provide a summary statement expressing what you did and if there is a choice
in implementation or design pattern, the rationale for choosing a certain path.
Notable software or data features should be mentioned as well.
A well written merge request will motivate your reviewers, and bring them up
to speed faster. Future software developers will be able to understand the
reasons why something was done, and possibly avoid chasing down dead ends,
Although it may take you a little more time to write a good merge request,
you’ll likely see payback in faster reviews and better understood and
maintainable software.
Review a Merge Request
----------------------
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment