THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
Summary
Commenting these options remained really silent. This means our Friend APIs most likely stay as they are now. I must acknowledge that adding new friends to an existing API is easier than ever having NetBeans under Apache umbrella.
What requires probably the less effort and ease the most pain is to try to make some API open using our best effort by:
Option 4: Make Module Public when There is more than a Certain Number of Friend Dependencies.
Purpose
The intention of this page is summarize the ideas to resolving the situation around Friend API-s. We probably need to vote on this.
For further information of the currently used system please check the API Stability on our old wiki, along with the API Snapshoting procedure.
Please read the NbmPackageStability on our old wiki that covers some ideas on this topic, and the wider relationship with semantic versioning, Maven, OSGi, Jigsaw, etc.Wh
What is possibly wrong with the Friend API concept?
- There are many Friend APIs, which are not changed for years but which are useful for many. It is difficult to use them because there is a known or not known author of the API as a gatekeeper to add you on the list of friends, e.g. problems with the JNA-module.
"Historically, the problem has been:
- Developer develops some modules with a friend API between them
- Developer goes away / moves on to another project / loses access to the repo
- The modules stay in the distro, but other than someone updating them in the case of API changes, nobody is touching the code
- Somebody wants friend access to it
- There is nobody to ask"
Suggestions
- Leave Friend API-s as it is.
a Additionally better documentation how to use this concept - Make all current Friend API-s Public, but leave the Friend API concept.
a. Review existing Friend APIs and make the APIs with good enough quality public - Make a module automatically Public after a certain point of time/number of releases.
- Make module public when there is more than certain number of friend dependencies
- Few friend deps are fine. More than five suspicious. More than ten a big no-no.
- Developers can mark their API as unstable/incubating/etc. but otherwise these modules behave as Public. Build time warnings can happen.
- As above, plus warn users on plugin installation if a plugin has unstable dependencies, and therefore is not guaranteed to work in future versions.
- Create a formal community process around Friendly package being promoted.
- Review / update the proposal at NbmPackageStability - switch to semantic versioning, mark stability, align better with OSGi / Maven, and get rid of Friend and Implementation dependencies (and possibly do same in-your-face warning as 5a to encourage moves to stabilize!)
Various positions
- Automatically "Public" after a certain point of time (3. suggestion): Some people assume that this can motivate friend-api writers to stabilize the APIs, others think this does not motivate but instead procudes unstable Public APIs.
"For me an unstable or incubation flag would be more than sufficient, and the build might warn me or optionally fail if I'd use an unstable/incubation level of module."
Originally "The *entire* purpose was for a developer to evolve an API, in collaboration with others whose requirements might lead to incompatible changes in it, prior to being subject to the stringent backward compatibility requirements Sun required of public APIs. But "There are other reasons for using more than one module where you *never* intend to create a public API, but need other aspects of the module system - optionally loaded parts, OS-specific parts, etc. So I *am* thinking of a small number of things that are logically a unit.
"If you have a shifting team of developers over a period of years, the best guarantee that the things you want to happen on an ongoing basis are remembered is if there is automation and infrastructure that makes them a natural part of doing work. Otherwise you're relying on institutional knowledge and someone having the time and concern to do it. I've seen "please make my module a friend of X" bugs languish for 6-9 months simply because it wasn't someone's priority, and they were working for someone who didn't see it as a priority either. If it's "hey we better stabilize this or we've got to live with it as-is", that makes it a priority, like it or not."
- "Another issue is still module splitting - bigger feature implementations are often splitted into several modules, which need the ability to
privately access each other. This also results in some mismatch: Sometimes it would be nice to be able to expose some APIs as friend-only, while others are interesting for public usage. Currently, only either export is possible. While one can split the exporting module once more, this is probably not always convenient - probably this should be fixed. Also, such module-clusters should probably be friends by convention, i.e. there should probably be some concept similar to "NetBeans Suite" projects (by sharing some token, residing together in a "sub-cluster" or sth. similar)."
- "I think you are annoyed by friend APIs just because nobody cared through time about those APIs to bring them to a public API. But that's just a sign of no money / human resources poured into it, not a lack of automation or other processes. If you somehow force people to reconsider friend APIs as they become public in 2 releases then they will just stop using friend APIs and find other creative ways via reflection, the global lookup, etc. So... you only obfuscate the matter. Note that the Friend API is not only for NetBeans! You could also have your own bunch of modules and defined friends among some of them, etc. I know that some NetBeans friend APIs are quite juicy so I understand the frustration but it's a frustration with the NetBeans codebase, not the concept itself."
"I like it to start with Friend-only API because then a potential user must become active to use it. The user asks me to be added on the friend-list and I get his e-mail and I can ask him for feedback in my answer. That is great. The main problem in the context of netbeans maybe is that it needs additional time that the netbeans repository is updated with the information of the list-change. Maybe other people are involved etc. But I am not sure if this is really a problem."
Analysis
Option 1: Leave Friend API-s as it is.
Well this is clearly an issue here. This generated quite a bit of stir on our mailing lists, see the various positions above. Adding more documentation on the topic does not solve the problem, though can help junior plugin developers.
Laszlo Kishalmi I'm still fine with my Yanta workaround, we could document it, and make that even official, though I won't feel this a solution for our initial problems.
Neil Smith -1 to in any way making Yenta official - that's just papering over the cracks and exposing internal implementation details (the NbmPackageStability proposal is mostly written by the same author as Yenta to stop it needing to be used!).
@peter steele -1, the design pattern of having a friend's API is a bad one in my opinion. If the API is not stable then it shouldn't be in a production build.
Option 2: Make all Current Friend API-s Public, but Leave the Friend API Concept.
This option has the advantage, that it does not require changes to the module system, though we get rid of our current friends that bugging us. I still need to prepare a list with the current Friendly modules, though if we would like to do it right, the module API and documentation needs to be reviewed, improved. That is a lot of additional work, that could leas us to option 5.
Option 3: Make a Module Automatically Public After a Certain Point of time/number of Releases.
This option, would make a simple strait forward way, and dependable way to move modules from friendly to public state, which is a goal if we would like to have a really open system. Though this simple condition only approach may decrease the quality of our API-s and do not grant stability.
Laszlo Kishalmi I could live with this option, though I might not see the real consequences now regarding the decreased API quality/stability. (Still this is not my favorite)
Option 4: Make Module Public when There is more than a Certain Number of Friend Dependencies.
This option sets an other condition making some API-s public based on the usage of the actual API. Number of friends could be a better indicator than the actual time the module present in or codebase. We need to add that there several Yenta users around and counting their usage might not be easy.
Laszlo Kishalmi Well, I like this idea as well. It might raise a question that how shall we handle friendship requests/registration in the future. E.g. Is it enough to create an issue and a pull request in JIRA/GitHub to grant friend access? Can we grant friendship access to a module all the time? What are the use cases if we deny such a request?
Option 5: Developers can mark Their API as Unstable/Incubating but Otherwise These Modules Behave as Public.
This solution could mean a slight modification on our module system or maybe just the tooling (build harness, maven plugins). This just puts complete responsibility to the plugin developer if he would like to use a non-stable module as dependency.
Laszlo Kishalmi I can support this.
Neil Smith I can support this - was my initial position until I found the Option 7 page. But this still might require changes to how module versioning / dependency resolution is done? Stability in a single release of the IDE / platform should probably be guaranteed with this idea? No breaking point updates.
@peter steele this is by far the easiest solution if experimental APIs are needed.
Option 6: Create a Formal Community Process Around Friendly Package Being Promoted.
This option also means that we keep the current concept, just try to deal with our baggage of friendly API-s on an organized manner. Well, we need come up with a process, if we would go this way, but a sample one could be:
- After 2 weeks of each release (this is just a trigger event I came up with)
- The community has 1-2 weeks to came up with a prioritized list of Friend packages that needs to go to public.
- An API review committee takes this list as input, and reviews the API and documentation of the topmost item (maybe items), creates issues on required changes/documentation.
- The community provides documentation/modification/fixes for the API.
- If all the committee found issues has been resolved, then a committee does a second review, if the review has no other findings than the committee accepts the API as a public NetBeans API
- We could do a commitment, depending on our release schedule, that how many modules we are going to review during one cycle.
This way we could make NetBeans gradually more open, with keeping the quality.
Laszlo Kishalmi : I fully support this approach.
Neil Smith I'd fully support us doing this irrespective of other outcomes on here - this just feels like formalising things that should already be happening?!
@peter steele the over head of doing this could be problematic, over time the process will be forgotten and you end up in the same place as now.
Option 7: Review / Update the Proposal at NbmPackageStability
Following the link to the old wiki pages, this solution, has far the best in-depth analysis. Though the proposed solution here is theoretically doable, but I have a feeling that it would cause more pain than the current Friend system. Let's see the main points of the proposal:
- Move down the stability classification from module level to package level
- Use explicit closed, open version ranges on dependencies
- Adds new enforced policies to the process (mostly through the build system)
Laszlo Kishalmi: I think this option would be overkill, and though it would help in our Friendly issue, placing the policies and migrating the modules this way, would be a ton of work and would create other problems elsewhere.
Neil Smith no secret this is my preferred approach! I don't see the point in changing anything in the module system itself (so Option 5) without addressing other crunch points of the module system that have come up recently, and how it translates to other systems we're using or might use (OSGi, Maven, Jigsaw etc.). In that respect I don't think it's overkill if the solution to this involves changing the module system.