Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

About Compatibility #11528

Closed
panyx0718 opened this issue Jun 16, 2018 · 1 comment
Closed

About Compatibility #11528

panyx0718 opened this issue Jun 16, 2018 · 1 comment
Assignees

Comments

@panyx0718
Copy link
Contributor

panyx0718 commented Jun 16, 2018

Paddle follows semantic versioning.
Each release has version of the following format: MAJOR.MINOR.PATCH. Some key points:

  • Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable. (We'll discuss it doesn't quite fit us)

  • For 1.y.z, changes across MINOR version should be backward compatible.

  • If your software is being used in production, it should probably already be 1.0.0. If you have a stable API on which users have come to depend, you should be 1.0.0. If you’re worrying a lot about backwards compatibility, you should probably already be 1.0.0.

Why Paddle Needs to Worry About Compatibility Now

  • Paddle has been used in production.
  • Paddle has been widely announced and users are encouraged to try it.
  • For internal users and external users, there is no way to search all usages of a public API or checkpoings.
  • We really want to release 1.x.y sometime in the near future.

Why not release 1.x.y now.

  • Paddle Fluid is still fast evolving.
  • We do not have enough knowledge about how well the current design fits to the real usages.
  • Compatibility-related policy and tools are not set up.

What can be done before 1.x.y

  • API that you are not sure if user would use it, make it private.

  • API that is expected to be public but is expected to change:

    • Expose the API through contrib/ directory.
  • If a backward incompatible change can make the design much better and cleaner

    • Add a new API with better design.
    • Mark the old API as deprecated. Print warning message declaring the removal date (at least 3 months later). And try to inform or upgrade every user you are aware of.
    • 3 months later, remove the old API.
  • If API has bug that can only be fixed in an incompatible way.

    • Ask for tech leads and other colleagues advice.
    • If there is no better solutions, fix it.
  • Write a tool to monitor incompatible change

    • Analyze the API changes
    • Analyze ProgramDesc changes.
    • Alarm when such as change happens.

What changes could cause incompatibility.

  • Change public Python API codes.
  • Change C++ Operator interface and it's public Python API is auto-generated.
  • Change framework.proto or update codes that cause changes in generated Program proto.
  • etc.

Reference

https://semver.org/
http://docs.chainer.org/en/stable/compatibility.html
https://www.tensorflow.org/programmers_guide/version_compat

@panyx0718 panyx0718 self-assigned this Jun 16, 2018
@panyx0718
Copy link
Contributor Author

drafting a version document for 1.0

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant