Mailing-List: contact dev-help@apex.incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@apex.incubator.apache.org
Date: Mon, 14 Mar 2016 14:45:33 +0000 (UTC)
From: "ASF GitHub Bot (JIRA)" <jira@apache.org>
To: dev@apex.incubator.apache.org
Message-ID: <JIRA.12934710.1453965760000.8355.1457966733686@Atlassian.JIRA>
In-Reply-To: <JIRA.12934710.1453965760000@Atlassian.JIRA>
References: <JIRA.12934710.1453965760000@Atlassian.JIRA>
 <JIRA.12934710.1453965760157@arcas>
Subject: [jira] [Commented] (APEXCORE-319) Document backward compatibility
 guidelines
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 7bit


    [ https://issues.apache.org/jira/browse/APEXCORE-319?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15193386#comment-15193386 ] 

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_r56011204
  
    --- 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.
    +
    +###REST API
    +
    +REST API compatibility corresponds to both the URLs and request/response content over the wire. REST APIs are specifically meant for stable use by clients across releases, even major releases. 
    +
    +Policy
    +
    +The REST API is separately versioned. This is to allow for co-existence of old and new API should there be a need for backward incompatible changes in the future.
    +
    +###Command Line Interface (CLI)
    +
    +The CLI may be used either directly via the system shell or via shell scripts. Changing the path, removing or renaming command line options, the order of arguments, or the command return code and output break compatibility and may adversely affect users.
    +
    +Policy
    +
    +CLI commands are to be deprecated (warning when used) in a prior minor release before they are removed or incompatibly modified in a subsequent major release.
    +
    +###Configuration Files
    +
    +Configuration files are used for engine or application settings. Changes to keys and default values affect users. 
    +
    +Policy
    +
    +Name, location, format, keys of configuration files should be deprecated in a prior minor release and can only be changed in major release. Best effort should be made to support the deprecated behavior for one more major release (not guaranteed). 
    --- End diff --
    
    Why not have uniform deprecation policy for all the units


> 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)