Difference between revisions of "HOW-TO:Submit a patch"

From Official Kodi Wiki
Jump to: navigation, search
(Edited for spelling/grammar and removed a bunch of unnecessary cruft)
Line 1: Line 1:
XBMC is a non-profit open source hobby project that is developed only by volunteers in their spare-time without any monetary gain. The team of developers working on XBMC encurage anyone submit your own source code patches for bug-fixes, new features/functions, improvements to existing ones. All and any help/additions/contributions to the source code are appriciated, and please note that even though we will do our best to look at and give feedback on your code/patch as soon as possible please understand trhat there are no garantees that your patch will be accepted and implemented into XBMC. Please be patient (especially during public holiday periods). Please understand that clean and well documented code will most likely be looked at and implemented sooner than messy and undocumented code.
+
XBMC is a non-profit open source hobby project that is developed by volunteers in their spare time without any monetary gain. The team of developers working on XBMC encourage anyone submit source code patches for bug-fixes, new features/functions or improvements to existing ones. Any and all contributions to the source code are appreciated, though please understand that there is no guarantee that your patch will be accepted and implemented into XBMC. If you wish to have input from XBMC developers prior to implementing a feature or improvement, please open a discussion on the [http://forum.xbmc.org forums]. Lastly, understand that it may take us a little while to review your patch, so please be patient - clean and well documented code will most likely be looked at sooner than messy or undocumented code.
  
:'''Note!''' We know our rules place a burden on you the submitter, but rest assured that maintaining a big and complex software project is even harder, so please accept the rules that have been set before you here. These rules are there for a reason, we cannot afford to spend too much of our time fixing buggy, broken or outdated patches. The closer you follow our rules the higher is the probability that your patch will be included in the XBMC project.
+
:'''Note!''' We know our rules place a burden on you the submitter, but rest assured that maintaining a large, complex software project is even harder, so please accept the rules that have been set before you here. These rules are there for a reason, we cannot afford to spend too much of our time fixing buggy, broken or outdated patches. The closer you follow our rules the higher is the likelihood that your patch will be accepted.
  
 
=Code submittions=
 
=Code submittions=
Please submit it as a "''unified diff''" to the [http://trac.xbmc.org XBMC Tracker (Trac)], see the section below about patch format for information on how to create a unified diff, (please try to avoid to zip/rar it before uploadinging it unless it is absolutly nessesary). Then to get some attention please also post a new topic-thread in the development-section of our community-forums telling everyone about the patch and its functions/features, doing so also allows for a more open discussion with the whole XBMC community including non-developers about possible improvements/enhancements or additions and bugs/fixes. We also really appriciate it if you consent to hand over the ownership (copyright owner) of your code patches to the XBMC Foundation.
+
Please submit all code submissions as a "''unified diff''" to the [http://trac.xbmc.org XBMC Tracker (Trac)] - see the section below for information on how to create a unified diff - and please avoid compressing it prior to uploading unless absolutely necessary. Then to get some attention please also post a new thread in the development-section of our [http://forum.xbmc.org forums] describing the patch. Doing so allows for a more open discussion with the whole XBMC community including non-developers about possible improvements/enhancements or additions and bugs/fixes. Note that any code you submit will be (c) Team XBMC.
  
 
==Minimum requirements==
 
==Minimum requirements==
We currently do not have any other minimum requirements other than the code being under [http://www.gnu.org/licenses/lgpl.html LGPL] or [http://www.gnu.org/copyleft/gpl.html GPL] license and that all/any comments and documentation should be in correct and in English. Clean and well documented ([http://doxygen.org doxygen]) code are also more ''appreciated'' than 'messy' and undocumented code.
+
We currently do not have any other minimum requirements other than the code being under [http://www.gnu.org/licenses/lgpl.html LGPL] or [http://www.gnu.org/copyleft/gpl.html GPL] license, that it is clean and that any comments and documentation be accurate and in English.
  
 
==Code documentation==
 
==Code documentation==
Though unfortunatly not yet a standard in all XBMC source code nor a forced requirement, please try to use [http://www.doxygen.org doxygen] to document your code with inline comments, and if possible please also add a small "''readme.txt''" to the the patch when submitting it if the patch is for a new feature or function, telling people what functions/features it serves and how to apply it so that it will be easier to document that function/feature in this wiki later.
+
Though not yet a standard in all XBMC source code, please try and document at least the "public" portions of your code using [http://www.doxygen.org doxygen] inline comments.  If you are submitting a new feature or function, please also add a small "''readme.txt''" to the the patch describing the use of feature that may be used as a basis for user documentation in the wiki later. You are most welcome to format this up for the wiki after the patch is submitted.
  
 
==Code guide-lines and formatting conventions==
 
==Code guide-lines and formatting conventions==
 
This is still under discussion, so for now please follow or add to the discussion [http://forum.xbmc.org/showthread.php?t=5238 here]. Of course, modular designs (like dynamic or static libraries) are preferred.
 
This is still under discussion, so for now please follow or add to the discussion [http://forum.xbmc.org/showthread.php?t=5238 here]. Of course, modular designs (like dynamic or static libraries) are preferred.
  
All code should strive to be platform agnostic - XBMC is a multi-platform software, thus any single platform specific features should be discussed with other team members before implemented. Major features should be developed in a separate branch or committed in small increments so that other members have the opportunity to review the code and comment on it during development.
+
All code should strive to be platform agnostic - XBMC is multi-platform software, thus any single platform-specific features should be discussed with XBMC team members before being implemented. Major features should ideally be developed in a separate branch or in small increments so that other members have the opportunity to review the code and comment on it during development.
 
 
Please also try try to avoid code duplications as the Xbox hardware-platform which (we still try to stay backwards compatible with whenever possible) is quite resource restrictive.
 
  
 
==Patch format==
 
==Patch format==
Please do not send complete files. These need to be diffed by hand to see the changes, which makes reviews harder and less likely to occur. Besides as soon as one of the files changes, your version becomes harder to apply, thus reducing its chances of being accepted. Please follow these simple rules when making patch for XBMC.
+
Please do not send complete files. These need to be diffed by hand to see the changes, which makes reviews harder and less likely to occur. Besides as soon as one of the files changes, your version becomes harder to apply, thus reducing its chances of being accepted. Please follow these simple rules when making patch for XBMC:
  
 
:'''1.''' Always make patches for Subversion HEAD. We do not accept patches for releases or outdated Subversion revisions.
 
:'''1.''' Always make patches for Subversion HEAD. We do not accept patches for releases or outdated Subversion revisions.
  
:'''2.''' Make unified diff created using e.g. svn diff against head ('svn diff' or 'diff -Naur'). Unified diffs can be applied easily with 'patch'. This is much harder with other diff types. Besides, unified diffs are more readable and thus easier to review. Also, if patch is general in nature, the the diff should preferably be against the trunk (and not a branch).
+
:'''2.''' Make unified diff created using e.g. svn diff against head ('svn diff' or 'diff -Naur'). Unified diffs can be applied easily with 'patch'. This is much harder with other diff types. Unified diffs are more readable and thus easier to review.
  
 
::'''NOTE!''' Please make each patch per feature, (not one patch per source file with multiple features in it).
 
::'''NOTE!''' Please make each patch per feature, (not one patch per source file with multiple features in it).
Line 36: Line 34:
 
::'''TIP!''' If you already wrote some code and did cosmetic changes, you can use 'diff -uwbBE' to help you remove them. Do not forget to check the patch to make sure diff did not ignore some important change and remove any remaining cosmetics! To use these options directly with svn, use this command: ''svn diff --diff-cmd diff -x -uwbBE''
 
::'''TIP!''' If you already wrote some code and did cosmetic changes, you can use 'diff -uwbBE' to help you remove them. Do not forget to check the patch to make sure diff did not ignore some important change and remove any remaining cosmetics! To use these options directly with svn, use this command: ''svn diff --diff-cmd diff -x -uwbBE''
  
:'''6.''' Comment parts that really need it (tricky side-effects etc). Always document string operations! Comment on what you are doing and why it is safe. This makes it easy to review and change your code if needed. Commenting trivial code not required. Comments must be English!
+
:'''6.''' Comment parts that really need it (tricky side-effects etc). Always document string operations! Comment on what you are doing and why it is safe. This makes it easy to review and change your code if needed. Do not comment trivial code. Comments must be English!
 +
 
 +
:'''7.''' If you implement new features or modify the behavior of existing features, please do not forget to also point out whether any changes are required in the wiki documentation, and ideally perform these changes once your patch is accepted.
  
:'''7.''' If you implement new features, add, change, or modify the behavior of existing features, please do not forget to also update the wiki documentation.  
+
:'''8.''' If you make independent changes, please submit them as separate patches in separate patch-tracker item to our XBMC patch-tracker. Likewise, if your patch is very large, try splitting it into several self-contained pieces, so that each part can then be reviewed and committed separately.
  
:'''8.''' If you make independent changes, try to submit them as separate patches in separate patch-tracker item to our XBMC patch-tracker. Likewise, if your patch is very big, try splitting it into several self-contained pieces. Each part can then be reviewed and committed separately. Logical units should stay together, though, i.e. do not send a patch for every file or directory you change.
+
:'''9.''' Upload the patch file directly as an attachment to the [http://trac.xbmc.org Trac ticket] rather than using some other web hosting facility. The fewer steps it takes us to get at the patch, the higher the likelihood of it getingt reviewed and applied. If your patch is so large that you cannot upload it, try splitting it into smaller pieces first, and only if it is absolutely unavoidable use zip to compress it.
  
:'''9.''' Do not upload the patch to a web or FTP site unless it is absolutely no way around it, intsead upload it directly to our XBMC patch-tracker ("Trac") as a unified diff 'as is' without compressing it using zip, rar or similar. The fewer steps it takes us to get at the patch without having to process it first the higher the likelihood for it to get reviewed and applied. If your patch is so big you cannot upload it to the XBMC patch-tracker ("Trac") tricket, try splitting it into smaller pieces first, and only if it is absolutly unavoidable use zip to compress it.
+
:'''10.''' Use a clear title and description in the ticket detailing what the patch is for and (if necessary) why it was done the way it was. If the patch fixes a bug, include the bug number (eg fixes #8479) in the title or description, and add a comment to the bug ticket linking back to the patch.
  
:'''10.''' Give us a few days to react. We try to review patches as fast as possible, but unfortunately we are constantly overloaded with work, be it XBMC-related or from our day to day lives. If your patch seems to be ignored, post a reminder asking for opinions in the forum's development section or as a reply to the original patch on the XBMC patch-tracker ("Trac") and mention that you got ignored. We are interested in your work and will eventually either accept it or reject it with an explanation of what we liked and disliked about your patch. Note that we will often ask you to make changes to your patch to make it acceptable before we commit it, so please implement those changes if you want to see your patch applied and send the update to the original XBMC patch-tracker ("Trac") tricket.
+
:'''11.''' Give us a few days to react. We try to review patches as quickly as possible, but unfortunately we are constantly overloaded with work, be it XBMC-related or from our day to day lives. If your patch seems to be ignored, post a reminder asking for opinions in the forum's development section or as a reply to the original patch ticket, mentioning that you got ignored - we are interested in your work and will eventually either accept it or reject it with an explanation of what we liked and disliked about your patch. Note that we will often ask you to make changes to your patch to make it acceptable before we commit it, so please implement those changes, and attach an updated patch to the ticket. Some of these changes may seem trivial, but the less work we need to do, the faster it'll hit SVN.
  
:'''11.''' Do not immediately ask for Subversion write access. If you have contributed one or more nice, acceptable patches and they need maintaining or you want to be an XBMC developer, you'll get Subversion write access.
+
:'''11.''' Do not immediately ask for Subversion write access. If you have contributed one or more nice, acceptable patches and they need maintaining, we'll come to you.
  
:'''12.''' If you send a modified or updated version of your patch, resend the complete patch. It is very time-consuming and error-prone to piece together patches that are distributed over several files and/or tickets. Please always resend patches as replies to the original XBMC patch-tracker ("Trac") tricket to keep the thread with the discussion together.
+
:'''12.''' If you send a modified or updated version of your patch, resend the complete patch. It is very time-consuming and error-prone to piece together patches that are distributed over several files and/or tickets. Please always resend patches as replies to the original trac ticket to keep the thread with the discussion together.
  
 
=External Links=
 
=External Links=

Revision as of 01:18, 10 January 2010

XBMC is a non-profit open source hobby project that is developed by volunteers in their spare time without any monetary gain. The team of developers working on XBMC encourage anyone submit source code patches for bug-fixes, new features/functions or improvements to existing ones. Any and all contributions to the source code are appreciated, though please understand that there is no guarantee that your patch will be accepted and implemented into XBMC. If you wish to have input from XBMC developers prior to implementing a feature or improvement, please open a discussion on the forums. Lastly, understand that it may take us a little while to review your patch, so please be patient - clean and well documented code will most likely be looked at sooner than messy or undocumented code.

Note! We know our rules place a burden on you the submitter, but rest assured that maintaining a large, complex software project is even harder, so please accept the rules that have been set before you here. These rules are there for a reason, we cannot afford to spend too much of our time fixing buggy, broken or outdated patches. The closer you follow our rules the higher is the likelihood that your patch will be accepted.

1 Code submittions

Please submit all code submissions as a "unified diff" to the XBMC Tracker (Trac) - see the section below for information on how to create a unified diff - and please avoid compressing it prior to uploading unless absolutely necessary. Then to get some attention please also post a new thread in the development-section of our forums describing the patch. Doing so allows for a more open discussion with the whole XBMC community including non-developers about possible improvements/enhancements or additions and bugs/fixes. Note that any code you submit will be (c) Team XBMC.

1.1 Minimum requirements

We currently do not have any other minimum requirements other than the code being under LGPL or GPL license, that it is clean and that any comments and documentation be accurate and in English.

1.2 Code documentation

Though not yet a standard in all XBMC source code, please try and document at least the "public" portions of your code using doxygen inline comments. If you are submitting a new feature or function, please also add a small "readme.txt" to the the patch describing the use of feature that may be used as a basis for user documentation in the wiki later. You are most welcome to format this up for the wiki after the patch is submitted.

1.3 Code guide-lines and formatting conventions

This is still under discussion, so for now please follow or add to the discussion here. Of course, modular designs (like dynamic or static libraries) are preferred.

All code should strive to be platform agnostic - XBMC is multi-platform software, thus any single platform-specific features should be discussed with XBMC team members before being implemented. Major features should ideally be developed in a separate branch or in small increments so that other members have the opportunity to review the code and comment on it during development.

1.4 Patch format

Please do not send complete files. These need to be diffed by hand to see the changes, which makes reviews harder and less likely to occur. Besides as soon as one of the files changes, your version becomes harder to apply, thus reducing its chances of being accepted. Please follow these simple rules when making patch for XBMC:

1. Always make patches for Subversion HEAD. We do not accept patches for releases or outdated Subversion revisions.
2. Make unified diff created using e.g. svn diff against head ('svn diff' or 'diff -Naur'). Unified diffs can be applied easily with 'patch'. This is much harder with other diff types. Unified diffs are more readable and thus easier to review.
NOTE! Please make each patch per feature, (not one patch per source file with multiple features in it).
3. Please create the diff from the root of the XBMC SVN source tree, this makes the diff easier to apply as it saves the step of searching for and changing to the correct directory.
4. Test the functionality of your patch. We'll *refuse* it if it breaks something, even if it extends other features!
5. Read your patch. We may *refuse* it if it changes indentation of the code or if it does tab/space conversion or other cosmetic changes!
TIP! If you already wrote some code and did cosmetic changes, you can use 'diff -uwbBE' to help you remove them. Do not forget to check the patch to make sure diff did not ignore some important change and remove any remaining cosmetics! To use these options directly with svn, use this command: svn diff --diff-cmd diff -x -uwbBE
6. Comment parts that really need it (tricky side-effects etc). Always document string operations! Comment on what you are doing and why it is safe. This makes it easy to review and change your code if needed. Do not comment trivial code. Comments must be English!
7. If you implement new features or modify the behavior of existing features, please do not forget to also point out whether any changes are required in the wiki documentation, and ideally perform these changes once your patch is accepted.
8. If you make independent changes, please submit them as separate patches in separate patch-tracker item to our XBMC patch-tracker. Likewise, if your patch is very large, try splitting it into several self-contained pieces, so that each part can then be reviewed and committed separately.
9. Upload the patch file directly as an attachment to the Trac ticket rather than using some other web hosting facility. The fewer steps it takes us to get at the patch, the higher the likelihood of it getingt reviewed and applied. If your patch is so large that you cannot upload it, try splitting it into smaller pieces first, and only if it is absolutely unavoidable use zip to compress it.
10. Use a clear title and description in the ticket detailing what the patch is for and (if necessary) why it was done the way it was. If the patch fixes a bug, include the bug number (eg fixes #8479) in the title or description, and add a comment to the bug ticket linking back to the patch.
11. Give us a few days to react. We try to review patches as quickly as possible, but unfortunately we are constantly overloaded with work, be it XBMC-related or from our day to day lives. If your patch seems to be ignored, post a reminder asking for opinions in the forum's development section or as a reply to the original patch ticket, mentioning that you got ignored - we are interested in your work and will eventually either accept it or reject it with an explanation of what we liked and disliked about your patch. Note that we will often ask you to make changes to your patch to make it acceptable before we commit it, so please implement those changes, and attach an updated patch to the ticket. Some of these changes may seem trivial, but the less work we need to do, the faster it'll hit SVN.
11. Do not immediately ask for Subversion write access. If you have contributed one or more nice, acceptable patches and they need maintaining, we'll come to you.
12. If you send a modified or updated version of your patch, resend the complete patch. It is very time-consuming and error-prone to piece together patches that are distributed over several files and/or tickets. Please always resend patches as replies to the original trac ticket to keep the thread with the discussion together.

2 External Links