Second Life Wiki - User contributions [en]

Preparing Code

2008-12-22T22:15:25Z

Coco Linden: /* Good Patch Practise */

{{OSWikiContribBox}}

If you have a piece of source code (be it a fix, new feature, or optimization of existing code) submit the patches in a way that makes it easy for the Lindens to incorporate them into the source code.

== Good Patch Practice ==

=== General ===

The people who review and apply patches are the bottleneck in the system. If you can make it easier for Lindens to understand, test and apply your patch without lots of cleanup, Lindens can incorporate more patches in a fixed amount of time.

===Before You Start===

Check [https://jira.secondlife.com/secure/Dashboard.jspa JIRA Bug Tracker] to see if a similar issue has been submitted, and check its status. You will eventually attach to the existing issue if you find one. If your issue is new, it can help to create the issue before starting work so that others can begin voting for the patch. More votes lead to faster incorporation.

If you haven't, don't forget to sign and send in the [http://secondlifegrid.net/programs/open_source/submission contribution agreement]. The sooner you do that, the sooner Lindens can accept your patch. Getting this out of the way early avoids any mailing or processing delays. You only need to do this one time.

=== Coding Standard ===

Please read and follow the coding standard: [[Coding_standard|Second Life coding standard]]

=== Comments ===

Please do not add issue numbers and your name to the code section. These have to be removed by hand. While comments explaining code in a general working context are helpful, bracketing a patch with comments like "// PATCH START" and "// PATCH END" does not add any information, and adds to the manual cleanup Lindens have to do.

In short, add to the patch what is expected to appear in the final source.

=== Give Yourself Credit! ===

While names and JIRAs shouldn't appear in source, they do belong in doc/contributions.txt. Please don't be shy about adding the issue label and adding your name. We use this file for a number of purposes, including the generation of the [[Source contributions]] page. This also helps Lindens track the purpose of a given patch file.

=== One Patch for one Issue ===

Each patch should do exactly one thing. If you have three different bugs to fix, please submit three different patches. When you fold unrelated hunks into a single patch, Lindens have to try to figure out which part of the patch applies to which bug, and split it out by hand, usually into several patches. Combo patches are particularly time consuming, and the manual splitting up makes it very easy to lose pieces of patches altogether.

=== Less is more ===

Smaller patches are easier to review and therefore more likely to be integrated quickly. The longer it takes for a patch to be incorporated, the higher the likelihood that the underlying code will change enough for the patch to fail. Please do not include formatting or other clean-up changes. These make a patch harder to review and more likely to fail.

=== Path structure ===

It's best practice for your patch to be made on the directory level where the linden folder resides so that the path/file names in your patch will start with '''linden/'''. If you are working from a SVN, a diff in SVN style starting from the '''indra''' directory level [https://lists.secondlife.com/pipermail/sldev/2008-May/009568.html is also fine].

=== Additional Suggestions ===

Getting your patches accepted into open source projects is a bit of an art. The Red Hat Linux project contains [http://et.redhat.com/~rjones/how-to-supply-code-to-open-source-projects/ some excellent tips] that you may find to be helpful.

== Creating a Patch ==

Patches should be submitted in unified diff format. This format is similar to simple diffs, but with more detailed information, and it can be automatically integrated into the source. You can generate a unified diff by calling ''diff -u <original file> <new file>'' (under Windows you will find the diff command as part of the CygWin project in C:\CYGWIN\BIN).

Please submit a single plain text uncompressed patch file that affects all of the files you need to modify. This is far easier to review than a collection of tiny one-file patches.

Also bad for reviewability are a compressed patch, or a tarball or zip containing one or more patches.

=== Unified diff of all changed files in a folder tree ===
The easiest way to generate a clean patch is to keep two copies of the source tree. Leave one completely unmodified, and make all of your changes in the second. Then use "diff -urN" to generate the patch. You can use the --exclude option to omit unwanted files. For example:

diff -urN --exclude="*.o" my_untouched_tree my_modified_tree

=== Unified diff of multiple files ===
If for any reason you can not use a whole tree diff as above, you can still merge patches from different files into one, by appending the output of patch commands to the previous output (via '''>>''' redirection for the 2nd and later commands).

diff -u linden-untouched/indra/newview/viewer.h linden/indra/newview/viewer.h >mychanges.patch.txt
diff -u linden-untouched/indra/newview/viewer.cpp linden/indra/newview/viewer.cpp '''>>'''mychanges.patch.txt
diff -u linden-untouched/indra/newview/llviewerwindow.cpp linden/indra/newview/llviewerwindow.cpp '''>>'''mychanges.patch.txt

<br/>

=== CR/LF vs LF and Whitespace===
In some situations, you will find that the patch contains the whole file, rather than just the lines changed. The reason is that sometimes, files in Linux format find their way into the source distribution. With these diff.exe will treat all lines as different from those in your modified file.

There are various options that will help here. You can add ''--strip-trailing-cr'' to the command line to fix this.

diff -u --strip-trailing-cr linden-untouched/indra/newview/viewer.h linden/indra/newview/viewer.h >mychanges.patch.txt

In some situations try the '''w''' (ignore whitespace) and/or '''B''' (ignore empty lines) options are also helpful (e.g. with tabs vs. space or spurious space characters while editing). Type '''diff --help''' for more details.

<br/>

=== Sample output ===
For reference, here's what a unified diff looks like.

--- linden-untouched/indra/newview/viewer.cpp 2007-05-14 16:47:26.000000000 +0200
+++ linden/indra/newview/viewer.cpp 2007-05-22 08:49:50.484375000 +0200
@@ -6302,7 +6326,7 @@

llinfos << "Cleaning Up" << llendflush;

- LLKeyframeMotion::flushKeyframeCache();
+ LLKeyframeMotion::flushKeyframeCache(TRUE);

// Must clean up texture references before viewer window is destroyed.
LLHUDObject::cleanupHUDObjects();
@@ -6562,6 +6586,8 @@
delete gVFS;
gVFS = NULL;

+ LLCurl::cleanup();
+
// This will eventually be done in LLApp
LLCommon::cleanupClass();
}

== Submitting the Patch on JIRA ==

When you are ready for the world to view your patch, submit the patch on the [https://jira.secondlife.com/secure/Dashboard.jspa| JIRA Bug Tracker]. Create a new issue or attach the patch to an existing entry as appropriate. Attach the ''.patch.txt'' file itself as a file attachment and make sure that the check mark for ''Patch attached'' is set (you can do that when creating the issue or by choosing Edit for an existing one). Along with your patch, it helps to provide a brief description explaining your patch from an implementor's view. Non-trivial patches benefit form a simple review plan naming what systems were affected and describing what peers can do to verify that the patch works and doesn't break surrounding systems. Very often, you will find that writing only a few lines will give you pause and make you double-check some code.

For all but the most trivial patches, it is a good idea to submit the patch for peer review on the [[Developer_communication_tools|mailing list]]. This way fellow developers can review the patch, uncover possible bugs, comment on undesired interactions or generally share ideas with you. Subscribe to the mailing list, then write an email to the list with a link to the description of what your patch does.

Good luck!

== Applying patches to your source ==

In case you are interested, the application of other patches to your source is easy. Assuming that you are at the directory level from where the patch references the files (usually in the folder where you see the '''linden''' folder), applying a patch can be done via:

c:\cygwin\bin\patch -p 0 -i changes.patch

or

c:\cygwin\bin\patch -p 0 < changes.patch

On your first attempts, you might also be interested in the '''--verbose''', '''--backup''' or '''--dry-run''' (simulate patch) options. See '''patch --help''' for details.

c:\cygwin\bin\patch -p 0 --verbose --backup --dry-run -i changes.patch

Also, if a patch fails, look for files ending with '''.rej''' in the target folder.

All keyboard shortcut keys

2008-09-05T06:52:14Z

Coco Linden:

This page contains a comprehensive list of keyboard shortcut keys in the Second Life Viewer, even ones that are rarely used.

For a list of only the most commonly-used keyboard shortcut keys, see [[Keyboard shortcut keys]].

== Menus ==

=== File ===

Ctrl-U --> File > Upload Image...
Ctrl-W --> File > Close Window
Ctrl-Shift-W --> File > Close All Windows
Ctrl-Shift-S --> File > Take or Refresh Snapshot
Ctrl-` --> File > Snapshot to Disk
Ctrl-Q --> File > Quit

=== Edit ===

Ctrl-Z --> Edit > Undo
Ctrl-Y --> Edit > Redo
Ctrl-X --> Edit > Cut
Ctrl-C --> Edit > Copy
Ctrl-V --> Edit > Paste
Del --> Edit > Delete
Ctrl-F --> Edit > Search...
Ctrl-A --> Edit > Select All
Ctrl-E --> Edit > Deselect
Ctrl-D --> Edit > Duplicate
Ctrl-G --> Edit > Gestures...
Ctrl-Shift-F --> Edit > Friends...
Ctrl-P --> Edit > Preferences...

=== View ===

M --> View > Mouselook
B --> View > Build
Alt-Shift-F --> View > Joystick Flycam
Esc --> View > Reset View
Ctrl-\ --> View > Look at Last Chatter
Ctrl-H --> View > Local Chat
Ctrl-T --> View > Communicate
Ctrl-I --> View > Inventory
Ctrl-M --> View > World Map
Ctrl-Shift-M --> View > Mini-Map
Ctrl-Shift-1 --> View > Statistics Bar
Ctrl-Alt-Shift-P --> View > Property Lines
Ctrl-Shift-T --> View > Hover Tips > Show Tips
Ctrl-Alt-T --> View > Highlight Transparent
Ctrl-Alt-Shift-N --> View > Beacons
Ctrl-Alt-Shift-= --> View > Particle Sources
Alt-Shift-H --> View > Show HUD Attachments
Ctrl-0 --> View > Zoom In
Ctrl-9 --> View > Zoom Default
Ctrl-8 --> View > Zoom Out
Alt-Enter --> View > Toggle Fullscreen

=== World ===

Enter --> World > Chat
Ctrl-R --> World > Always Run
Home --> World > Fly
Ctrl-Shift-H --> World > Teleport Home

Ctrl-Shift-Y --> World > Environment Settings > Midday
Ctrl-Shift-N --> World > Environment Settings > Sunset

=== Tools ===

Ctrl-1 --> Tools > Select Tool > Focus
Ctrl-2 --> Tools > Select Tool > Move
Ctrl-3 --> Tools > Select Tool > Edit
Ctrl-4 --> Tools > Select Tool > Create
Ctrl-5 --> Tools > Select Tool > Land

G --> Tools > Snap to Grid
Shift-X --> Tools > Snap Object XY to Grid
Shift-G --> Tools > Use Selection for Grid
Ctrl-Shift-B --> Tools > Grid Options...
Ctrl-L --> Tools > Link
Ctrl-Shift-L --> Tools > Unlink
H --> Tools > Focus on Selection
Shift-H --> Tools > Zoom to Selection

=== Help ===

F1 --> Help > Second Life Help

=== Advanced ===

Ctrl-Shift-2 --> Advanced > Consoles > Frame Console
Ctrl-Shift-3 --> Advanced > Consoles > Texture Console
Ctrl-Shift-4 --> Advanced > Consoles > Debug Console
Ctrl-Shift-9 --> Advanced > Consoles > Fast Timers
Ctrl-Shift-0 --> Advanced > Consoles > Memory

Ctrl-Shift-F2 --> Advanced > Reload personal settings overrides

Ctrl-Alt-Shift-1 --> Advanced > Rendering > Types > Simple
Ctrl-Alt-Shift-2 --> Advanced > Rendering > Types > Alpha
Ctrl-Alt-Shift-3 --> Advanced > Rendering > Types > Tree
Ctrl-Alt-Shift-4 --> Advanced > Rendering > Types > Character
Ctrl-Alt-Shift-5 --> Advanced > Rendering > Types > SurfacePatch
Ctrl-Alt-Shift-6 --> Advanced > Rendering > Types > Sky
Ctrl-Alt-Shift-7 --> Advanced > Rendering > Types > Water
Ctrl-Alt-Shift-8 --> Advanced > Rendering > Types > Ground
Ctrl-Alt-Shift-9 --> Advanced > Rendering > Types > Volume
Ctrl-Alt-Shift-0 --> Advanced > Rendering > Types > Grass
Ctrl-Alt-Shift-- --> Advanced > Rendering > Types > Clouds
Ctrl-Alt-Shift-= --> Advanced > Rendering > Types > Particles
Ctrl-Alt-Shift-\ --> Advanced > Rendering > Types > Bump

Ctrl-Alt-F1 --> Advanced > Rendering > Features > UI
Ctrl-Alt-F2 --> Advanced > Rendering > Features > Selected
Ctrl-Alt-F3 --> Advanced > Rendering > Features > Highlighted
Ctrl-Alt-F4 --> Advanced > Rendering > Features > Dynamic Textures
Ctrl-Alt-F5 --> Advanced > Rendering > Features > Foot Shadows
Ctrl-Alt-F6 --> Advanced > Rendering > Features > Fog
Ctrl-Alt-F7 --> Advanced > Rendering > Features > Palletized Textures
Ctrl-Alt-F8 --> Advanced > Rendering > Features > Test FRInfo
Ctrl-Alt-F9 --> Advanced > Rendering > Features > Flexible Objects

Ctrl-Alt-Shift-T --> Advanced > Rendering > Selected Texture Info
Ctrl-Shift-R --> Advanced > Rendering > Wireframe
Ctrl-Shift-O --> Advanced > Rendering > Object-Object Occlusion

Ctrl-Alt-F --> Advanced > UI > Dump Focus Holder
Ctrl-Shift-P --> Advanced > UI > Print Selected Object Info
Shift-P --> Advanced > UI > Print Agent Info
Ctrl-Alt-Shift-M --> Advanced > UI > Memory Stats

Ctrl-Alt-R --> Advanced > Character > Rebake Textures

Ctrl-Alt-L --> Advanced > Network > Drop a Packet

Ctrl-Alt-Shift-U --> Advanced > Show Updates
Ctrl-Alt-V --> Advanced > View Admin Options
Ctrl-Alt-G --> Advanced > Request Admin Status
Ctrl-Alt-Shift-G --> Advanced > Leave Admin Status

=== Admin ===

Ctrl-Alt-Shift-O --> Admin > Object > Take Copy
Ctrl-Alt-Shift-Del --> Admin > Object > Delete
Ctrl-Alt-Shift-L --> Admin > Object > Lock
Ctrl-Alt-Shift-I --> Admin > Object > Get Asset IDs

Ctrl-Alt-Shift-C --> Admin > Parcel > Set to Linden Content

== Other ==

Ctrl-Alt-Shift-H --> Hippos!

Preparing Code

2007-06-07T01:59:44Z

Coco Linden: /* Good Patch Practise */

{{OSWikiContribBox}}

If you have a piece of source code (be it a fix or a new feature) submit the patches in a way that makes it easy for the Lindens to incorporate them into the source code.

== Good Patch Practise ==

=== General ===

The best way to think about patches is that the people who are reviewing and applying your patches are the bottleneck in the system. If you can make it easier for us to understand and apply patches without lots of cleanup, we can spend more time reviewing and incorporating your work.

=== Coding Standard ===

Please read and follow the coding standard: [[Coding_standard|Second Life coding standard]]

=== Comments ===

Please do not add issue numbers or your name to patches. We have to remove these by hand. Also, please be careful in how you add comments. Bracketing a patch with comments like "// PATCH START" and "// PATCH END" does not add any information, and adds to the manual cleanup we have to do.

If you want to make sure you get credited, then
add yourself to doc/contributions.txt as part of the patch. That makes
it easier for people to see the exact nature of the changes you've added.

In short, just add to the patch what is expected to appear in the final source.

=== One Patch for one Issue ===

Each patch should do exactly one thing. If you have three different bugs to fix, please submit three different patches. When you fold unrelated hunks into a single patch, we have to try to figure out which part of the patch applies to which bug, and split it out by hand, sometimes into several patches. Combo patches are particularly time consuming, and the manual splitting up makes it very easy to lose pieces of patches altogether.

=== Less is more ===

Smaller patches are easier to review and therefore more likely to be integrated quickly. The longer it takes for a patch to be incorporated, the higher the likelihood that the underlying code will change enough for the patch to fail. Please do not include formatting or other clean-up changes as that makes it harder to review and more likely to fail.

== Creating a Patch ==

Patches should be submitted in Unidiff-Format. This format is simlar to simple diffs but with more detailed information and can be automatically integrated into the source. It is generated by calling ''diff -u <original file> <new file>'' (under Windows you will find the diff command as part of the CygWin project in C:\CYGWIN\BIN).

With the file names it is best to rename the original file to something like ''viewer_orig.cpp'' have the new file the same name as in the Second Life project and redirect the output to a file that ends with ''.patch''

The patch command for a change viewer.cpp would then be something like ''diff -u --strip-trailing-cr linden/indra/newview/viewer_orig.cpp linden/indra/newview/viewer.cpp >viewer.patch'' and would create output file named ''viewer.patch'' like this:

--- linden/indra/newview/viewer_orig.cpp 2007-05-14 16:47:26.000000000 +0200
+++ linden/indra/newview/viewer.cpp 2007-05-22 08:49:50.484375000 +0200
@@ -6302,7 +6326,7 @@

llinfos << "Cleaning Up" << llendflush;

- LLKeyframeMotion::flushKeyframeCache();
+ LLKeyframeMotion::flushKeyframeCache(TRUE);

// Must clean up texture references before viewer window is destroyed.
LLHUDObject::cleanupHUDObjects();
@@ -6562,6 +6586,8 @@
delete gVFS;
gVFS = NULL;

+ LLCurl::cleanup();
+
// This will eventually be done in LLApp
LLCommon::cleanupClass();
}

== Submitting the Patch for Peer Review ==

Especially with larger or sensitive patches it is a good idea to first submit the patch for peer review on the [[Developer_communication_tools|mailing list]]. This way fellow developers can review the patch, uncover possible bugs, comment on undesired interactions or generally share ideas with you.

Just subscribe to the mailing list, then write an email to the list with your ''.patch'' file attached and with a description of what it does in the text or also as an attachment.

== Submitting the Patch on JIRA ==

Finally, when you think the patch is ready for the Lindens, submit the patch on the [https://jira.secondlife.com/secure/Dashboard.jspa|JIRA Bug Tracker]. Either create a new issue there or attach the patch to an existing entry. Attach the ''.patch'' file itself as a file attachment and make sure that the check mark for ''Patch attached'' is set (you can do that when creating the issue or by choosing Edit for an existing one).

Also, offer a description of the patch (the why and what) as a separate file and/or as a description or comment with the issue.

Before you do that however, just have a look at existing patches through the ''Issues with patches attached'' filter on the JIRA main page to get a general idea how it is done.

Good luck!