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.

Sign up for GitHub

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

Jump to bottom

Use @API Guardian to mark public API #1536

Closed
16 tasks done
mpkorstanje opened this issue Jan 11, 2019 · 0 comments · Fixed by #1722
Closed
16 tasks done

Use @API Guardian to mark public API #1536

mpkorstanje opened this issue Jan 11, 2019 · 0 comments · Fixed by #1722
Labels
📖 documentation Improvements or additions to documentation ⚡ enhancement Request for new functionality
Milestone
5.0.0

Comments

@mpkorstanje
Copy link
Contributor

mpkorstanje commented Jan 11, 2019 •
edited
Loading

Summary

Use @API Guardian to mark the public API.

Semantic versioning requires that the public API is clearly marked. However the public API of Cucumber JVM does not overlap with the publicly accessible methods and classes. So the project is using *.api.* packages to mark the public api.

This is less then ideal:

  • Being in a separate package forces to either use Interface and InterfaceImpl constructs or to make implementation details of specific classes public. There are various examples of this in the codebase.
  • It makes it harder to organize packages by functionality. Most functions will have some classes located in api. As a result automated tooling and dependency graph analysis become hard to use.

Using an annotation instead of a package would solve this. It would also allow us to provide a bit more information about the API.

The downside is that we can't simply tell users to look in the cucumber.api package. However with the upcoming package restructuring for v5 this package will be split into cucumber.<module>.api and so lose quite a bit of it's value already.

Related:

Details

To do:

  • Add @API Guardian dependency to cucumber-parent.
  • Add @API to cucumber-expressions.
  • Add @API to datatable.
  • Document the use of @API Guardian.

While migrating these modules to the new package structure:

  • Add @API to junit. [JUnit] Deprecate cucumber.junit.api.Cucumber #1666
  • Add @API to testng.
  • Add @API to cd2.
  • Add @API to guice in develop-v5.
  • Add @API to needle.
  • Add @API to openejb.
  • Add @API to picocontainer.
  • Add @API to spring.
  • Add @API to weld.
  • Add @API to java.
  • Add @API to java8.
  • Add @API to core partially in develop-v5.
@mpkorstanje mpkorstanje added this to the 5.0.0 milestone Jan 11, 2019
@mpkorstanje mpkorstanje added Core 📖 documentation Improvements or additions to documentation ⚡ enhancement Request for new functionality labels Jan 11, 2019
@mpkorstanje mpkorstanje modified the milestones: 5.0.0, 5.x.x Apr 15, 2019
@mpkorstanje mpkorstanje changed the title Consider using @API Guardian to mark public API Use @API Guardian to mark public API Jun 16, 2019
mpkorstanje added a commit that referenced this issue Jun 16, 2019
@mpkorstanje
[JUnit] Replace api package with @API Guardian
cebf91f 
See: #1536
mpkorstanje added a commit that referenced this issue Jun 16, 2019
@mpkorstanje
[TestNG] Replace api package with @API Guardian
51e5c90 
See: #1536
@mpkorstanje mpkorstanje modified the milestones: 5.x.x, 4.x.x Jun 22, 2019
mpkorstanje added a commit that referenced this issue Jun 30, 2019
@mpkorstanje
[Core] Document what Cucumber-JVM considers it public API
e6de84d 
Cucumber-JVMs public API consists of either:

 * Any public class in in the `cucumber.api` package or subpackage
   thereof.
 * Any public class marked with
  `@org.apiguardian.api.API(status = API.Status.STABLE)`.

This dual system will allow us to gradually migrate the package
structure to `io.cucumber`.

While the `api` package makes it clear what is part of the API, it also
forces us to expose more of the API then strictly necessary. It also
creates split packages which will prevent Cucumber from being used
with the Java module system.

See #1536
mpkorstanje added a commit that referenced this issue Jun 30, 2019
@mpkorstanje
[Core] Document what Cucumber-JVM considers it public API
65b024f 
Cucumber-JVMs public API consists of either:

 * Any public class in in the `cucumber.api` package or subpackage
   thereof.
 * Any public class marked with
  `@org.apiguardian.api.API(status = API.Status.STABLE)`.

This dual system will allow us to gradually migrate the package
structure to `io.cucumber`.

While the `api` package makes it clear what is part of the API, it also
forces us to expose more of the API then strictly necessary. It also
creates split packages which will prevent Cucumber from being used
with the Java module system.

See #1536
@mpkorstanje mpkorstanje modified the milestones: 4.x.x, 5.0.0 Jun 30, 2019
@mpkorstanje mpkorstanje mentioned this issue Jun 30, 2019
Closed
This was referenced Aug 2, 2019
Merged
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
📖 documentation Improvements or additions to documentation ⚡ enhancement Request for new functionality
Projects
None yet
Milestone
5.0.0
Development

Successfully merging a pull request may close this issue.

Upgrade dependencies cucumber/cucumber-jvm
1 participant
@mpkorstanje