@@ -10,6 +10,9 @@
1010 * New combinators have time and space complexity annotations
1111 * New combinators have `since` annotation
1212* Changelog entry is added for exposed combinators.
13+* Identify breaking changes, or changes that may require depndency
14+ version bound changes. See https://pvp.haskell.org/. Also see the
15+ "Breaking changes section below".
1316* Optionally, look at hlint output if anything in that is worth fixing.
1417* Merge the PR by rebasing. Note that github always creates new commits when
1518 merged with rebase, it records the committer as well as the author in the
@@ -100,6 +103,37 @@
100103 * Check haddocks on Hackage, upload if not built
101104 * Announce to haskell-cafe@haskell.org
102105
106+## Breaking Changes
107+
108+This section lists what constitutes breaking changes. See
109+https://pvp.haskell.org/ breaking changes that can be determined by the
110+API alone. We specify some additional recommendations here:
111+
112+Behavior changes, this kind of changes are nasty and should be avoided. If such
113+changes are made they should be emphasized adequately in the changelog:
114+
115+* Silent changes in the behavior of an API without any changes to the
116+ signature.
117+* Even fixing a bug could break things as users may have employed workarounds
118+ for the bug.
119+* Changes in the behavior of a dependency may also cause a change in behavior.
120+
121+Be cautious about the following:
122+
123+* Change in version bounds of dependencies may cause compilation failure for
124+ some programs because they may not be able to find a build plan.
125+* Ideally, new warnings should not be considered breaking, dependencies
126+ should never be compiled with -Werror. But packages may not be following
127+ it perfectly.
128+* Deprecating an API may issue new warnings, however the code can still be
129+ compiled if warnings are not treated as errors.
130+
131+Internal APIs:
132+
133+* Internal APIs can change without having to change the major version. However,
134+ we should try to align the Internal API changes with a major release as long
135+ as possible.
136+
103137## Managing Issues
104138
105139### User Impacting Changes