Docs: added deprecation guidance eBay#352

Author: ianmcburnie

CONTRIBUTING.md

@@ -67,31 +67,50 @@ This section contains information and etiquette regarding pull requests (or "PRs
 
 If you are creating a new component or significantly altering an existing one, please ensure that an issue has been created *before* you start any work, and that it has been assigned to you. The same goes for any big new additions or changes to the project structure, CI or documentation.
 
-We want to avoid cases where developers build something that does not align with our wants & needs. We also want to be able to carefully plan our sprint and test cycles with minimal disruption. We especially want to avoid cases where two developers duplicate work.
+We ask this because:
+
+* we want to avoid cases where developers build something that does not align with our wants & needs
+* we want to be able to carefully plan our sprint and test cycles with minimal disruption
+* we want to avoid cases where two developers duplicate work
 
 ### Writing Code
 
 The contents of a pull request should be related to a single issue only (or, at most, perhaps two very closely related issues). The reviewer has the right to reject a pull request that contains anything non-issue related.
 
-Whilst it may be tempting to fix any other [broken windows](https://www.rtuin.nl/2012/08/software-development-and-the-broken-windows-theory/) that you encounter, it can distract the reviewer from the main issue at hand, make their job more time-consuming and increase the chance of regressions. Remember too, if the main issue were to get rolled back (for whatever reason), then there is a good chance that your non-related fixes would get rolled back along with it too. Which is probably not what anyone wants. So please be a good citizen and create separate issues or pull requests for the broken windows that you find.
+Whilst it may be tempting to fix any [broken windows](https://www.rtuin.nl/2012/08/software-development-and-the-broken-windows-theory/) that you encounter, we ask you not to because:
+
+* it can distract the reviewer from the main issue at hand
+* it can add additional time needed for the reviewer
+* it can increase the chance of regressions
+* it can make rollbacks more difficult
+
+So please be a good citizen and create separate issues or pull requests for any broken windows that you find.
 
 ### Moving Code
 
 Please try and isolate "noisy" commits that only *move* many files or lines of code, from commits that actually modify code logic. The reviewer has the right to reject a pull request that is difficult to reason with due to too much *unnecessary* noise in the diff.
 
 For example, assuming moving some code doesn't put the app into a broken state, the move can be considered a safe atomic commit (e.g. "moved functions x, y and z to bottom of file"). The actual *fixes* to functions x, y and z can then be made in a follow up commit (e.g. "fixed functions x, y and z") which will be easier for the reviewer to diff.
 
+### Breaking Changes
+
+Please think very carefully before introducing breaking API changes. Breaking changes may only be introduced in a major version. If you wish to alter the API *before* a major version, then aliases can often be a good way to achieve this. Using an alias, the old API can be deprecated and will still continue to function.
+
+### Deprecating Code
+
+Any deprecated code should be clearly documented in the code comments and the release notes. Deprecated code will typically be scheduled for removal in the next major version.
+
 ### Avoiding Conflicts
 
-It is your responsibility to ensure that your feature branch has no merge conflicts with it's base branch. A pull request created and sent for review containing many conflicts does not inspire confidence in the reviewer.
+It is your responsibility to ensure that your feature branch has no merge conflicts with its base branch. A pull request created and sent for review containing many conflicts does not inspire confidence in the reviewer.
 
-The best way to ensure there are no conflicts is by keeping your branch up to date with it's base branch and resolving any conflicts in your own branch early & often. You may do this either by rebasing or merging. If you are the only developer working in the feature branch (you need to be sure), it is usually better to rebase. If another developer is sharing your branch, then merging is the safer option (as it doesn't require a force push).
+The best way to ensure there are no conflicts is by keeping your branch up to date with its base branch and resolving any conflicts in your own branch early & often. If you are the only developer working in the feature branch, then it is usually better to rebase. If another developer is sharing your branch, then merging is the safer option (as it doesn't require a force push).
 
-If you are working on a large feature, that takes many days, then there is a good chance that the base branch will have received many other commits during that time. If you wait till the very end you may find you have to deal with some difficult merge conflicts. On the other hand, if your pull request was created quickly and only touches a small surface area, then more than likely you will not run into any conflicts at the time the pull request is created. It doesn't hurt to keep a watchful eye on the base branch though.
+If you are working on a large feature, that takes many days, then there is a good chance that the base branch will have received other commits during that time. If you wait till the very end before syncing your branch with the base branch, then you may have to deal with some difficult merge conflicts.
 
 ### Commit History
 
-Whilst having multiple "work in progress", "almost done" and "merged branch" type commits in a feature branch is fine, we wish to refrain from them polluting the milestone and master branch history. On the flip side, although rarer in comparison, we might also have some *atomic* commits in our feature branch that we absolutely wish to keep as part of the project history.
+Whilst having multiple "work in progress", "almost done" and "merged branch" type commits in a feature branch is fine, we wish to refrain from those commits polluting the milestone and master branch history. On the flip side, although rarer in comparison, we might also have some *atomic* commits in our feature branch that we absolutely wish to keep as part of the project history.
 
 Before creating your pull request you have two options regarding what to do with the commit history of your feature branch:
 
@@ -177,8 +196,7 @@ A component is considered "done", and ready for merge into release branch, when
 3) Code review
 
 * Linter should catch syntax and style issues
-* Prefer performance over readability
-* Prefer readability over "space saving" code
+* Prefer performance over readability, but readability over "space saving" code
 * Apply the single-responsibility principle to functions
 * Refactor long functions into several small functions
 * Identify and move common utility functions to libraries or static methods

README.md

@@ -200,6 +200,10 @@ Given a version number MAJOR.MINOR.PATCH:
 * MINOR version is incremented when we add functionality in a backwards-compatible manner
 * PATCH version is incremented when we make backwards-compatible bug fixes.
 
+### Deprecations
+
+Deprecations will be communicated via [release notes](https://github.com/eBay/ebayui-core/releases), so please ensure that you read those carefully. In general, expect any deprecated feature to be removed in the next major version. However, in some cases we may wait a while longer.
+
 ### Issues
 
 Please use our [issues page](https://github.com/eBay/ebayui-core/issues) to ask questions, report issues or submit feature requests.