Latest News Article

[EvilSeph]

The following is the breakdown of the system we're looking to use to gather and handle Minecraft API changes. We're planning to employ the use of a JIRA project for proposal gathering, organisation and discussion and GitHub Pull Requests once code becomes involved (and a proposal has been accepted).

Quote

The Minecraft API proposal system is a set of guidelines developers are expected to follow if they want to contribute to the Minecraft API. A Minecraft API proposal (MAP) is a design document detailing the specifications, justification, challenges faced and need for a new addition to the Minecraft API. Every proposal submitted to the official Minecraft API JIRA Project is required to follow the provided template and to meet the following requirements.

Minecraft API Proposal Requirements:  

• A specific, to the point, summary (JIRA ticket title) should be provided. Vague summaries like "Awesome new feature!" will result in the proposal being rejected.
  
• The description of the MAP should contain detailed and justified specifications and challenges faced.
  
• The appropriate labels and components should be set to help with organisation and searching of MAPs.

MAP Template and example:
Summary: Trading API

Description:
Proposed addition:
Developers should be able to make use of the trading system in the game to set up their own trading system, inventory, prices and results. The trading API should allow developers to attach the ability to trade to any container, not just villagers.

Specific features:

• Trade recipe editing
  
• Trading related events

Justification and Use Case:
A trading API would allow developers to construct a sophisticated merchant system using the chest container.

Challenges faced:
None discovered at this time.

Affects Version/s:

Component/s:

Label/s: trading

After a MAP is properly submitted, each submission has a 2 week grace period before a decision can be made about the proposal, with some exceptions. This is to allow for ample time for the Minecraft developers community to review and comment on each proposal. However, while we are busy building the API for the first time, we may opt to skip the 2 week grace period on a per proposal basis to speed up the API design and development process.

The original author of the Minecraft API Proposal is expected to present their idea in a convincing manner and garner support from other developers in order to build up a community consensus. Alongside this public vetting process, the Minecraft team will be looking over each MAP and providing input as we feel is necessary and, ultimately, deciding to accept or reject a proposal. If we find that a proposal is popular but we need to reject it for whatever reason, we will usually look into alternatives, fixes or changes to address the issues we have with the proposal.

Once a MAP is accepted, a reference implementation will be worked on and the entire development process moves over to GitHub and its Pull Request system. In order for a reference implementation to be considered, each pull request has to meet the following requirements.

Minecraft API Pull Request (MAPR) Requirements:  

• The relevant MAP should be clearly associated and mentioned in the Pull Request title (see the template for an example of the expected format).
  
• The relevant MAP should be clearly linked to so discussions about the MAP can be read over if need be.
  
• Detailed information from the relevant MAP should be included in the Pull Request's description for easier managing of proposals.
  
• Submitted code is expected and required to adhere to our coding guidelines.
  
• A vetted MAP covering the Pull Request has to exist before a Pull Request is made.

Minecraft API Pull Request template and example:
Title: [MCAPI-1] Trading API

Description:
Associated MAP:
[MCAPI-1] http://link.to.MAP.here

Proposed addition:
Developers should be able to make use of the trading system in the game to set up their own trading system, inventory, prices and results. The trading API should allow developers to attach the ability to trade to any container, not just villagers.

Specific features:
- Trade recipe editing
- Trading related events

Justification and Use Case:
A trading API would allow developers to construct a sophisticated merchant system using the chest container.

Challenges faced:
None discovered at this time.

Thoughts and feedback on this process are greatly appreciated. We'll be constantly revising this system based on the lessons we learn from it being used and your input will help us with that immensely.

[russjr08]

Sounds great!

[md_5]

Seems like a good way to get things organised, personally I think google docs is a great way to organise your MAP's

[dcba41]

Nice, seems like a good, fair system; why do all the work yourselves, when most of it already out there is one shape or form.


EDIT: Woow, none of the first three people decided to announce they were "FIRST!!!!"

[benthegreat17]

Can't Wait!!!

[McProHosting]

EvilSeph, on 01 August 2012 - 08:17 AM, said:

The following is the breakdown of the system we're looking to use to gather and handle Minecraft API changes. We're planning to employ the use of a JIRA project for proposal gathering, organisation and discussion and GitHub Pull Requests once code becomes involved (and a proposal has been accepted).



Thoughts and feedback on this process are greatly appreciated. We'll be constantly revising this system based on the lessons we learn from it being used and your input will help us with that immensely.

Looks decent, but I really think performance should be one of the key factors, the better you can get performance the more features you can end up packing in in the long run, it'll open up room to do more things.

[PxlPanda]

Sounds interesting.

[ThaLenis]

i agree with md_5

[Iyeru]

McProHosting, on 01 August 2012 - 08:23 AM, said:

Looks decent, but I really think performance should be one of the key factors, the better you can get performance the more features you can end up packing in in the long run, it'll open up room to do more things.

Definitely agree with this.

[RustyDagger]

seems like a good way to go about the task at hand.

[chaseoes]

Sounds good - can't wait!

[Xamio]

Glad to see that you Mojangstas finally getting around to doing something related the the API after all this time. How long has it been, a year?

[escortkeel]

This looks great!

[Nouish]

Will be great to have an API available for modding. I'd be so happy to have one rather than 3-4, but I do believe it can end up being a shell for the modloaders everyone seems to be using.

[Milkycraft]

Sounds good

[varradami]

Seems perfectly reasonable, though I wouldn't bother inventing the terms "MAP" and "MAPR" - just call them proposals and pull requests.

Do you have an issue type called Proposal in JIRA? If not, you probably want to specify the issue type used. Also I assume you will at least have a Bug issue type. Do you want to provide some guidelines of how to write proper Bugs? Any other issue types (personally I recommend as few as possible - my experience is people will be confused)?

Do you prefer proposals come with pull requests, or at least some code examples?

McProHosting, on 01 August 2012 - 08:23 AM, said:

Looks decent, but I really think performance should be one of the key factors, the better you can get performance the more features you can end up packing in in the long run, it'll open up room to do more things.

Seems orthogonal to this discussion, which is more a "how to write a good issue description" than "how to write a good API". But certainly any proposal should consider performance.

[HeroCC]

Seems like a good idea!

It will help modders make their mods and iron out bugs! (And it would be cool to look at some Minecraft code

[DziNeIT]

Pull Request requirements needs to contain something about signing-off being required (in case you didn't know it makes sure they transfer ownership of the code to Mojang, if you'd done this for Bukkit you could have used Bukkit code in Minecraft-API ).

HeroCC, on 01 August 2012 - 12:46 PM, said:

Seems like a good idea!

It will help modders make their mods and iron out bugs! (And it would be cool to look at some Minecraft code

Minecraft code is not open-source. Only the API. The API alone does not contain any implementations and if you are hoping to learn Java from it the most you will learn is formatting / structure and how to define an abstract method.

[Talent3]

Should I start making my mod now? Or wait till 1.4. I feel like getting started now.

[CainFoool]

Finally, some real API work is getting done.