I’m curious about how much planning occurs before someone sits down to actually write code to add something to the API or refactor. Do the most active developers talk about their ideas on IRC or teamspeak? Do you draw up UML diagrams? Or is it more of a “someone writes the code, submits a pull request and then everyone looks it over” kind of deal?
More of the latter. But it’s entirely up to you.
Edit: I’m assuming you’re talking about user-submitted PRs. I don’t know what goes on for the official team.
So, part of it is mostly conversations held between IRC, TeamSpeak, and evaluations based on what is available from the implementation.
Since the API has been written from the ground up since September 2014, I can safely say that the API itself is a living a breathing creature of it’s own. When certain aspects of the game are features, we (the team) try to figure out ways to not just expose those features for manipulation from plugins, but also with a certain usability style and overall code style that aims to reduce changes in the future.
To give you an example of how I’ve personally went and written a large portion of a system of the API is the Data API.
It all started with my personal experience trying to work with Bukkit’s ItemMeta API when I was still a plugin developer targeting Bukkit implementations. The system was good for it’s own design in that it was clear what you can do and what you can’t do. The issues with the API arose when the game’s feature changes caused API changes, or sometimes forced the API to stagnate due to the idea of “always backwards compatible” by the Bukkit Team.
At first, I had thought for about a week how to design an API that would erase the necessity of knowing rigid constructs with regards to what the API could target, namely the specific ItemTypes. Since the largest goal of the API was to remain as compatible as possible with Forge mods, the API would have to be flexible enough to avoid rigid constructs about what sort of ItemTypes an ItemStack was, or whether the ItemType really mattered. After that week, I developed this PR. The goals of it are well documented in the PR’s description.
Of course, after a while, this system was working well enough from a design and usability standpoint to be flexible enough to work with more than just ItemStacks. After a lot of discussion with some other core developers, the API itself expanded into becoming what is now known as the Data API (this other PR). At the time, SpongeAPI had no concept of anything for something like EntityMeta, and the design decision was still something flexible that would work not with just the rigid vanilla constructs, but also those from mods.
The design decision paid off in the end, because that API was viable enough to still work with custom entities, without requiring those entities to specifically implement our API. Nor for plugins to even care what type of entities those entities were.
In the end, after some debate with plugin developers, simplification of the Data API was necessary, and it ended up being something of an even larger change that would keep in line with the principles of the API itself: being robust, flexible, and somewhat implementation agnostic. After some time from the original Data API PR, the Values API PR was introduced after a lot of internal discussion about various design concepts and design decisions.
That PR was made in June 2015. It is now February 2017, and the core of the Data API has yet to change.
Overall, yes, it took a lot of discussion with many people, a lot of time, and a lot of dedication to not just write out the entire API, but also to ensure that the API would be implemented without requiring changes.
That being said, this is an extreme example of what it would’ve required to introduce a huge system into the API (something that is used virtually throughout all plugins), whereas an example of a small API addition could be made with far less discussion and may require simply voicing out in an issue on the API repository saying: *“Hey, this part of the API could probably be improved. I have the following issues with how it’s used currently.” then, after some discussion, a new PR providing the changes, and to the implementation, would be reviewed, discussed, and ultimately decided on whether it’s accepted or replaced with a better alternative.
8 Likes
Hello @eah and welcome to Sponge 
.
Seeing as the API is my baby and I directly lead, I ultimately have the final say on what goes in or out. Thankfully that is only necessary for times in-which a final decision is needed to be made on x-y-z feature; otherwise the API is written by and for the community. The API can be thought of as one big project with many sub projects underneath. Each team member has their particular areas they are interested in working on and you’ll find that, depending on the issue at hand, a specific team member will end up helping you out. My role (beyond decision making) is project management; I decide when it is time to release new API revisions (such as the upcoming API 6 release) and coordinate with the team to wrap up the sub projects in prep for release as well as act as the “visionary” and guide the direction that the project will ultimately take.
To answer the thread topic question, I guess that I would say that a lot of it does happen behind the scenes. It isn’t out of necessity or some silly desire to be “secretive” if you will, its more out of the pace of the project’s progress the last few years. While things aren’t as blistering fast as it was at the start, there are so many things going on both in our lives and in the Sponge ecosystem that its difficult to juggle it all. By the time I can catch a breath and try to crawl all the forum posts or do up some PSAs I’ve long wanted to, we’re on to the next thing !
If you would like to know more of our history or more insight to some of the finer details of the project, let us know!
5 Likes
You’re a wizard. I can’t tell you how much I appreciate the Sponge API.
BTW, what did you use to render the UML diagrams in that first PR? And if it was Microsoft Visio, can you suggest an alternative, preferably one that’s free and looks good?