Imprudence:Contributing Code

From Kokua Wiki
Jump to: navigation, search

Contents

How to Contribute Code

The best way to submit any code contribution (bug fix, new feature, etc.) is with this process:

  1. Clone the Imprudence Git Repository and push a new Git branch containing your changes. Or, to create a patch file with your changes (but, we prefer a Git branch). If you need help with Git, please see our Git Primer or the documentation on the Git website, or contact us.
  2. Create a new issue on our issue tracker, if there isn't an issue related to your feature or bug fix already.
  3. In the issue description or comment, please summarize the changes you made, in plain English. Also, be sure to tell us the names of everyone who worked on it, so that we can give due credit for the contribution.
  4. Set the issue status to "Ready to Merge", and tell us where to find your contribution (i.e. your Git repository location and branch name). Or, if you created a patch, attach it to the issue.
  5. The Imprudence developers will take a look at your change, and we will probably discuss it (unless it's very simple and obvious). If it looks good, a developer will merge it into their repository. From there it will make its way into the final code!
  6. Remember when using git:
Imprudence uses LF (Unix) line endings
Make sure that's what you're using when you
clone/push or you'll cause merge conflicts

If you want to get feedback from the developers and other people before submitting your contribution, please send a message to the mailing list.

It is recommend to make changes by branching from the "exp" branch. Any patches you make and contribute would be merged with the "next" branch for testing before being merged with "exp". When an Experimental is feature frozen for bug fixing and its stable enough for a stable release it will be pushed to the "master" branch.

Code Contribution Guidelines

Contributions from the community are much appreciated — they are what make Imprudence great! Follow these guidelines to make sure your contribution can be incorporated quickly and easily:

  • Your code must be licensed under the GPLv2, or a license which allows us to re-license to GPLv2. We simply will not accept code under any other license, including the GPLv3. (Please note that if your code is derived from the SL viewer source, or any viewer based on it, then your code must be licensed under the GPLv2 anyway.)
  • Avoid using hardcoded strings in cpp files. Instead, put strings in the appropriate xml file and access them with getString("string_name"); (if an appropriate xml file doesn't exist, use strings.xml and LLTrans::getString("string_name"); instead). This allows them to be translated.

An example from llpanelavatar.cpp and panel_avatar.xml:

childSetText("notes edit", getString("Loading"));

<string name="Loading">
        Loading...
</string>
  • Add new settings to the Imprudence section of settings.xml. Likewise with notifications and notifications.xml.
  • Be sure to comment what you changed/implemented so we know why you did what you did.
  • Try not to add new preferences if you can avoid it. If your feature needs to be toggled, think about putting the control in Advanced or just making a sensible default. Debug settings are great, but the preferences window is already overcrowded.
  • When creating new source files (including C++ header files), use the following license information template at the beginning of each file. Of course, fill in the appropriate information in place of {FILENAME}, etc. For {YOUR NAME}, you may use either your real name or your SL avatar name, whichever you prefer.
/**
 * @file {FILENAME}
 * @brief {BRIEF DESCRIPTION OF FILE CONTENTS / PURPOSE}
 *
 * Copyright (c) {YEAR}, {YOUR NAME}
 *
 * The source code in this file ("Source Code") is provided to you
 * under the terms of the GNU General Public License, version 2.0
 * ("GPL"). Terms of the GPL can be found in doc/GPL-license.txt in
 * this distribution, or online at
 * http://secondlifegrid.net/programs/open_source/licensing/gplv2
 *
 * There are special exceptions to the terms and conditions of the GPL as
 * it is applied to this Source Code. View the full text of the exception
 * in the file doc/FLOSS-exception.txt in this software distribution, or
 * online at
 * http://secondlifegrid.net/programs/open_source/licensing/flossexception
 *
 * By copying, modifying or distributing this software, you acknowledge
 * that you have read and understood your obligations described above,
 * and agree to abide by those obligations.
 *
 * ALL SOURCE CODE IS PROVIDED "AS IS." THE AUTHOR MAKES NO
 * WARRANTIES, EXPRESS, IMPLIED OR OTHERWISE, REGARDING ITS ACCURACY,
 * COMPLETENESS OR PERFORMANCE.
 */

And finally:

  • Try to keep the UI clean. Imprudence prides itself on having a clean and usable UI. If you're unsure, ask for feedback.

Patch Formatting

If you submit a patch (rather than creating a Git branch), it should be in the unified diff format.

Git

The easiest way to generate a unified diff patch is to use git, e.g.:

$ git diff -u HEAD~1 > C:\your_change.patch

See git-diff for more information.

Diff

You can also use diff to generate patches.

Create two copies of your source tree. Leave one unmodified, include your changes in the other. You can use diff -u to compare the two and generate patches.

For single files:

diff -u original_source\linden\indra\newview\llfile.cpp modified_source\linden\indra\newview\llfile.cpp > C:\your_change.patch

For multiple files, you need to compare directory trees. Files can be excluded by using the --exclude flag (see the manual):

diff -u --exclude="pattern" original_source modified_source

Multiple files can also be added to the patch manually by using the >> operator:

diff -u original_source\linden\indra\newview\llfile.cpp modified_source\linden\indra\newview\llfile.cpp > C:\your_change.patch
diff -u original_source\linden\indra\newview\llfile.h modified_source\linden\indra\newview\llfile.h >> C:\your_change.patch

Sample Output

Here's what a typical patch looks like:

diff --git a/linden/indra/newview/llselectmgr.cpp b/linden/indra/newview/llselectmgr.cpp
index 998cc50..f46f104 100644
--- a/linden/indra/newview/llselectmgr.cpp
+++ b/linden/indra/newview/llselectmgr.cpp
@@ -4552,6 +4552,11 @@ extern LLGLdouble	gGLModelView[16];
 
 void LLSelectMgr::updateSilhouettes()
 {
+	if (!mRenderSilhouettes || !LLSelectMgr::sRenderSelectionHighlights)
+	{
+		return;
+	}
+
 	S32 num_sils_genned = 0;
 
 	LLVector3d	cameraPos = gAgent.getCameraPositionGlobal();

Coding Standards

  • Use a lowercase "s" to indicate static member variables, e.g. sVar.
  • Use a lowercase "m" to indicate non-static member variables, e.g. mVar.
  • Use a lowercase "g" to indicate global variables, e.g. gVar. Remember: global variables are evil.
  • Use all lowercase for local varaibles, e.g. this_is_a_local_var, and parameters.
  • Only classes are CapitalizedCase.
  • Only constants and enums are ALL_UPPERCASE.
  • Inlined functions go in headers.
  • Encase all "if" statements, "for" loops, etc. in brackets, e.g.
if (option)
{
      doThis();
}

as opposed to:

if (option)
      doThis();
  • Use "if␣(", not "if( " or "if␣(␣" or "if(␣".
  • Avoid switch statements.
  • Use initialization lists for member variables. If an initialization list isn't used in the place you want to add code, you can consider changing this a fix.
  • Use include guards in header files, e.g.
#ifndef LL_LLFOO_H
#define LL_LLFOO_H

#include "llbar.h"

class LLReferencedData; // forward declaration (no need to include "llrefrenceddata.h")

class LLFoo : public LLBar
{
public:
    LLFoo();
    void setData(LLReferencedData& refdata);
private:
    LLReferencedData* mRefData;
};

#endif //LL_LLFOO_H
  • Integer types are: U8, S8, U16, S16, U32, S32, U64, S64, e.g. S8 (signed 8-bit integer), U32 (unsigned 32 bit integer).
  • F32 denotes a 32-bit floating point value ("float").
  • F64 denotes a 64-bit floating point value ("double").
  • Use "bool" over "BOOL" whenever possible.
  • Use std::string for strings (as opposed to, say, const char *s).
  • NEVER hardcode a string or a color used by the UI in a source file.
  • Use LLFloaterSingleton<T> for floaters rather than storing an instance variable in the cpp file.
  • For more detailed information, see the coding standards page the Second Life wiki.