apex-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From davidyan74 <...@git.apache.org>
Subject [GitHub] incubator-apex-site pull request: APEXCORE-319 Document compatibil...
Date Mon, 14 Mar 2016 20:34:52 GMT
Github user davidyan74 commented on a diff in the pull request:

    https://github.com/apache/incubator-apex-site/pull/19#discussion_r56070892
  
    --- 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 --
    
    I agree with pramod


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

Mime
View raw message