@@ -10,6 +10,9 @@
10 * New combinators have time and space complexity annotations
10 * New combinators have time and space complexity annotations
11 * New combinators have `since` annotation
11 * New combinators have `since` annotation
12* Changelog entry is added for exposed combinators.
12* 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".
13* Optionally, look at hlint output if anything in that is worth fixing.
16* Optionally, look at hlint output if anything in that is worth fixing.
14* Merge the PR by rebasing. Note that github always creates new commits when
17* Merge the PR by rebasing. Note that github always creates new commits when
15 merged with rebase, it records the committer as well as the author in the
18 merged with rebase, it records the committer as well as the author in the
@@ -100,6 +103,37 @@
100 * Check haddocks on Hackage, upload if not built
103 * Check haddocks on Hackage, upload if not built
101 * Announce to haskell-cafe@haskell.org
104 * Announce to haskell-cafe@haskell.org
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:
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:
115+* Silent changes in the behavior of an API without any changes to the
117+* Even fixing a bug could break things as users may have employed workarounds
119+* Changes in the behavior of a dependency may also cause a change in behavior.
121+Be cautious about the following:
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
128+* Deprecating an API may issue new warnings, however the code can still be
129+ compiled if warnings are not treated as errors.
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
103## Managing Issues
137## Managing Issues
105### User Impacting Changes
139### User Impacting Changes