X-Git-Url: http://git.cascardo.eti.br/?p=cascardo%2Fovs.git;a=blobdiff_plain;f=CONTRIBUTING.md;h=6f69cfff0b96b5a01f4e014c5972e57e4e85a499;hp=b434e78e3a98a4fa444b9f86d61b5b80c7d475c5;hb=600766e877efa2713b9c87d127f7190d8ab48da9;hpb=542cc9bb8b8817866afcd692a78fa591db5839dc diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b434e78e3..6f69cfff0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,10 +24,16 @@ In particular: - A patch that adds or removes user-visible features should also update the appropriate user documentation or manpages. + Check "Feature Deprecation Guidelines" section in this document + if you intend to remove user-visible feature. Testing is also important: - - A patch that adds or deletes files should be tested with + - A patch that modifies existing code should be tested with `make + check` before submission. Please see INSTALL.md, under + "Self-Tests", for more information. + + - A patch that adds or deletes files should also be tested with `make distcheck` before submission. - A patch that modifies Linux kernel code should be at least @@ -44,8 +50,8 @@ Testing is also important: If you are using GitHub, then you may utilize the travis-ci.org CI build system by linking your GitHub repository to it. This will run some of the above tests automatically when you push changes to your repository. -See the "Continuous Integration with Travis-CI" in the [INSTALL](INSTALL.md) -file for details on how to set it up. +See the "Continuous Integration with Travis-CI" in the [INSTALL.md] file +for details on how to set it up. Email Subject ------------- @@ -154,6 +160,17 @@ Examples of common tags follow. the tag himself in response to an email indicating successful testing results. + Tested-at: + + When a test report is publicly available, this provides a way + to reference it. Typical s would be build logs from + autobuilders or references to mailing list archives. + + Some autobuilders only retain their logs for a limited amount + of time. It is less useful to cite these because they may be + dead links for a developer reading the commit message months + or years later. + Reported-by: Reporter Name When a patch fixes a bug reported by some person, please @@ -198,6 +215,14 @@ Examples of common tags follow. Reported-at: http://openvswitch.org/pipermail/dev/2014-June/040952.html + Submitted-at: + + If a patch was submitted somewhere other than the Open vSwitch + development mailing list, such as a GitHub pull request, this header can + be used to reference the source. + + Submitted-at: https://github.com/openvswitch/ovs/pull/92 + VMware-BZ: #1234567 ONF-JIRA: EXT-12345 @@ -215,6 +240,16 @@ Examples of common tags follow. in old change log entries. (They are obsolete because they do not tell the reader what bug tracker is referred to.) + Fixes: 63bc9fb1c69f (“packets: Reorder CS_* flags to remove gap.”) + + If you would like to record which commit introduced a bug being fixed, + you may do that with a “Fixes” header. This assists in determining + which OVS releases have the bug, so the patch can be applied to all + affected versions. The easiest way to generate the header in the + proper format is with this git command: + + git log -1 --pretty=format:"Fixes: %h (\"%s\")" --abbrev=12 COMMIT_REF + Developer's Certificate of Origin --------------------------------- @@ -249,6 +284,37 @@ certifies the following: maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved. +Feature Deprecation Guidelines +------------------------------ + +Open vSwitch is intended to be user friendly. This means that under +normal circumstances we don't abruptly remove features from OVS that +some users might still be using. Otherwise, if we would, then we would +possibly break our user setup when they upgrade and would receive bug +reports. + +Typical process to deprecate a feature in Open vSwitch is to: + + (a) Mention deprecation of a feature in the NEWS file. Also, mention + expected release or absolute time when this feature would be removed + from OVS altogether. Don't use relative time (e.g. "in 6 months") + because that is not clearly interpretable. + + (b) If Open vSwitch is configured to use deprecated feature it should print + a warning message to the log files clearly indicating that feature is + deprecated and that use of it should be avoided. + + (c) If this feature is mentioned in man pages, then add "Deprecated" keyword + to it. + +Also, if there is alternative feature to the one that is about to be marked +as deprecated, then mention it in (a), (b) and (c) as well. + +Remember to followup and actually remove the feature from OVS codebase +once deprecation grace period has expired and users had opportunity to +use at least one OVS release that would have informed them about feature +deprecation! + Comments -------- @@ -278,8 +344,8 @@ If you cannot convince your email client not to mangle patches, then sending the patch as an attachment is a second choice. Please follow the style used in the code that you are modifying. The -[CodingStyle](CodingStyle.md) file describes the coding style used in -most of Open vSwitch. Use Linux kernel coding style for Linux kernel code. +[CodingStyle.md] file describes the coding style used in most of Open +vSwitch. Use Linux kernel coding style for Linux kernel code. Example ------- @@ -316,3 +382,5 @@ index fdd952e..f6cb88e 100644 1.7.7.3 ``` +[INSTALL.md]:INSTALL.md +[CodingStyle.md]:CodingStyle.md