Difference between revisions of "HOWTO-Engine Inclusion"
Jump to navigation
Jump to search
(Initial import of the engine merge procedure discussed on -devel.) |
m (minor language changes) |
||
| Line 1: | Line 1: | ||
=Introduction about the engine merge procedure= | =Introduction about the engine merge procedure= | ||
This page describes the procedure | This page describes the procedure for merging a new engine into the main ScummVM development line. It intends to provide guidance for both the engine developers and the ScummVM team on the procedure for merging new engines into ScummVM. | ||
=Preparing your engine= | =Preparing your engine= | ||
| Line 7: | Line 7: | ||
==What needs to be done before you can ask for your engine to be merged into ScummVM?== | ==What needs to be done before you can ask for your engine to be merged into ScummVM?== | ||
ScummVM is a project which focuses on reimplementation of adventure game engines. We support a wide range of platforms. Due to these facts | ScummVM is a project which focuses on reimplementation of adventure game engines. We support a wide range of platforms. Due to these facts, there are a few requirements your engine has to fulfill before it has a chance of being included in the ScummVM mainline. | ||
We cover the really basic requirements here first: | We cover the really basic requirements here first: | ||
| Line 13: | Line 13: | ||
* Your engine must target an 2D point&click adventure game. | * Your engine must target an 2D point&click adventure game. | ||
* All your code must follow our Code Formatting Conventions. It does not have to be perfect, but it needs to follow the overall style. We will happily point out issues and help you with the remaining issues. | * All your code must follow our Code Formatting Conventions. It does not have to be perfect, but it needs to follow the overall style. We will happily point out issues and help you with the remaining issues. | ||
* Your code should | * Your code should reflect the fact that you know our Coding Conventions and have tried to implement them in your code. If you have questions about specifics, you are free to ask us. | ||
* Your engine needs to be on github. | * Your engine needs to be on github. | ||
* The engine development history should not change/add common code and/or modify backend related code, without | * The engine development history should not change/add common code and/or modify backend related code, without discussing it with us first. | ||
* Your code compiles with g++. | * Your code compiles with g++. | ||
| Line 21: | Line 21: | ||
* You will be becoming the maintainer for the engine. That gives you the possibility to work on your engine in our master development branch. But it also comes with responsibilities. You should be able to spend some time handling incoming bugs for your engine, especially in release phases. Furthermore we need you to be contactable, so we can discuss issues in your engine or backend/middleware changes with you, so either we or you can adapt your engine to these. | * You will be becoming the maintainer for the engine. That gives you the possibility to work on your engine in our master development branch. But it also comes with responsibilities. You should be able to spend some time handling incoming bugs for your engine, especially in release phases. Furthermore we need you to be contactable, so we can discuss issues in your engine or backend/middleware changes with you, so either we or you can adapt your engine to these. | ||
* Your code needs to be in a maintainable state. It should be written in such a way that we | * Your code needs to be in a maintainable state. It should be written in such a way that we (as C++ coders) can maintain/port/fix the input/graphics/sound code, and that we can at least understand the game logic (i.e. not too many unknown fields, commented where necessary, not depending on asm files or an IDB or etc to be readable) | ||
* The game supported by your engine needs to be completable on at least i386/amd64. You need to have time to adapt your code so it will work on as much platforms as we support (and is feasible) OR help our porters or other developers with it. | * The game supported by your engine needs to be completable on at least i386/amd64. You need to have time to adapt your code so it will work on as much platforms as we support (and is feasible) OR help our porters or other developers with it. | ||
* Your engine needs to be in a state that we can easily include it in the next release or at latest in the one afterwards. | * Your engine needs to be in a state that we can easily include it in the next release - or, at latest, in the one afterwards. | ||
==How you ask for inclusion in ScummVM== | ==How you ask for inclusion in ScummVM== | ||
It is always a good idea to first come to our IRC channel and point people to your engine. Even when you do not want it to be merged yet! That will help you to get feedback on what you need to take care of when you | It is always a good idea to first come to our IRC channel and point people to your engine. Even when you do not want it to be merged yet! That will help you to get feedback on what you need to take care of when you eventually want your engine to be merged. There is always a developer - or even a few - who will happily help you with your engine and answer general questions. | ||
The next step would be to drop a mail to our -devel mailing list. There you can tell everyone working on ScummVM that you | The next step would be to drop a mail to our -devel mailing list. There, you can tell everyone working on ScummVM that you are working on a new engine, and are planning to bring it to a state where it will be ready for the merge discussion. | ||
==Starting the pull request== | ==Starting the pull request== | ||
| Line 37: | Line 37: | ||
=The merge discussion= | =The merge discussion= | ||
This is the part were you and the ScummVM team discuss about the chances of your engine | This is the part were you and the ScummVM team discuss about the chances of your engine being merged, and eventually, even discuss how it will be merged. You should have time to reply to the questions we have about your engine and its code. In this phase we usually try to provide code feedback too, so it would be nice if you could show us that you can work with that. | ||
There are minimal requirements before you engine will be merged: | There are minimal requirements before you engine will be merged: | ||
* There is a delay of at least one week between your initial pull request and -devel mail and the merge. In that time we will give all ScummVM members the chance to check your engine and | * There is a delay of at least one week between your initial pull request and -devel mail and the merge. In that time we will give all ScummVM members the chance to check your engine and its state. | ||
* All serious issues which arise in that time have to be taken care of before the engine will be merged. | * All serious issues which arise in that time have to be taken care of before the engine will be merged. | ||
* The majority ScummVM core team members have to *explicitly* state that they are fine with the merge. All other core team members have at least told their stance on the merge. | * The majority ScummVM core team members have to *explicitly* state that they are fine with the merge. All other core team members have at least told their stance on the merge. | ||
How we proceeded from then on will be decided on a per case | How we proceeded from then on will be decided on a per case basis. | ||
Revision as of 09:43, 20 November 2011
Introduction about the engine merge procedure
This page describes the procedure for merging a new engine into the main ScummVM development line. It intends to provide guidance for both the engine developers and the ScummVM team on the procedure for merging new engines into ScummVM.
Preparing your engine
What needs to be done before you can ask for your engine to be merged into ScummVM?
ScummVM is a project which focuses on reimplementation of adventure game engines. We support a wide range of platforms. Due to these facts, there are a few requirements your engine has to fulfill before it has a chance of being included in the ScummVM mainline.
We cover the really basic requirements here first:
- Your engine must target an 2D point&click adventure game.
- All your code must follow our Code Formatting Conventions. It does not have to be perfect, but it needs to follow the overall style. We will happily point out issues and help you with the remaining issues.
- Your code should reflect the fact that you know our Coding Conventions and have tried to implement them in your code. If you have questions about specifics, you are free to ask us.
- Your engine needs to be on github.
- The engine development history should not change/add common code and/or modify backend related code, without discussing it with us first.
- Your code compiles with g++.
Furthermore we require a bit more from you, which isn't basic anymore:
- You will be becoming the maintainer for the engine. That gives you the possibility to work on your engine in our master development branch. But it also comes with responsibilities. You should be able to spend some time handling incoming bugs for your engine, especially in release phases. Furthermore we need you to be contactable, so we can discuss issues in your engine or backend/middleware changes with you, so either we or you can adapt your engine to these.
- Your code needs to be in a maintainable state. It should be written in such a way that we (as C++ coders) can maintain/port/fix the input/graphics/sound code, and that we can at least understand the game logic (i.e. not too many unknown fields, commented where necessary, not depending on asm files or an IDB or etc to be readable)
- The game supported by your engine needs to be completable on at least i386/amd64. You need to have time to adapt your code so it will work on as much platforms as we support (and is feasible) OR help our porters or other developers with it.
- Your engine needs to be in a state that we can easily include it in the next release - or, at latest, in the one afterwards.
How you ask for inclusion in ScummVM
It is always a good idea to first come to our IRC channel and point people to your engine. Even when you do not want it to be merged yet! That will help you to get feedback on what you need to take care of when you eventually want your engine to be merged. There is always a developer - or even a few - who will happily help you with your engine and answer general questions.
The next step would be to drop a mail to our -devel mailing list. There, you can tell everyone working on ScummVM that you are working on a new engine, and are planning to bring it to a state where it will be ready for the merge discussion.
Starting the pull request
This is really easy, just open a pull request for your engine on github. Also write a mail to our -devel mailing list.
The merge discussion
This is the part were you and the ScummVM team discuss about the chances of your engine being merged, and eventually, even discuss how it will be merged. You should have time to reply to the questions we have about your engine and its code. In this phase we usually try to provide code feedback too, so it would be nice if you could show us that you can work with that.
There are minimal requirements before you engine will be merged:
- There is a delay of at least one week between your initial pull request and -devel mail and the merge. In that time we will give all ScummVM members the chance to check your engine and its state.
- All serious issues which arise in that time have to be taken care of before the engine will be merged.
- The majority ScummVM core team members have to *explicitly* state that they are fine with the merge. All other core team members have at least told their stance on the merge.
How we proceeded from then on will be decided on a per case basis.