Submitting code to OpenSim
From OpenSimulator
| (29 intermediate revisions by 6 users not shown) | |||
| Line 1: | Line 1: | ||
| − | + | __NOTOC__ | |
| + | {{Quicklinks}} | ||
| + | <br /> | ||
| − | + | == Overview == | |
| − | + | '''Before you begin, please review our [[Contributions Policy]]'''. | |
| − | '' | + | Not all patches will make it into OpenSimulator. To keep a lid on code complexity, OpenSimulator is not trying to be a 'batteries included' project. Things that can't be considered core functionality are better implements as an external region module. If extra hooks/events are needed to make these work then patches for those are very welcome. |
| − | + | Please review the [[Coding standards]] and stick to them in your patch. The only exception should be if the surrounding code does not conform to these guidelines, in which cases its okay to be consistent with the code already in the file. If a patch does not follow the guidelines we will ask for it to be changed. | |
| − | If you're looking for an initial piece of code to do, the bugs in Mantis are a very good starting point. | + | Please put only one logical change in a patch at a time. Patches that contain more than one logical change tend to be larger, more complex and hence take more time to be applied. At worse, developers will tend not to look at them because it's hard to disentangle all the possible effects. Multiple logical changes can be in a patch if they only affect a single feature (like, for example, the feature the patch enables). |
| + | |||
| + | == Test == | ||
| + | |||
| + | Please run the automated tests (via "nant test" on the command line) before submitting your patch. Patches that add new tests (either to test accompanying patch code or to test existing code) are very welcome. | ||
| + | |||
| + | == Create a Patch File == | ||
| + | |||
| + | Code is submitted to OpenSimulator via patches attached to entries in our [http://opensimulator.org/mantis/my_view_page.php Mantis bug tracker]. One way to generate these is by using the Git command line. | ||
| + | |||
| + | git format-patch <commit hash>^! | ||
| + | |||
| + | This will package up all your git commit changes into a nice easily applicable file. | ||
| + | |||
| + | Alternatively, if you have a specific commit, or range of commits, that you want to include in the patch, then run this command: | ||
| + | |||
| + | git format-patch -<num> <newest commit hash> | ||
| + | |||
| + | For example, if your commit hash is a30f224, and you want the patch to include only this one commit, then you would use this command: | ||
| + | |||
| + | git format-patch -1 a30f224 | ||
| + | |||
| + | If your patch includes several sequential commits then <num> would be the number of commits, and the commit hash would be the newest commit. | ||
| + | |||
| + | == Submit the Patch == | ||
| + | |||
| + | Submit the patch by attaching it to an entry in Mantis. | ||
| + | * If you're creating a new entry then the title line should start with [PATCH]. | ||
| + | * Once you've submitted your patch please move the Mantis entry into the '''Patch Included''' state to let us know there's a patch waiting to be reviewed. It might take a bit longer to see a mantis entry with a patch if it's not in this state (and in unfortunate rare cases it may be missed altogether for a period). | ||
| + | |||
| + | Once you've put it on a Mantis, you may want to hop on the IRC channels and mention it someone there (though at the moment we're pretty good at getting round to these, since e-mails about newly opened mantis entries are sent to developers automatically). | ||
| + | |||
| + | General turnaround time for patch review is a week. though, it could be up to two weeks depending on the situation. If you want to chat about a patch (or remind people that it exists after a week has gone by), please feel free to pop into #opensim-dev on IRC or send an e-mail to the opensim-dev ailing list. | ||
| + | |||
| + | When a patch is reviewed, it will either be applied (in which case, thanks very much!) or the Mantis entry will be changed to the "Patch feedback" state with comments from developers/interested parties. If you revise the patch in light of the discussion, please then change the state back to "Patch Included". | ||
| + | |||
| + | == Helping Out == | ||
| + | |||
| + | If you're looking for an initial piece of code to do, the bugs in Mantis are a very good starting point. You may want to see if there's anybody on IRC to discuss the difficulty of a particular bug (they do vary, sometimes in unexpected ways). | ||
| + | |||
| + | [[Category:Development]] | ||
Latest revision as of 12:17, 21 August 2015
[edit] Overview
Before you begin, please review our Contributions Policy.
Not all patches will make it into OpenSimulator. To keep a lid on code complexity, OpenSimulator is not trying to be a 'batteries included' project. Things that can't be considered core functionality are better implements as an external region module. If extra hooks/events are needed to make these work then patches for those are very welcome.
Please review the Coding standards and stick to them in your patch. The only exception should be if the surrounding code does not conform to these guidelines, in which cases its okay to be consistent with the code already in the file. If a patch does not follow the guidelines we will ask for it to be changed.
Please put only one logical change in a patch at a time. Patches that contain more than one logical change tend to be larger, more complex and hence take more time to be applied. At worse, developers will tend not to look at them because it's hard to disentangle all the possible effects. Multiple logical changes can be in a patch if they only affect a single feature (like, for example, the feature the patch enables).
[edit] Test
Please run the automated tests (via "nant test" on the command line) before submitting your patch. Patches that add new tests (either to test accompanying patch code or to test existing code) are very welcome.
[edit] Create a Patch File
Code is submitted to OpenSimulator via patches attached to entries in our Mantis bug tracker. One way to generate these is by using the Git command line.
git format-patch <commit hash>^!
This will package up all your git commit changes into a nice easily applicable file.
Alternatively, if you have a specific commit, or range of commits, that you want to include in the patch, then run this command:
git format-patch -<num> <newest commit hash>
For example, if your commit hash is a30f224, and you want the patch to include only this one commit, then you would use this command:
git format-patch -1 a30f224
If your patch includes several sequential commits then <num> would be the number of commits, and the commit hash would be the newest commit.
[edit] Submit the Patch
Submit the patch by attaching it to an entry in Mantis.
- If you're creating a new entry then the title line should start with [PATCH].
- Once you've submitted your patch please move the Mantis entry into the Patch Included state to let us know there's a patch waiting to be reviewed. It might take a bit longer to see a mantis entry with a patch if it's not in this state (and in unfortunate rare cases it may be missed altogether for a period).
Once you've put it on a Mantis, you may want to hop on the IRC channels and mention it someone there (though at the moment we're pretty good at getting round to these, since e-mails about newly opened mantis entries are sent to developers automatically).
General turnaround time for patch review is a week. though, it could be up to two weeks depending on the situation. If you want to chat about a patch (or remind people that it exists after a week has gone by), please feel free to pop into #opensim-dev on IRC or send an e-mail to the opensim-dev ailing list.
When a patch is reviewed, it will either be applied (in which case, thanks very much!) or the Mantis entry will be changed to the "Patch feedback" state with comments from developers/interested parties. If you revise the patch in light of the discussion, please then change the state back to "Patch Included".
[edit] Helping Out
If you're looking for an initial piece of code to do, the bugs in Mantis are a very good starting point. You may want to see if there's anybody on IRC to discuss the difficulty of a particular bug (they do vary, sometimes in unexpected ways).
