Howto:Submit patches: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
m (Corrected link to mailing-list archives.)
m (moved Howto: Submit patches to Howto:Submit patches: Robot: Moved page)
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
=== Patch Guidelines ===
== Guidelines ==
 
Any invasive or non-trivial patches should preferably adhere to the following recommendations:
Any invasive or non-trivial patches should preferably adhere to the following recommendations:


* Search the [http://sourceforge.net/mailarchive/forum.php?forum_name=flightgear-devel flightgear-devel list archives] ([http://www.flightgear.org/mail.html old]) for any relevant discussion and then post to the flightgear-devel [[mailing list]] describing your idea and discussing the scope of effort required.
* Search the [http://sourceforge.net/mailarchive/forum.php?forum_name=flightgear-devel flightgear-devel list archives] ([http://www.flightgear.org/mail.html old]) for any relevant discussion and then post to the flightgear-devel [[mailing list]] describing your idea and discussing the scope of effort required.
 
* If you have developed several different features, make sure '''not''' to provide one big patch for all of these changes, but instead several smaller ones for each individual feature (likewise, use separate threads on the mailing list as well), that way you will enable developers to easily and independently review/discuss your patches [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg16986.html].
* if you have developed several different features, make sure '''not''' to provide one big patch for all of these changes, but instead several smaller ones for each individual feature (likewise, use separate threads on the mailing list as well), that way you will enable developers to easily and independently review/discuss your patches [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg16986.html].


* Try to make your patch optionally minimally invasive:
* Try to make your patch optionally minimally invasive:
** provide compile time switches to generally enable or disable your modifications (i.e. using #ifdefs, [http://sources.redhat.com/autobook/ autoconf and automake] macros) That way, you will ensure that your patch can be easily disabled (excluded from compilation while remaining in the source tree) if it should cause trouble while any issues are addressed. This applies in particular if your patch introduces any extra dependencies (i.e. libraries) or is any way platform specific.
** provide compile time switches to generally enable or disable your modifications (i.e. using #ifdefs, [http://sources.redhat.com/autobook/ autoconf and automake] macros) That way, you will ensure that your patch can be easily disabled (excluded from compilation while remaining in the source tree) if it should cause trouble while any issues are addressed. This applies in particular if your patch introduces any extra dependencies (i.e. libraries) or is any way platform specific.
** provide capabilities to enable or disable your code modifications at startup time or even at runtime, using command line options (check out $FG_SRC/Main/options.cxx) or preferably the PropertyTree/SGPropertyListeners and some simple GUI dialog (check out $FG_ROOT/gui) to enable developers and users to decide whether they want to activate your code. That way, it can be ensured that your code doesn't interfere with any other FlightGear components. This will make potential bug tracking much easier and the chances of your code remaining in the source tree are much better as well.
** provide capabilities to enable or disable your code modifications at startup time or even at runtime, using command line options (check out $FG_SRC/Main/options.cxx) or preferably the PropertyTree/SGPropertyListeners and some simple GUI dialog (check out $FG_ROOT/gui) to enable developers and users to decide whether they want to activate your code. That way, it can be ensured that your code doesn't interfere with any other FlightGear components. This will make potential bug tracking much easier and the chances of your code remaining in the source tree are much better as well.
** if you intend to add new features that may benefit from proper documentation, make sure to also provide patches to the documentation files provided under $FG_SRC/mini-docs and $FG_ROOT/Docs
** if you intend to add new features that may benefit from proper documentation, make sure to also provide patches to the documentation files provided under $FG_SRC/mini-docs and $FG_ROOT/Docs
** new command line switches should also be documented via options.xml
** new command line switches should also be documented via options.xml
Line 23: Line 21:
* If you need to print output to the terminal, make sure to use the SG_LOG logging mechanism, using the appropriate log level. Use this command sparingly, as excessive logging information has negative impact on framerate, especially on some platforms (you can however easily use switches to generally enable/disable output of debugging information). When committing a patch, make sure you have either removed or commented out any cout or cerr statements that you have used during private debugging sessions.
* If you need to print output to the terminal, make sure to use the SG_LOG logging mechanism, using the appropriate log level. Use this command sparingly, as excessive logging information has negative impact on framerate, especially on some platforms (you can however easily use switches to generally enable/disable output of debugging information). When committing a patch, make sure you have either removed or commented out any cout or cerr statements that you have used during private debugging sessions.


=== Patch Format ===
== Howto create and share patches ==
TODO:  unified diff vs. tarball (compressed archives)
{{Main article|Merge request}}
 
=== Howto Create Patches ===
 
'''fg-submit script'''
 
As of March 2007, a bash script "fg-submit" is available that simplifies the preparation of patches that are to be submitted for commit. It can be found in '/source/scripts/tools'.  It compares your changes to cvs, creates a diff file and an archive containing your changed files and the diff file. Run this script from within the CVS directory containing your changes. It's output will go to that same directory.
 
fg-submit should work with any flavor of Unix/Linux. Windows users may use this script from within a Cygwin bash shell, assuming the necessary Devel tools have been installed.
 
Usage:
 
$ cd $FG_ROOT/Aircraft/foo
 
$ fg-submit
 
'''TODO:'''
 
links to diff/patch tutorials
link to diff/patch utilities for various platforms
 
recommended: KDiff3 (QT based cross platform, GUI frontend to GNU diff/patch)
http://kdiff3.sourceforge.net
 
=== Where to Send Patches ===
 
'''Developers with CVS access :'''
 
'''FlightGear developer mailing list(subscription required)'''
 
(any non-trivial or larger patches should preferably not be sent by email, but rather made available by putting a tarball of your patch on some free webspace, so that people can simply download your patch if they are interested.
 
'''Note''':The FlightGear project's sourceforge site [http://sourceforge.net/projects/flightgear] also provides a simple patch tracking facility [http://sourceforge.net/tracker/index.php?func=detail&aid=1547559&group_id=583&atid=300583], which is easy and intuitive to use and doesn't require any complicated sign up process. While this facility is not yet being used regularly by the project, it may still help you making your patches and code easily accessible.


[[Category:Development]]
[[Category:Development]]

Latest revision as of 16:53, 6 May 2012

Guidelines

Any invasive or non-trivial patches should preferably adhere to the following recommendations:

  • Search the flightgear-devel list archives (old) for any relevant discussion and then post to the flightgear-devel mailing list describing your idea and discussing the scope of effort required.
  • If you have developed several different features, make sure not to provide one big patch for all of these changes, but instead several smaller ones for each individual feature (likewise, use separate threads on the mailing list as well), that way you will enable developers to easily and independently review/discuss your patches [1].
  • Try to make your patch optionally minimally invasive:
    • provide compile time switches to generally enable or disable your modifications (i.e. using #ifdefs, autoconf and automake macros) That way, you will ensure that your patch can be easily disabled (excluded from compilation while remaining in the source tree) if it should cause trouble while any issues are addressed. This applies in particular if your patch introduces any extra dependencies (i.e. libraries) or is any way platform specific.
    • provide capabilities to enable or disable your code modifications at startup time or even at runtime, using command line options (check out $FG_SRC/Main/options.cxx) or preferably the PropertyTree/SGPropertyListeners and some simple GUI dialog (check out $FG_ROOT/gui) to enable developers and users to decide whether they want to activate your code. That way, it can be ensured that your code doesn't interfere with any other FlightGear components. This will make potential bug tracking much easier and the chances of your code remaining in the source tree are much better as well.
    • if you intend to add new features that may benefit from proper documentation, make sure to also provide patches to the documentation files provided under $FG_SRC/mini-docs and $FG_ROOT/Docs
    • new command line switches should also be documented via options.xml
  • Try to carefully document those passages in your source code that:
    • are non-obvious or unfinished
    • are hackish or workarounds
    • use code where you yourself aren't entirely sure if you're doing the right thing
    • are known to negatively interfere with other FlightGear code
    • seem to affect overall runtime performance of FlightGear
  • Try to make sure that your code isn't platform-specific. Hence, it is generally a good idea to make any contributions as cross-platform capable as possible
  • If you need to print output to the terminal, make sure to use the SG_LOG logging mechanism, using the appropriate log level. Use this command sparingly, as excessive logging information has negative impact on framerate, especially on some platforms (you can however easily use switches to generally enable/disable output of debugging information). When committing a patch, make sure you have either removed or commented out any cout or cerr statements that you have used during private debugging sessions.

Howto create and share patches

1rightarrow.png See Merge request for the main article about this subject.