[
https://issues.apache.org/jira/browse/APEXCORE-319?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15194185#comment-15194185
]
ASF GitHub Bot commented on APEXCORE-319:
-----------------------------------------
Github user PramodSSImmaneni commented on a diff in the pull request:
https://github.com/apache/incubator-apex-site/pull/19#discussion_r56079841
--- Diff: src/md/compatibility.md ---
@@ -0,0 +1,112 @@
+#Apache Apex Compatibility
+
+##Purpose
+
+This document captures the compatibility goals of the Apache Apex project.
The different types of compatibility between Apex releases that affect
contributors, downstream projects, and end-users are enumerated. For each type
of compatibility we:
+
+* describe the impact on downstream projects or end-users
+* where applicable, call out the policy adopted when incompatible changes
are permitted.
+
+Apache Apex follows [semantic versioning](http://semver.org/). Depending
in the compatibility type, there may be different tools or mechanisms to ensure
compatibility, for example by comparing artifacts during the build process.
+
+The type of change will inform the required target version number. Given a
version number MAJOR.MINOR.PATCH, increment the:
+
+* MAJOR version when you make incompatible API changes,
+* MINOR version when you add functionality in a backwards-compatible
manner, and
+* PATCH version when you make backwards-compatible bug fixes.
+
+Additional labels for pre-release and build metadata are available as
extensions to the MAJOR.MINOR.PATCH format.
+
+The overall goal is to avoid backward incompatible changes and major
release upgrades. Accordingly we attempt to release new features with minor
versions that are incremental to the prior release and offer our users a
frictionless upgrade path. When planning contributions, please consider
compatibility and release road map upfront. Specifically, certain changes that
conflict with the versioning may need to be documented in JIRA and deferred
until a future major release.
+
+##Compatibility types
+
+###Java API
+
+Public API compatibility is required to ensure end-user programs and
downstream projects continue to work without modification.
+The public API consists of:
+
+* apex-core: all interfaces and classes in `api` and `common` modules
+* apex-malhar: all interfaces and classes in all modules except `demos`,
`samples`, `benchmark`
+
+Interfaces and classes that are part of the public API and are annotated
with [interface
stability](https://hadoop.apache.org/docs/stable/hadoop-project-dist/hadoop-common/InterfaceClassification.html)
are treated according to the rules defined by the annotation.
+
+Policy
+
+Changes to the public API must follow semantic versioning.
+Public APIs must be deprecated for at least one major release prior to
their removal in a major release.
+The japicmp plugin is used to enforce compatibility as part of the Travis
pre-commit builds.
+
+###Semantic compatibility
+
+The behavior of APIs needs to remain consistent over versions, though
changes for correctness may result in changes in behavior. Tests and javadocs
specify the behavior. Over time, test suites should be expanded to verify
compliance with the specification, effectively creating a formal specification
for the subset of behaviors that can be easily tested.
+
+Policy
+
+The behavior of API may be changed to fix incorrect behavior, changes to
be accompanied by tests coverage for the exact behavior.
--- End diff --
Not suggesting to undo a release. A bug fix is fine unless it changes the
behavior that user relies upon. For example if you are throwing an exception
with an error code and you made a mistake by reusing same error code for two
different error conditions, you cannot "fix" it by just changing the error
code, the caller may have already added error handling code for the two
scenarios for the old error code. Think about mkdir() for example, in non mapr
versions it creates all folders in the path if they don't exist but mapr sticks
to the posix standard. Lets say you had such a function that didn't implement
the standard correctly the first time and you want to change it, that would
break user code. A new method should be created to handle such scenarios.
Golden rule don't break user code (not my words).
> Document backward compatibility guidelines
> ------------------------------------------
>
> Key: APEXCORE-319
> URL: https://issues.apache.org/jira/browse/APEXCORE-319
> Project: Apache Apex Core
> Issue Type: Task
> Reporter: Chris Nauroth
> Assignee: Thomas Weise
> Labels: tlp
>
> QU40
> The project puts a high priority on backwards compatibility and aims to
> document any incompatible changes and provide tools and documentation to help
> users transition to new features.
> I couldn't find backwards-compatibility guidelines documented at
> apex.incubator.apache.org. Example:
> http://hadoop.apache.org/docs/r2.7.2/hadoop-project-dist/hadoop-common/Comp
> atibility.html
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
