- 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.
+
+ - 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
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
-------------
the tag himself in response to an email indicating successful
testing results.
+ Tested-at: <URL>
+
+ When a test report is publicly available, this provides a way
+ to reference it. Typical <URL>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 <reporter.name@email.address...>
When a patch fixes a bug reported by some person, please
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
---------------------------------
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
--------
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
-------
1.7.7.3
```
+[INSTALL.md]:INSTALL.md
+[CodingStyle.md]:CodingStyle.md