<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Contributing to Transifex — Transifex v0.9.1 documentation</title>
<link rel="stylesheet" href="../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '0.9.1',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="top" title="Transifex v0.9.1 documentation" href="../index.html" />
</head>
<body>
<div class="document">
<div id="custom-doc" class="yui-t6">
<div id="hd">
<h1><a href="../index.html">Transifex v0.9.1 documentation</a></h1>
<div id="global-nav">
<a title="Home page" href="../index.html">Home</a> |
<a title="Table of contents" href="../contents.html">Table of contents</a> |
<a title="Global index" href="../genindex.html">Index</a> |
<a title="Search" href="../modindex.html">Modules</a>
</div>
<div class="nav">
<a title="Transifex v0.9.1 documentation" href="../index.html" accesskey="U">up</a></div>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-g" id="development-contributing">
<div class="section" id="contributing-to-transifex">
<span id="development-contributing"></span><h1>Contributing to Transifex<a class="headerlink" href="#contributing-to-transifex" title="Permalink to this headline">¶</a></h1>
<p>We’re passionate about helping Transifex users make the jump to contributing members
of the community, so there are many ways you can help Django’s development:</p>
<ul class="simple">
<li>Report bugs and request features in our <a class="reference external" href="http://transifex.org/newticket">ticket tracker</a>. Please read
<a class="reference internal" href="#id1">Reporting bugs</a>, below, for the details on how we like our bug reports
served up.</li>
<li>Submit patches for new and/or fixed behavior. Please read <a class="reference internal" href="#submitting-patches">Submitting
patches</a>, below, for details on how to submit a patch.</li>
<li>Join the <a class="reference external" href="http://groups.google.com/group/transifex-devel">transifex-devel</a> mailing list and share your ideas for how
to improve Transifex. We’re always open to suggestions, although we’re
likely to be skeptical of large-scale suggestions without some code to
back it up.</li>
</ul>
<div class="section" id="reporting-bugs">
<span id="id1"></span><h2>Reporting bugs<a class="headerlink" href="#reporting-bugs" title="Permalink to this headline">¶</a></h2>
<p>Well-written bug reports are <em>incredibly</em> helpful. However, there’s a certain
amount of overhead involved in working with any bug tracking system, so your
help in keeping our ticket tracker as useful as possible is appreciated. In
particular:</p>
<ul class="simple">
<li><strong>Do</strong> read the <a class="reference external" href="../faq/index.html#faq-index"><em>FAQ</em></a> to see if your issue might be a well-known question.</li>
<li><strong>Do</strong> <a class="reference external" href="http://transifex.org/search?&ticket=on">search the tracker</a> to see if your issue has already been filed.</li>
<li><strong>Do</strong> ask on <a class="reference external" href="http://groups.google.com/group/transifex-devel">transifex-devel</a> <em>first</em> if you’re not sure if what you’re
seeing is a bug.</li>
<li><strong>Do</strong> write complete, reproducible, specific bug reports. Include as
much information as you possibly can, complete with code snippets, test
cases, etc. This means including a clear, concise description of the
problem, and a clear set of instructions for replicating the problem.
A minimal example that illustrates the bug in a nice small test case
is the best possible bug report.</li>
<li><strong>Don’t</strong> use the ticket system to ask support questions. Use the
<a class="reference external" href="http://groups.google.com/group/transifex-devel">transifex-devel</a> list, or the <a class="reference external" href="irc://irc.freenode.net/transifex">#transifex</a> IRC channel for that.</li>
<li><strong>Don’t</strong> use the ticket system to make large-scale feature requests.
We like to discuss any big changes to Transifex’s core on the <a class="reference external" href="http://groups.google.com/group/transifex-devel">transifex-devel</a>
list before actually working on them.</li>
<li><strong>Don’t</strong> reopen issues that have been marked “wontfix”. This mark means
that the decision has been made that we can’t or won’t fix this particular
issue. If you’re not sure why, please ask on <a class="reference external" href="http://groups.google.com/group/transifex-devel">transifex-devel</a>.</li>
<li><strong>Don’t</strong> use the ticket tracker for lengthy discussions, because they’re
likely to get lost. If a particular ticket is controversial, please move
discussion to <a class="reference external" href="http://groups.google.com/group/transifex-devel">transifex-devel</a>.</li>
<li><strong>Don’t</strong> post to transifex-devel just to announce that you have filed
a bug report. All the tickets are mailed to another list
(<a class="reference external" href="http://groups.google.com/group/transifex-updates">transifex-updates</a>), which is tracked by developers and triagers, so we
see them as they are filed.</li>
</ul>
</div>
<div class="section" id="submitting-patches">
<h2>Submitting patches<a class="headerlink" href="#submitting-patches" title="Permalink to this headline">¶</a></h2>
<p>We’re always grateful for patches to Transifex’s code. Indeed, bug reports with
associated patches will get fixed <em>far</em> more quickly than those without patches.</p>
</div>
<div class="section" id="coding-style">
<span id="id2"></span><h2>Coding style<a class="headerlink" href="#coding-style" title="Permalink to this headline">¶</a></h2>
<p>Here are some notes on the common style we use for stuff landing in Transifex.</p>
<ul>
<li><p class="first">Code follows the guidelines described in the standard Python Coding Style
of <a class="reference external" href="http://www.python.org/dev/peps/pep-0008/">PEP-8</a>. Docstrings follow <a class="reference external" href="http://www.python.org/dev/peps/pep-0257/">PEP-257</a>.</p>
</li>
<li><p class="first">Use the following style (indented, auto-concat) when writing long strings:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">lorem_ipsum</span><span class="p">():</span>
<span class="n">description</span> <span class="o">=</span> <span class="n">_</span><span class="p">(</span>
<span class="s">"Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas "</span>
<span class="s">"nisl leo, suscipit sed, elementum ac, condimentum eget, augue. "</span>
<span class="s">"Pellentesque consequat posuere metus. Curabitur scelerisque faucibus "</span>
<span class="s">"massa. Vestibulum ut nisl ut leo cursus commodo."</span>
<span class="p">)</span>
</pre></div>
</div>
</li>
<li><p class="first">Model filtering should be in the form:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">Module</span><span class="o">.</span><span class="n">query</span><span class="o">.</span><span class="n">filter_by</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">'foo'</span><span class="p">)</span>
</pre></div>
</div>
<p>and <em>not</em>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">Module</span><span class="o">.</span><span class="n">query</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">Module</span><span class="o">.</span><span class="n">name</span><span class="o">==</span><span class="s">'foo'</span><span class="p">)</span>
</pre></div>
</div>
</li>
</ul>
</div>
<div class="section" id="committing">
<h2>Committing<a class="headerlink" href="#committing" title="Permalink to this headline">¶</a></h2>
<div class="section" id="commit-messages">
<h3>Commit messages<a class="headerlink" href="#commit-messages" title="Permalink to this headline">¶</a></h3>
<p>Commit messages should have a short first line and optionally more information
after a blank newline:</p>
<div class="highlight-python"><pre>Short (50 chars or less) summary of changes (#ticket)
More detailed explanatory text can follow after a blank line, if
necessary. Wrap to about 72 characters or so.
If there is a ticket associated, include it in the summary line. Prefix
line with "bugfix:" and "trivial:" for bugfixes and trivial commits.
- Bullet points are okay, too. Typically a hyphen or asterisk is used
for the bullet, preceded by a single space, with blank lines between
items.
- Use a hanging indent, like above.</pre>
</div>
</div>
</div>
<div class="section" id="setup-hints-for-common-editors">
<h2>Setup Hints for Common Editors<a class="headerlink" href="#setup-hints-for-common-editors" title="Permalink to this headline">¶</a></h2>
<div class="section" id="configuring-vim-for-transifex-code">
<h3>Configuring VIM for Transifex Code<a class="headerlink" href="#configuring-vim-for-transifex-code" title="Permalink to this headline">¶</a></h3>
<p>To configure vim for editing Transifex code, make sure that it sets up
the indentation level to 4 columns when editing Python code, that it
expands ASCII TAB (code: 9) characters to spaces, and wraps text at 72
columns.</p>
<p>To enable these options only for <tt class="docutils literal"><span class="pre">*.py</span></tt> files, you can add the following
options to your <tt class="docutils literal"><span class="pre">~/.vimrc</span></tt> file:</p>
<div class="highlight-python"><pre>if !exists("format_tx_python")
let format_tx_python = 1
" Formatting Python code for Transifex.
autocmd BufNewFile,BufRead *.py set autoindent showmatch
autocmd BufNewFile,BufRead *.py set formatoptions=tcq2l
autocmd BufNewFile,BufRead *.py set textwidth=72 shiftwidth=4
autocmd BufNewFile,BufRead *.py set softtabstop=4 tabstop=8 expandtab
endif</pre>
</div>
</div>
<div class="section" id="configuring-emacs-for-transifex-code">
<h3>Configuring Emacs for Transifex Code<a class="headerlink" href="#configuring-emacs-for-transifex-code" title="Permalink to this headline">¶</a></h3>
<p>To configure Emacs for editing Transifex code, you can set up a hook
function that runs whenever <tt class="docutils literal"><span class="pre">python-mode</span></tt> is enabled. Setting up the
column for wrapping text, and the use of only ASCII SPACE characters for
indentation is easy. Just add the following Emacs Lisp snippet in your
Emacs startup file:</p>
<div class="highlight-python"><pre>;; Formatting Python code for Transifex.
(defun local/python-mode-options ()
"My local configuration tweaks for `python-mode'."
(setq fill-column 72 ;text wrap column
python-indent 4 ;use 4-column indentation for Python
indent-tabs-mode nil ;use only SPC for indentation
next-line-add-newlines nil)) ;don't add newlines at end-of-file
;; When python-mode loads, call our hook function.
(eval-after-load "python"
'(add-hook 'python-mode 'local/python-mode-options))</pre>
</div>
</div>
</div>
<div class="section" id="changing-the-model">
<h2>Changing the model<a class="headerlink" href="#changing-the-model" title="Permalink to this headline">¶</a></h2>
<p>Like with all software having a database, changes to Transifex’s models should
be handled with care. Production instances of Transifex rely on the stability
of the model when upgrading, and a safe upgrade path should be given to
everyone currently running a Transifex instance.</p>
<p>For this reason we usually discuss model changes on the mailing list,
especially if they’re big ones.</p>
<p>New model fields should follow the style of the current fields and include
any help texts attributes to them, if needed.</p>
<p>A commit which changes the models needs to include fixtures that work with the
new model. We already have some sample data for folks to try out in
<tt class="docutils literal"><span class="pre">txcommon/fixtures/sample_data.json</span></tt>.</p>
<div class="section" id="typical-model-change-scenario">
<h3>Typical model change scenario<a class="headerlink" href="#typical-model-change-scenario" title="Permalink to this headline">¶</a></h3>
<p>When model modifications are introduced, the following steps can be followed
to have the fixture updated:</p>
<ol class="arabic">
<li><p class="first">Flush, create tables and load data:</p>
<div class="highlight-python"><pre>./manage.py flush
./manage.py syncdb
./manage.py loaddata txcommon/fixtures/sample_data.json</pre>
</div>
</li>
<li><p class="first">Make changes to the models.</p>
</li>
<li><p class="first">Probably a migration will be required.</p>
<p>From the Release 0.7, Transifex uses South for managing the schema
migrations of models. To get the migration script related to your model
change run:</p>
<div class="highlight-python"><pre>./manage.py startmigration <app_name> <migration_name> --auto</pre>
</div>
<p>Note that a new python script with the <migration_name> will be created under
the <app_name>/migrations/ dir. As it’s an automatic detection, please, have
a look on it for checking if it is really reflecting your changes correctly.
After check it, you can test it running:</p>
<div class="highlight-python"><pre>./manage.py migrate <app_name> --db-dry-run</pre>
</div>
<p>In complex changes the South application might not be able to proceed
automatically (for example when adding a non-null column). In this case you can
delete the column and re-add it, add it as null and change it, etc. South
also supports to write manual migrations and more information can be found
at <a class="reference external" href="http://south.aeracode.org/wiki/Documentation">http://south.aeracode.org/wiki/Documentation</a>.</p>
<p>Once your migration pass through the above command without errors, you can
proceed the migration in the database skipping the option –db-dry-run:</p>
<div class="highlight-python"><pre>./manage.py migrate <app_name></pre>
</div>
</li>
<li><p class="first">With the new DB schema in place, dump the data again:</p>
<div class="highlight-python"><pre>./manage.py dumpdata --indent=2 projects releases codebases \
tarball vcs sites > txcommon/fixtures/sample_data.json</pre>
</div>
</li>
<li><p class="first">Try the new DB fixture:</p>
<div class="highlight-python"><pre>./manage.py flush --noinput
./manage.py syncdb --noinput
./manage.py loaddata txcommon/fixtures/sample_data.json
./manage.py loaddata txcommon/fixtures/sample_users.json</pre>
</div>
<p>Open up your browser to check everything looks OK and that your changes
have been included as you’d expect.</p>
</li>
<li><p class="first">Update the documentation if needed. Commit all changes together.</p>
</li>
</ol>
</div>
</div>
<div class="section" id="updating-translation-files-po-files">
<h2>Updating translation files (PO files)<a class="headerlink" href="#updating-translation-files-po-files" title="Permalink to this headline">¶</a></h2>
<p>To extract new messages from the source code and update the PO files of
Transifex it is necessary to run the following command and then commit the
changes:</p>
<div class="highlight-python"><pre>./manage.py txmakemessages --all</pre>
</div>
</div>
<div class="section" id="various-development-tips">
<h2>Various Development Tips<a class="headerlink" href="#various-development-tips" title="Permalink to this headline">¶</a></h2>
<div class="section" id="cross-site-request-forgery-protection">
<h3>Cross Site Request Forgery protection<a class="headerlink" href="#cross-site-request-forgery-protection" title="Permalink to this headline">¶</a></h3>
<p>Transifex is protected against <a class="reference external" href="http://en.wikipedia.org/wiki/Cross-site_request_forgery">CSRF</a> attacks by ensuring that GET requests are
side-effect free. This means that every action inside Transifex that has an
effect on the database, session, etc. are not being done over a GET request.
With Django’s <a class="reference external" href="http://docs.djangoproject.com/en/dev/ref/contrib/csrf/">CSRF Middleware</a> enabled, attackers are prevented from meddling
with a Transifex user’s settings.</p>
<p>Examples of CSRF-vulnerable elements are a link which calls <tt class="docutils literal"><span class="pre">/logout</span></tt> over
GET to log the user out, a ‘pt_BR’ link to change the page’s language to
Brazilian Portuguese and save this setting to the user’s cookie, a simple AJAX
request to lock a file, etc.</p>
<p>Examples not vulnerable actions are searching through the website for a string,
pagination, etc.</p>
<p>If you are adding some code in Transifex which has a side-effect, always do it
over POST.</p>
</div>
</div>
</div>
<div class="nav">
<a title="Transifex v0.9.1 documentation" href="../index.html" accesskey="U">up</a></div>
</div>
</div>
</div>
<div class="yui-b" id="sidebar">
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/transifex-logo.png" alt="Logo"/>
</a></p>
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference external" href="#">Contributing to Transifex</a><ul>
<li><a class="reference external" href="#reporting-bugs">Reporting bugs</a></li>
<li><a class="reference external" href="#submitting-patches">Submitting patches</a></li>
<li><a class="reference external" href="#coding-style">Coding style</a></li>
<li><a class="reference external" href="#committing">Committing</a><ul>
<li><a class="reference external" href="#commit-messages">Commit messages</a></li>
</ul>
</li>
<li><a class="reference external" href="#setup-hints-for-common-editors">Setup Hints for Common Editors</a><ul>
<li><a class="reference external" href="#configuring-vim-for-transifex-code">Configuring VIM for Transifex Code</a></li>
<li><a class="reference external" href="#configuring-emacs-for-transifex-code">Configuring Emacs for Transifex Code</a></li>
</ul>
</li>
<li><a class="reference external" href="#changing-the-model">Changing the model</a><ul>
<li><a class="reference external" href="#typical-model-change-scenario">Typical model change scenario</a></li>
</ul>
</li>
<li><a class="reference external" href="#updating-translation-files-po-files">Updating translation files (PO files)</a></li>
<li><a class="reference external" href="#various-development-tips">Various Development Tips</a><ul>
<li><a class="reference external" href="#cross-site-request-forgery-protection">Cross Site Request Forgery protection</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h3>Browse</h3>
<ul>
</ul>
<h3>You are here:</h3>
<ul>
<li>
<a href="../index.html">Transifex v0.9.1 documentation</a>
<ul><li>Contributing to Transifex</li></ul>
</li>
</ul>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/development/contributing.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<h3>Last update:</h3>
<p class="topless">Sep 24, 2010</p>
</div>
</div>
<div id="ft">
<div class="nav">
<a title="Transifex v0.9.1 documentation" href="../index.html" accesskey="U">up</a></div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
© Copyright <a href="http://www.indifex.com">Indifex</a> and the <a href="http://transifex.org/">Transifex</a> Community.
Last updated on Sep 24, 2010 using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
</div>
<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
try {
var pageTracker = _gat._getTracker("UA-4362397-5");
pageTracker._trackPageview();
} catch(err) {}</script>
</body>
</html>
