From owner-svn-doc-head@FreeBSD.ORG Mon Nov 11 04:07:58 2013 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTP id B246EAF5; Mon, 11 Nov 2013 04:07:58 +0000 (UTC) (envelope-from eadler@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 841552650; Mon, 11 Nov 2013 04:07:58 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id rAB47w4r068472; Mon, 11 Nov 2013 04:07:58 GMT (envelope-from eadler@svn.freebsd.org) Received: (from eadler@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id rAB47wsY068471; Mon, 11 Nov 2013 04:07:58 GMT (envelope-from eadler@svn.freebsd.org) Message-Id: <201311110407.rAB47wsY068471@svn.freebsd.org> From: Eitan Adler Date: Mon, 11 Nov 2013 04:07:58 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43157 - head/en_US.ISO8859-1/articles/committers-guide X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 11 Nov 2013 04:07:58 -0000 Author: eadler Date: Mon Nov 11 04:07:57 2013 New Revision: 43157 URL: http://svnweb.freebsd.org/changeset/doc/43157 Log: Split out and expand upon the committer guide's discussion of commit logs. Some discussion about how to write an appropriate commit log description should be included. The section currently only discusses the 'meta data'. Modified: head/en_US.ISO8859-1/articles/committers-guide/article.xml Modified: head/en_US.ISO8859-1/articles/committers-guide/article.xml ============================================================================== --- head/en_US.ISO8859-1/articles/committers-guide/article.xml Sun Nov 10 21:58:10 2013 (r43156) +++ head/en_US.ISO8859-1/articles/committers-guide/article.xml Mon Nov 11 04:07:57 2013 (r43157) @@ -2178,6 +2178,210 @@ ControlPersist yes + + Commit Log Messages + + This section contains some suggestions and traditions for + how commit logs are formatted. + + As well as including an informative message with each + commit you may need to include some additional + information. + + This information consists of one or more lines + containing the key word or phrase, a colon, tabs for + formatting, and then the additional information. + + The key words or phrases are: + + + + + + PR: + The problem report (if any) which is affected + (typically, by being closed) by this + commit. Only include one PR per line as the + automated scripts which parse this line can not + understand more than one. + + + + Submitted by: + The name and e-mail address of the person + that submitted the fix; for committers, just the + username on the &os; cluster. + If the submitter is the maintainer of the port + to which you are commiting include "(maintainer)" + after the email address. + Avoid obfuscating the + email address of the submitter as this adds + additional work when searching logs. + + + + + Reviewed by: + The name and e-mail address of the person or + people that reviewed the change; for committers, + just the username on the &os; cluster. If a + patch was submitted to a mailing list for review, + and the review was favorable, then just include + the list name. + + + + Approved by: + The name and e-mail address of the person or + people that approved the change; for committers, + just the username on the &os; cluster. It is + customary to get prior approval for a commit if it + is to an area of the tree to which you do not + usually commit. In addition, during the run up to + a new release all commits + must be approved by the + release engineering team. + + If these are your first + commits then you should have passed them past your + mentor first, and you should list your mentor, as + in ``username-of-mentor + (mentor)''. + + If a team approved these commits + then include the team + name followed by the username of the approver in + parenticies. For example: ``re@ + (username)`` + + + + Obtained from: + The name of the project (if any) from which + the code was obtained. Do not use this line for the + name of an indivual person. + + + + MFC after: + If you wish to receive an e-mail reminder to + MFC at a later date, specify + the number of days, weeks, or months after which + an MFC is planned. + + + + Security: + If the change is related to a security + vulnerability or security exposure, include one or + more references or a description of the + issue. If possible, include a VuXML URL or a CVE id. + + + + + + + Commit Log for a Commit Based on a PR + + You want to commit a change based on a PR submitted + by John Smith containing a patch. The end of the commit + message should look something like this. + + ... + + PR: foo/12345 + Submitted by: John Smith <John.Smith@example.com> + + + + Commit Log for a Commit Needing Review + + You want to change the virtual memory system. You + have posted patches to the appropriate mailing list (in + this case, freebsd-arch) and the + changes have been approved. + + ... + + Reviewed by: -arch + + + + Commit Log for a Commit Needing Approval + + You want to commit a port + You have collaborated with + the listed MAINTAINER, who has told you to go ahead and + commit. + + ... + + Approved by: abc (maintainer) + + Where abc is the account + name of the person who approved. + + + + Commit Log for a Commit Bringing in Code from + OpenBSD + + You want to commit some code based on work done in + the OpenBSD project. + + ... + + Obtained from: OpenBSD + + + + Commit Log for a Change to &os.current; with a + Planned Commit to &os.stable; to Follow at a Later + Date. + + You want to commit some code which will be merged + from &os.current; into the &os.stable; branch after two + weeks. + + ... + +MFC after: 2 weeks + + Where 2 is the number of + days, weeks, or months after which an + MFC is planned. The + weeks option may be + day, days, + week, weeks, + month, months, or + may be left off (in which case, days will be + assumed). + + + In some cases you may need to combine some of + these. + + Consider the situation where a user has submitted a PR + containing code from the NetBSD project. You are looking + at the PR, but it is not an area of the tree you normally + work in, so you have decided to get the change reviewed by + the arch mailing list. Since the + change is complex, you opt to MFC after + one month to allow adequate testing. + + The extra information to include in the commit would + look something like + + Example Combined Commit Log + PR: foo/54321 +Submitted by: John Smith <John.Smith@example.com> +Reviewed by: -arch +Obtained from: NetBSD +MFC after: 1 month + + + Preferred License for New Files @@ -4400,192 +4604,6 @@ bak/packages packages from last complet - What meta information should I include - in a commit message? - - - - As well as including an informative message with each - commit you may need to include some additional information - as well. - - This information consists of one or more lines - containing the key word or phrase, a colon, tabs for - formatting, and then the additional information. - - The key words or phrases are: - - - - - - PR: - The problem report (if any) which is affected - (typically, by being closed) by this - commit. - - - - Submitted by: - The name and e-mail address of the person - that submitted the fix; for committers, just the - username on the &os; cluster. - - - - Reviewed by: - The name and e-mail address of the person or - people that reviewed the change; for committers, - just the username on the &os; cluster. If a - patch was submitted to a mailing list for review, - and the review was favorable, then just include - the list name. - - - - Approved by: - The name and e-mail address of the person or - people that approved the change; for committers, - just the username on the &os; cluster. It is - customary to get prior approval for a commit if it - is to an area of the tree to which you do not - usually commit. In addition, during the run up to - a new release all commits - must be approved by the - release engineering team. If these are your first - commits then you should have passed them past your - mentor first, and you should list your mentor, as - in ``username-of-mentor - (mentor)''. - - - - Obtained from: - The name of the project (if any) from which - the code was obtained. - - - - MFC after: - If you wish to receive an e-mail reminder to - MFC at a later date, specify - the number of days, weeks, or months after which - an MFC is planned. - - - - Security: - If the change is related to a security - vulnerability or security exposure, include one or - more references or a description of the - issue. - - - - - - - Commit Log for a Commit Based on a PR - - You want to commit a change based on a PR submitted - by John Smith containing a patch. The end of the commit - message should look something like this. - - ... - -PR: foo/12345 -Submitted by: John Smith <John.Smith@example.com> - - - - Commit Log for a Commit Needing Review - - You want to change the virtual memory system. You - have posted patches to the appropriate mailing list (in - this case, freebsd-arch) and the - changes have been approved. - - ... - -Reviewed by: -arch - - - - Commit Log for a Commit Needing Approval - - You want to commit a change to a section of the tree - with a MAINTAINER assigned. You have collaborated with - the listed MAINTAINER, who has told you to go ahead and - commit. - - ... - -Approved by: abc - - Where abc is the account - name of the person who approved. - - - - Commit Log for a Commit Bringing in Code from - OpenBSD - - You want to commit some code based on work done in - the OpenBSD project. - - ... - -Obtained from: OpenBSD - - - - Commit Log for a Change to &os.current; with a - Planned Commit to &os.stable; to Follow at a Later - Date. - - You want to commit some code which will be merged - from &os.current; into the &os.stable; branch after two - weeks. - - ... - -MFC after: 2 weeks - - Where 2 is the number of - days, weeks, or months after which an - MFC is planned. The - weeks option may be - day, days, - week, weeks, - month, months, or - may be left off (in which case, days will be - assumed). - - - In some cases you may need to combine some of - these. - - Consider the situation where a user has submitted a PR - containing code from the NetBSD project. You are looking - at the PR, but it is not an area of the tree you normally - work in, so you have decided to get the change reviewed by - the arch mailing list. Since the - change is complex, you opt to MFC after - one month to allow adequate testing. - - The extra information to include in the commit would - look something like - - PR: foo/54321 -Submitted by: John Smith <John.Smith@example.com> -Reviewed by: -arch -Obtained from: NetBSD -MFC after: 1 month - - - - - How do I access people.FreeBSD.org to put up personal or project information?