Difference between revisions of "Developer Central"

From ScummVM :: Wiki
Jump to navigation Jump to search
(→‎New GUI: Add link to developer instructions for GUI translation support)
(→‎Code statistics: update link to ohloh/openhub)
(32 intermediate revisions by 11 users not shown)
Line 2: Line 2:


== Getting started ==
== Getting started ==
* The first thing you need to be able to do is [[SVN#Getting the code|get the ScummVM code]].
* The first thing you need to be able to do is [[Git#Retrieving_the_code|get the ScummVM code]] from our [[Git]] repository.
* Then you should [[Compiling ScummVM|compile ScummVM]].
* Then you should [[Compiling ScummVM|compile ScummVM]].


Line 8: Line 8:


* Some hints on [[Debugging ScummVM|debugging ScummVM]].
* Some hints on [[Debugging ScummVM|debugging ScummVM]].
* Before you write/submit code, '''you must read about our''' [[Code Formatting Conventions]]. Patches which do not follow them will be rejected or at least delayed until they are cleaned up to comply to them.
* Before you write/submit code, '''you must read''' our [[Code Formatting Conventions]].<br>Patches which do not follow them will be rejected or at least delayed until they are cleaned up to comply to them.
* Also, please read and respect the [[Portability Guide]].
* Also, you should read and respect the general [[Coding Conventions]].
* If you have write access to our repository, you are expected to have read and to comply with our [[Commit Guidelines]].
* If you have write (push) access to our repository, you are expected to have read and to comply with our [[Commit Guidelines]].<br>Also, please read the tips for using Git here: [[Git tips]].<br>In particular, note the use of feature branches, when working on refactoring or other large connected changes, rather than committing directly to scummvm/master.
* If you do not have write access, you should use our [http://sourceforge.net/tracker/?group_id=37116&atid=418822 patch tracker] to submit your contributions.
* If you do not have write (push) access to our repository, you should submit your contributions by one of the following methods:
** Using a [https://help.github.com/articles/using-pull-requests Github Pull Request].<br> This requires you to have/register a github account, fork our repository, commit your changes to a branch and then issue a Pull Request.<br>This is the current preferred method as it is easier for the team to review, discuss and amend prior to merging.<br>You are expected to have read and to comply with our [[Commit Guidelines]].
** Using the [https://bugs.scummvm.org/ patch tracker].<br>This requires you to have/register a github account, and generate a [https://en.wikipedia.org/wiki/Patch_%28Unix%29 patch] file, but this may be easier for developers unfamilar with Git or for small single commit changes, where a Pull Request might be considered overkill.
** If neither of the above methods are suitable, individual developers may be willing to accept patches or amended source files by other methods i.e. e-mail, but please ask in the project IRC channel or by e-mail before doing this.
* Our [http://doxygen.scummvm.org/ Doxygen source code documentation] may help you to get the big picture about ScummVM.
* Our [http://doxygen.scummvm.org/ Doxygen source code documentation] may help you to get the big picture about ScummVM.
* Also, you might want to check our list for current [[Platform Limitations]].
* Also, you might want to check our list for current [[Platform Limitations]].
== Pull Request approval process ==
The current procedure is as follow:
# For a sizeable, significant changes it is advised to make a [https://help.github.com/articles/about-pull-requests/ Pull Request on GitHub].
# Such Pull Request will have to stay for at least 2 weeks open for the comments.
# Everyone is invited to comment and review and voice their opinion (views of non-team members are valuable, but have no decisive power).
# If there are no unaddressed objections after 2 weeks, the PR could be merged. Exception could be made if there are suggestions over refactoring or tidying up the code, granted that they will be addressed in-tree.
# Immediately after the merge the PR maker ensures that the [http://buildbot.scummvm.org buildbot] stays happy and is not worsened (historically we had few ports broken for months).
The definition of what makes a sizeable changes not cast in stone. This is up to the discretion of the PR creator, but normally we would expect that anything which breaks existing OSystem API and the Common code, or significantly extends these, especially if it requires more work from the Porters, should go via a Pull Request process. The goal is to ensure that everything stays maintainable.
Any developer is free to open a PR for less significant changes, and that process could be used for facilitating the discussion and collecting feedback, but when there are no big changes involved, no 2 weeks timeout is enforced.
Individual engine sub-teams decide by themselves on the process. For example currently the SCI development is performed via PRs as well for any sizeable changes. It is up to that sub-team to drop this rule any time or make something even stricter. Just make sure you continue enjoying hacking the ScummVM code.


== For Engine authors ==
== For Engine authors ==
Line 20: Line 37:
* If your engine supports multiple games / game variants, properly detecting and differentiating them all can be a nuisance. Use the [[Advanced Detector]] to overcome this hurdle.
* If your engine supports multiple games / game variants, properly detecting and differentiating them all can be a nuisance. Use the [[Advanced Detector]] to overcome this hurdle.
* Accessing files in a portable fashion is non-trivial. Read all about [[HOWTO-Open_Files|how to open files]].
* Accessing files in a portable fashion is non-trivial. Read all about [[HOWTO-Open_Files|how to open files]].
* Debugging endian issues can be tricky. [[HOWTO-Debug-Endian-Issues |This page]] gives some solutions.
* If you want to have your engine merged into the ScummVM mainline, check out our [[HOWTO-Engine_Inclusion|Engine Inclusion HOWTO]].
* For those starting out with reverse engineering, check out our [[HOWTO-Reverse_Engineering|Reverse Engineering HOWTO]].
* Apart from git bisection to locate regressions in gameplay, the (experimental) [[Event_Recorder|Event Recorder]] provides a framework for recording and replaying gameplay to detect regressions.
* For some general suggestions on developing engines, see the [[HOWTO-Tips_And_Tricks|Engine Development Tips & Tricks]]


== For Backend authors ==
== For Backend authors ==
* If you want to port ScummVM to a new platform, check out our [[HOWTO-Backends|Backends HOWTO]].
* If you want to port ScummVM to a new platform, check out our [[HOWTO-Backends|Backends HOWTO]].
* The [[HOWTO-Dynamic_Modules|Dynamic Modules HOWTO]] describes how to implement loadable modules on a smaller backend, even without operating system support.
== For Web site maintainers ==
If you want to update the main web site:
* Update the files you want in the scummvm-web project
* Trigger http://www.scummvm.org/site-update/ URL. (Ask sev for an account)
* This is also covered in more detail by the relevant section of the Admin HOWTO [[HOWTO-Admin#How_to_edit.2Fupdate_webpages|here]].


== Projects, plans, things to do ==
== Projects, plans, things to do ==
We are usually happy to receive any kind of help with the things listed below.
We are usually happy to receive any kind of help with the things listed below.
* [[OpenTasks|List of open tasks]], with relatively detailed descriptions, and contact points. Some rather small ones, some bigger ones, take a look.
* [[OpenTasks|List of open tasks]], with relatively detailed descriptions, and contact points. Some rather small ones, some bigger ones, take a look. [[GSoC Ideas]] also has some ideas, intended for students applying for Google's Summer of Code.
* [[TODO|Main TODO list]] (contains links to many further specialized TODO pages, e.g. for specific engines).
* [[TODO|Main TODO list]] (contains links to many further specialized TODO pages, e.g. for specific engines).
* Our [http://sourceforge.net/tracker/?group_id=37116&atid=418820 bug tracker] lists bugs that need to be resolved
* Our [https://bugs.scummvm.org/ bug tracker] lists bugs that need to be resolved and also lists features requested by all kinds of people.
* Our [http://sourceforge.net/tracker/?group_id=37116&atid=418823 feature request tracker] also lists features requested by all kinds of people.


The following are partially outdated, but kept for now for the sake of reference.
The following are partially outdated, but kept for now for the sake of reference.
Line 40: Line 68:
* [[GUI Themes]]
* [[GUI Themes]]
* [[GUI Themes/Specs|GUI Theme Specs]]
* [[GUI Themes/Specs|GUI Theme Specs]]
* [[Supporting_GUI_Translation|GUI Translation Support]]
* [[Supporting_GUI_Translation|GUI Translation Support]] in code
* [[HOWTO-Translate_ScummVM_GUI|Translation HOWTO]] for translation authors
* [[GUI Themes/TODO|GUI TODO]]
* [[GUI Themes/TODO|GUI TODO]]
== Networking ==
* [[Cloud Storage Support | Cloud Storage Support]]
* [[Local Webserver | Local Webserver]]


== Release Management ==
== Release Management ==
* Our release guideline for ScummVM [[HOWTO-Release |Release HOWTO]]
* Our release guideline for ScummVM [[HOWTO-Release |Release HOWTO]]
* Our release testing status for the latest stable release [[Release_Testing |Release Testing]]
* Our release testing status for the latest stable release [[Release_Testing |Release Testing]]
* Anyone who wishes to bundle ScummVM with games for legal commercial and non-commercial release should read the notes [[Bundling_ScummVM|here]].


== CVS/SVN statistics ==
== Code statistics ==
Our commit logs are fed to several freely available statistics tools:
Our commit logs are fed to several freely available statistics tools:
* [http://fisheye3.cenqua.com/browse/scummvm/ FishEye SVN statistics]
* [https://www.openhub.net/p/113 OpenHub project analysis] nice graphs and devs activity
* [http://fisheye1.cenqua.com/browse/scummvm/ FishEye CVS statistics] prior to Feb 6th, 2006
* [http://cia.vc/stats/project/ScummVM CIA.vc statistics], current development
* [http://cia.vc/stats/project/ScummVM CIA SVN statistics], current development
* [http://github.com/scummvm GitHub page], current development on github
* [http://www.ohloh.net/projects/113 ohloh project analysis] nice graphs and devs activity
* [http://www.koders.com/info.aspx?c=ProjectInfo&pid=GGWGLGR5Z5XF9MGEE816ZHSGTB Koders statistics]


== Team Member Benefits ==
== Team Member Benefits ==
Every active ScummVM Team member is eligible for enhanced access to our [[Project Services]] and some further benefits:
Every active ScummVM Team member is eligible for enhanced access to our [[Project Services]] and some further benefits:
* being added to our main credits (do it by yourself in scummvm/tools/credits.pl)
* being added to our main credits (do it by yourself in scummvm/devtools/credits.pl)
* @scummvm.org forwarding address
* @scummvm.org forwarding address
* operator status in our [[IRC Channel]] #scummvm @ freenode
* operator status in our [[IRC Channel]] #scummvm @ freenode
Line 66: Line 98:
* using project donations for purchasing necessary things for the development, such as game copies, software licenses, etc.
* using project donations for purchasing necessary things for the development, such as game copies, software licenses, etc.


If you need any of the above, talk to [[User:Fingolfin|Fingolfin]] or [[User:Sev|sev]].
If you need any of the above, talk to [[User:Sev|sev]].
 
If you do admin tasks e.g. responding to bugs, moderating the forums, you should read the Admin HOWTO [[HOWTO-Admin|here]] for tips and guidelines on doing this.


== Misc ==
== Misc ==
* [http://www.w3schools.com/media/media_mimeref.asp MIME types], useful for setting the svn:mime-type.
* List of [[Defines]] used in the source code.
* Documentation on how we performed our [[CVS2SVN|CVS to Subversion]] conversion.
* Documentation on how we performed our [[CVS2SVN|CVS to Subversion]] conversion.
* Old page listing [[CVS vs SVN|pros and cons between CVS and SVN]] before the conversion was made.
* Old page listing [[CVS vs SVN|pros and cons between CVS and SVN]] before the conversion was made.
* A guide on submitting [[Screenshots]] for use on our website.
* A guide on submitting [[Screenshots]] for use on our website.

Revision as of 19:51, 21 March 2017

The purpose of this page is to give a link to all kinds of resources that contain information valuable to current and future developers of ScummVM.

Getting started

That was easy, right? Here are some more tips:

  • Some hints on debugging ScummVM.
  • Before you write/submit code, you must read our Code Formatting Conventions.
    Patches which do not follow them will be rejected or at least delayed until they are cleaned up to comply to them.
  • Also, you should read and respect the general Coding Conventions.
  • If you have write (push) access to our repository, you are expected to have read and to comply with our Commit Guidelines.
    Also, please read the tips for using Git here: Git tips.
    In particular, note the use of feature branches, when working on refactoring or other large connected changes, rather than committing directly to scummvm/master.
  • If you do not have write (push) access to our repository, you should submit your contributions by one of the following methods:
    • Using a Github Pull Request.
      This requires you to have/register a github account, fork our repository, commit your changes to a branch and then issue a Pull Request.
      This is the current preferred method as it is easier for the team to review, discuss and amend prior to merging.
      You are expected to have read and to comply with our Commit Guidelines.
    • Using the patch tracker.
      This requires you to have/register a github account, and generate a patch file, but this may be easier for developers unfamilar with Git or for small single commit changes, where a Pull Request might be considered overkill.
    • If neither of the above methods are suitable, individual developers may be willing to accept patches or amended source files by other methods i.e. e-mail, but please ask in the project IRC channel or by e-mail before doing this.
  • Our Doxygen source code documentation may help you to get the big picture about ScummVM.
  • Also, you might want to check our list for current Platform Limitations.

Pull Request approval process

The current procedure is as follow:

  1. For a sizeable, significant changes it is advised to make a Pull Request on GitHub.
  2. Such Pull Request will have to stay for at least 2 weeks open for the comments.
  3. Everyone is invited to comment and review and voice their opinion (views of non-team members are valuable, but have no decisive power).
  4. If there are no unaddressed objections after 2 weeks, the PR could be merged. Exception could be made if there are suggestions over refactoring or tidying up the code, granted that they will be addressed in-tree.
  5. Immediately after the merge the PR maker ensures that the buildbot stays happy and is not worsened (historically we had few ports broken for months).

The definition of what makes a sizeable changes not cast in stone. This is up to the discretion of the PR creator, but normally we would expect that anything which breaks existing OSystem API and the Common code, or significantly extends these, especially if it requires more work from the Porters, should go via a Pull Request process. The goal is to ensure that everything stays maintainable.

Any developer is free to open a PR for less significant changes, and that process could be used for facilitating the discussion and collecting feedback, but when there are no big changes involved, no 2 weeks timeout is enforced.

Individual engine sub-teams decide by themselves on the process. For example currently the SCI development is performed via PRs as well for any sizeable changes. It is up to that sub-team to drop this rule any time or make something even stricter. Just make sure you continue enjoying hacking the ScummVM code.

For Engine authors

  • If you want to provide a new Engine for ScummVM, check out our Engines HOWTO.
  • If you work on a game engine for ScummVM, consider implementing Advanced Engine Features.
  • If your engine supports multiple games / game variants, properly detecting and differentiating them all can be a nuisance. Use the Advanced Detector to overcome this hurdle.
  • Accessing files in a portable fashion is non-trivial. Read all about how to open files.
  • Debugging endian issues can be tricky. This page gives some solutions.
  • If you want to have your engine merged into the ScummVM mainline, check out our Engine Inclusion HOWTO.
  • For those starting out with reverse engineering, check out our Reverse Engineering HOWTO.
  • Apart from git bisection to locate regressions in gameplay, the (experimental) Event Recorder provides a framework for recording and replaying gameplay to detect regressions.
  • For some general suggestions on developing engines, see the Engine Development Tips & Tricks

For Backend authors

  • If you want to port ScummVM to a new platform, check out our Backends HOWTO.
  • The Dynamic Modules HOWTO describes how to implement loadable modules on a smaller backend, even without operating system support.

For Web site maintainers

If you want to update the main web site:

  • Update the files you want in the scummvm-web project
  • Trigger http://www.scummvm.org/site-update/ URL. (Ask sev for an account)
  • This is also covered in more detail by the relevant section of the Admin HOWTO here.

Projects, plans, things to do

We are usually happy to receive any kind of help with the things listed below.

  • List of open tasks, with relatively detailed descriptions, and contact points. Some rather small ones, some bigger ones, take a look. GSoC Ideas also has some ideas, intended for students applying for Google's Summer of Code.
  • Main TODO list (contains links to many further specialized TODO pages, e.g. for specific engines).
  • Our bug tracker lists bugs that need to be resolved and also lists features requested by all kinds of people.

The following are partially outdated, but kept for now for the sake of reference.

New GUI

Our "new" GUI is themeable and translatable. If you are interested in writing a custom theme, the following may be of help for you:

Networking

Release Management

  • Our release guideline for ScummVM Release HOWTO
  • Our release testing status for the latest stable release Release Testing
  • Anyone who wishes to bundle ScummVM with games for legal commercial and non-commercial release should read the notes here.

Code statistics

Our commit logs are fed to several freely available statistics tools:

Team Member Benefits

Every active ScummVM Team member is eligible for enhanced access to our Project Services and some further benefits:

  • being added to our main credits (do it by yourself in scummvm/devtools/credits.pl)
  • @scummvm.org forwarding address
  • operator status in our IRC Channel #scummvm @ freenode
  • address cloak on freenode (in form of scummvm/undead/nick)
  • moderator status on ScummVM Forums and appropriate badge "ScummVM Developer" or "ScummVM Porter" or special one
  • ScummVM Wiki account
  • having development blog displayed on ScummVM Planet
  • using project donations for purchasing necessary things for the development, such as game copies, software licenses, etc.

If you need any of the above, talk to sev.

If you do admin tasks e.g. responding to bugs, moderating the forums, you should read the Admin HOWTO here for tips and guidelines on doing this.

Misc