Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-03-27 18:26:32 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Updated HTML docs.

Browse source
This commit is contained in:
Evennia docbuilder action 2022-11-25 18:52:52 +00:00
parent 55dc9942a8
commit cf88322ffe
83 changed files with 2621 additions and 3207 deletions
Download patch file Download diff file Expand all files Collapse all files

8
docs/1.0-dev/Coding/Changelog.html
View file

@ -17,7 +17,7 @@
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Continuous Integration" href="Continuous-Integration.html" />
<link rel="next" title="Continuous Integration (CI)" href="Continuous-Integration.html" />
<link rel="prev" title="Quirks" href="Quirks.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
@ -30,7 +30,7 @@
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Continuous-Integration.html" title="Continuous Integration"
<a href="Continuous-Integration.html" title="Continuous Integration (CI)"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Quirks.html" title="Quirks"
@ -129,7 +129,7 @@
title="previous chapter">Quirks</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Continuous-Integration.html"
title="next chapter">Continuous Integration</a></p>
title="next chapter">Continuous Integration (CI)</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
@ -1080,7 +1080,7 @@ and have no changelogs.</p>
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Continuous-Integration.html" title="Continuous Integration"
<a href="Continuous-Integration.html" title="Continuous Integration (CI)"
>next</a> |</li>
<li class="right" >
<a href="Quirks.html" title="Quirks"

160
docs/1.0-dev/Coding/Coding-FAQ.html
View file

@ -17,8 +17,8 @@
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Debugging" href="Debugging.html" />
<link rel="prev" title="Coding Introduction" href="Coding-Introduction.html" />
<link rel="next" title="Quirks" href="Quirks.html" />
<link rel="prev" title="Evennia Code Style" href="Evennia-Code-Style.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
@ -30,10 +30,10 @@
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Debugging.html" title="Debugging"
<a href="Quirks.html" title="Quirks"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Coding-Introduction.html" title="Coding Introduction"
<a href="Evennia-Code-Style.html" title="Evennia Code Style"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Coding-Overview.html" accesskey="U">Coding and development help</a> &#187;</li>
@ -63,28 +63,25 @@
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Coding FAQ</a><ul>
<li><a class="reference internal" href="#table-of-contents">Table of Contents</a></li>
<li><a class="reference internal" href="#removing-default-commands">Removing default commands</a></li>
<li><a class="reference internal" href="#preventing-character-from-moving-based-on-a-condition">Preventing character from moving based on a condition</a></li>
<li><a class="reference internal" href="#reference-initiating-object-in-an-evmenu-command">Reference initiating object in an EvMenu command.</a></li>
<li><a class="reference internal" href="#adding-color-to-default-evennia-channels">Adding color to default Evennia Channels</a></li>
<li><a class="reference internal" href="#selectively-turn-off-commands-in-a-room">Selectively turn off commands in a room</a></li>
<li><a class="reference internal" href="#select-command-based-on-a-condition">Select Command based on a condition</a></li>
<li><a class="reference internal" href="#automatically-updating-code-when-reloading">Automatically updating code when reloading</a></li>
<li><a class="reference internal" href="#changing-all-exit-messages">Changing all exit messages</a></li>
<li><a class="reference internal" href="#add-parsing-with-the-to-delimiter">Add parsing with the “to” delimiter</a></li>
<li><a class="reference internal" href="#store-last-used-session-ip-address">Store last used session IP address</a></li>
<li><a class="reference internal" href="#non-latin-characters-in-evtable">Non-latin characters in EvTable</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="Coding-Introduction.html"
title="previous chapter">Coding Introduction</a></p>
<p class="topless"><a href="Evennia-Code-Style.html"
title="previous chapter">Evennia Code Style</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Debugging.html"
title="next chapter">Debugging</a></p>
<p class="topless"><a href="Quirks.html"
title="next chapter">Quirks</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
@ -120,29 +117,9 @@
<p><em>This FAQ page is for users to share their solutions to coding problems. Keep it brief and link to
the docs if you can rather than too lengthy explanations. Don’t forget to check if an answer already
exists before answering - maybe you can clarify that answer rather than to make a new Q&amp;A section.</em></p>
<section id="table-of-contents">
<h2>Table of Contents<a class="headerlink" href="#table-of-contents" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p><a class="reference internal" href="#removing-default-commands"><span class="std std-doc">Removing default commands</span></a></p></li>
<li><p>[Preventing character from moving based on a condition](./Coding-FAQ.md#preventing-character-from-
moving-based-on-a-condition)</p></li>
<li><p>[Reference initiating object in an EvMenu command](./Coding-FAQ.md#reference-initiating-object-in-an-
evmenu-command)</p></li>
<li><p><a class="reference internal" href="#adding-color-to-default-evennia-channels"><span class="std std-doc">Adding color to default Evennia Channels</span></a></p></li>
<li><p><a class="reference internal" href="#selectively-turn-off-commands-in-a-room"><span class="std std-doc">Selectively turn off commands in a room</span></a></p></li>
<li><p><a class="reference internal" href="#select-command-based-on-a-condition"><span class="std std-doc">Select Command based on a condition</span></a></p></li>
<li><p>[Automatically updating code when reloading](./Coding-FAQ.md#automatically-updating-code-when-
reloading)</p></li>
<li><p><a class="reference internal" href="#changing-all-exit-messages"><span class="std std-doc">Changing all exit messages</span></a></p></li>
<li><p><a class="reference internal" href="#add-parsing-with-the-to-delimiter"><span class="std std-doc">Add parsing with the “to” delimiter</span></a></p></li>
<li><p><a class="reference internal" href="#store-last-used-session-ip-address"><span class="std std-doc">Store last used session IP address</span></a></p></li>
<li><p><a class="reference internal" href="#non-latin-characters-in-evtable"><span class="std std-doc">Use wide characters with EvTable</span></a></p></li>
</ul>
</section>
<section id="removing-default-commands">
<h2>Removing default commands<a class="headerlink" href="#removing-default-commands" title="Permalink to this headline"></a></h2>
<p><strong>Q:</strong> How does one <em>remove</em> (not replace) e.g. the default <code class="docutils literal notranslate"><span class="pre">get</span></code> <a class="reference internal" href="../Components/Commands.html"><span class="doc std std-doc">Command</span></a> from the
Character <a class="reference internal" href="../Components/Command-Sets.html"><span class="doc std std-doc">Command Set</span></a>?</p>
<p><strong>Q:</strong> How does one <em>remove</em> (not replace) e.g. the default <code class="docutils literal notranslate"><span class="pre">get</span></code> <a class="reference internal" href="../Components/Commands.html"><span class="doc std std-doc">Command</span></a> from the Character <a class="reference internal" href="../Components/Command-Sets.html"><span class="doc std std-doc">Command Set</span></a>?</p>
<p><strong>A:</strong> Go to <code class="docutils literal notranslate"><span class="pre">mygame/commands/default_cmdsets.py</span></code>. Find the <code class="docutils literal notranslate"><span class="pre">CharacterCmdSet</span></code> class. It has one
method named <code class="docutils literal notranslate"><span class="pre">at_cmdset_creation</span></code>. At the end of that method, add the following line:
<code class="docutils literal notranslate"><span class="pre">self.remove(default_cmds.CmdGet())</span></code>. See the <a class="reference internal" href="../Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Adding-Commands.html"><span class="doc std std-doc">Adding Commands Tutorial</span></a>
@ -183,29 +160,6 @@ properties on this menu object:</p>
</div>
<p>Inside the menu you can now access the object through <code class="docutils literal notranslate"><span class="pre">caller.ndb._evmenu.stored_obj</span></code>.</p>
</section>
<section id="adding-color-to-default-evennia-channels">
<h2>Adding color to default Evennia Channels<a class="headerlink" href="#adding-color-to-default-evennia-channels" title="Permalink to this headline"></a></h2>
<p><strong>Q:</strong> How do I add colors to the names of Evennia channels?</p>
<p><strong>A:</strong> The Channel typeclass’ <code class="docutils literal notranslate"><span class="pre">channel_prefix</span></code> method decides what is shown at the beginning of a
channel send. Edit <code class="docutils literal notranslate"><span class="pre">mygame/typeclasses/channels.py</span></code> (and then <code class="docutils literal notranslate"><span class="pre">&#64;reload</span></code>):</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># define our custom color names</span>
<span class="n">CHANNEL_COLORS</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;public&quot;</span><span class="p">:</span> <span class="s2">&quot;|015Public|n&quot;</span><span class="p">,</span>
<span class="s2">&quot;newbie&quot;</span><span class="p">:</span> <span class="s2">&quot;|550N|n|551e|n|552w|n|553b|n|554i|n|555e|n&quot;</span><span class="p">,</span>
<span class="s2">&quot;staff&quot;</span><span class="p">:</span> <span class="s2">&quot;|010S|n|020t|n|030a|n|040f|n|050f|n&quot;</span><span class="p">}</span>
<span class="c1"># Add to the Channel class</span>
<span class="c1"># ...</span>
<span class="k">def</span> <span class="nf">channel_prefix</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">msg</span><span class="p">,</span> <span class="n">emit</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
<span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">key</span> <span class="ow">in</span> <span class="n">COLORS</span><span class="p">:</span>
<span class="n">p_str</span> <span class="o">=</span> <span class="n">CHANNEL_COLORS</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">key</span><span class="o">.</span><span class="n">lower</span><span class="p">())</span>
<span class="k">else</span><span class="p">:</span>
<span class="n">p_str</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">key</span><span class="o">.</span><span class="n">capitalize</span><span class="p">()</span>
<span class="k">return</span> <span class="sa">f</span><span class="s2">&quot;[</span><span class="si">{</span><span class="n">p_str</span><span class="si">}</span><span class="s2">] &quot;</span>
</pre></div>
</div>
<p>Additional hint: To make colors easier to change from one place you could instead put the
<code class="docutils literal notranslate"><span class="pre">CHANNEL_COLORS</span></code> dict in your settings file and import it as <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">django.conf.settings</span> <span class="pre">import</span> <span class="pre">CHANNEL_COLORS</span></code>.</p>
</section>
<section id="selectively-turn-off-commands-in-a-room">
<h2>Selectively turn off commands in a room<a class="headerlink" href="#selectively-turn-off-commands-in-a-room" title="Permalink to this headline"></a></h2>
<p><strong>Q:</strong> I want certain commands to turn off in a given room. They should still work normally for
@ -239,18 +193,16 @@ is an example of a room where certain commands are disabled for non-staff:</p>
<span class="bp">self</span><span class="o">.</span><span class="n">locks</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">&quot;call:not perm(Builders)&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>After <code class="docutils literal notranslate"><span class="pre">&#64;reload</span></code>, make some <code class="docutils literal notranslate"><span class="pre">BlockingRooms</span></code> (or switch a room to it with <code class="docutils literal notranslate"><span class="pre">&#64;typeclass</span></code>). Entering one
<p>After <code class="docutils literal notranslate"><span class="pre">reload</span></code>, make some <code class="docutils literal notranslate"><span class="pre">BlockingRooms</span></code> (or switch a room to it with <code class="docutils literal notranslate"><span class="pre">&#64;typeclass</span></code>). Entering one
will now replace the given commands for anyone that does not have the <code class="docutils literal notranslate"><span class="pre">Builders</span></code> or higher
permission. Note that the ‘call’ lock is special in that even the superuser will be affected by it
(otherwise superusers would always see other player’s cmdsets and a game would be unplayable for
superusers).</p>
(otherwise superusers would always see other player’s cmdsets and a game would be unplayable for superusers).</p>
</section>
<section id="select-command-based-on-a-condition">
<h2>Select Command based on a condition<a class="headerlink" href="#select-command-based-on-a-condition" title="Permalink to this headline"></a></h2>
<p><strong>Q:</strong> I want a command to be available only based on a condition. For example I want the “werewolf”
command to only be available on a full moon, from midnight to three in-game time.</p>
<p><strong>A:</strong> This is easiest accomplished by putting the “werewolf” command on the Character as normal,
but to <a class="reference internal" href="../Components/Locks.html"><span class="doc std std-doc">lock</span></a> it with the “cmd” type lock. Only if the “cmd” lock type is passed will the
<p><strong>A:</strong> This is easiest accomplished by putting the “werewolf” command on the Character as normal, but to <a class="reference internal" href="../Components/Locks.html"><span class="doc std std-doc">lock</span></a> it with the “cmd” type lock. Only if the “cmd” lock type is passed will the
command be available.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># in mygame/commands/command.py</span>
@ -264,8 +216,7 @@ command be available.</p>
<span class="c1"># ...</span>
</pre></div>
</div>
<p>Add this to the <a class="reference internal" href="../Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Adding-Commands.html"><span class="doc std std-doc">default cmdset as usual</span></a>. The <code class="docutils literal notranslate"><span class="pre">is_full_moon</span></code> <a class="reference internal" href="../Components/Locks.html#lock-functions"><span class="std std-doc">lock
function</span></a> does not yet exist. We must create that:</p>
<p>Add this to the <a class="reference internal" href="../Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Adding-Commands.html"><span class="doc std std-doc">default cmdset as usual</span></a>. The <code class="docutils literal notranslate"><span class="pre">is_full_moon</span></code> <a class="reference internal" href="../Components/Locks.html#lock-functions"><span class="std std-doc">lock function</span></a> does not yet exist. We must create that:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># in mygame/server/conf/lockfuncs.py</span>
<span class="k">def</span> <span class="nf">is_full_moon</span><span class="p">(</span><span class="n">accessing_obj</span><span class="p">,</span> <span class="n">accessed_obj</span><span class="p">,</span>
@ -276,7 +227,7 @@ function</span></a> does not yet exist. We must create that:</p>
</pre></div>
</div>
<p>After a <code class="docutils literal notranslate"><span class="pre">&#64;reload</span></code>, the <code class="docutils literal notranslate"><span class="pre">werewolf</span></code> command will be available only at the right time, that is when the
<p>After a <code class="docutils literal notranslate"><span class="pre">reload</span></code>, the <code class="docutils literal notranslate"><span class="pre">werewolf</span></code> command will be available only at the right time, that is when the
<code class="docutils literal notranslate"><span class="pre">is_full_moon</span></code> lock function returns True.</p>
</section>
<section id="automatically-updating-code-when-reloading">
@ -299,43 +250,28 @@ you have your project in a configured Git environment, it’s a matter of automa
<span class="n">process</span> <span class="o">=</span> <span class="n">subprocess</span><span class="o">.</span><span class="n">call</span><span class="p">([</span><span class="s2">&quot;git&quot;</span><span class="p">,</span> <span class="s2">&quot;pull&quot;</span><span class="p">],</span> <span class="n">shell</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
</pre></div>
</div>
<p>That’s all. We call <code class="docutils literal notranslate"><span class="pre">subprocess</span></code> to execute a shell command (that code works on Windows and Linux,
assuming the current directory is your game directory, which is probably the case when you run
Evennia). <code class="docutils literal notranslate"><span class="pre">call</span></code> waits for the process to complete, because otherwise, Evennia would reload on
partially-modified code, which would be problematic.</p>
<p>Now, when you enter <code class="docutils literal notranslate"><span class="pre">&#64;reload</span></code> on your development server, the game repository is updated from the
configured remote repository (Github, for instance). Your development cycle could resemble
something like:</p>
<p>That’s all. We call <code class="docutils literal notranslate"><span class="pre">subprocess</span></code> to execute a shell command (that code works on Windows and Linux, assuming the current directory is your game directory, which is probably the case when you run Evennia). <code class="docutils literal notranslate"><span class="pre">call</span></code> waits for the process to complete, because otherwise, Evennia would reload on partially-modified code, which would be problematic.</p>
<p>Now, when you enter <code class="docutils literal notranslate"><span class="pre">reload</span></code> on your development server, the game repository is updated from the configured remote repository (Github, for instance). Your development cycle could resemble something like:</p>
<ol class="simple">
<li><p>Coding on the local machine.</p></li>
<li><p>Testing modifications.</p></li>
<li><p>Committing once, twice or more (being sure the code is still working, unittests are pretty useful
here).</p></li>
<li><p>Committing once, twice or more (being sure the code is still working, unittests are pretty useful here).</p></li>
<li><p>When the time comes, login to the development server and run <code class="docutils literal notranslate"><span class="pre">&#64;reload</span></code>.</p></li>
</ol>
<p>The reloading might take one or two additional seconds, since Evennia will pull from your remote Git
repository. But it will reload on it and you will have your modifications ready, without needing
<p>The reloading might take one or two additional seconds, since Evennia will pull from your remote Git repository. But it will reload on it and you will have your modifications ready, without needing
connecting to your server using SSH or something similar.</p>
</section>
<section id="changing-all-exit-messages">
<h2>Changing all exit messages<a class="headerlink" href="#changing-all-exit-messages" title="Permalink to this headline"></a></h2>
<p><strong>Q:</strong> How can I change the default exit messages to something like “XXX leaves east” or “XXX
arrives from the west”?</p>
<p><strong>A:</strong> the default exit messages are stored in two hooks, namely <code class="docutils literal notranslate"><span class="pre">announce_move_from</span></code> and
<code class="docutils literal notranslate"><span class="pre">announce_move_to</span></code>, on the <code class="docutils literal notranslate"><span class="pre">Character</span></code> typeclass (if what you want to change is the message other
characters will see when a character exits).</p>
<p>These two hooks provide some useful features to easily update the message to be displayed. They
take both the default message and mapping as argument. You can easily call the parent hook with
these information:</p>
<p><strong>A:</strong> the default exit messages are stored in two hooks, namely <code class="docutils literal notranslate"><span class="pre">announce_move_from</span></code> and <code class="docutils literal notranslate"><span class="pre">announce_move_to</span></code>, on the <code class="docutils literal notranslate"><span class="pre">Character</span></code> typeclass (if what you want to change is the message other characters will see when a character exits).</p>
<p>These two hooks provide some useful features to easily update the message to be displayed. They take both the default message and mapping as argument. You can easily call the parent hook with these information:</p>
<ul class="simple">
<li><p>The message represents the string of characters sent to characters in the room when a character
leaves.</p></li>
<li><p>The mapping is a dictionary containing additional mappings (you will probably not need it for
simple customization).</p></li>
<li><p>The message represents the string of characters sent to characters in the room when a character leaves.</p></li>
<li><p>The mapping is a dictionary containing additional mappings (you will probably not need it for simple customization).</p></li>
</ul>
<p>It is advisable to look in the <a class="reference external" href="https://github.com/evennia/evennia/tree/master/evennia/objects/objects.py">code of both
hooks</a>, and read the
hooks’ documentation. The explanations on how to quickly update the message are shown below:</p>
<p>It is advisable to look in the <a class="reference internal" href="../api/evennia.objects.objects.html#evennia.objects.objects.DefaultCharacter" title="evennia.objects.objects.DefaultCharacter"><span class="xref myst py py-class">code of both hooks</span></a>, and read the hooks’ documentation. The explanations on how to quickly update the message are shown below:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># In typeclasses/characters.py</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="sd">Characters</span>
@ -394,16 +330,12 @@ hooks’ documentation. The explanations on how to quickly update the message a
<span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="n">announce_move_to</span><span class="p">(</span><span class="n">source_location</span><span class="p">,</span> <span class="n">msg</span><span class="o">=</span><span class="s2">&quot;</span><span class="si">{object}</span><span class="s2"> arrives from the </span><span class="si">{exit}</span><span class="s2">.&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>We override both hooks, but call the parent hook to display a different message. If you read the
provided docstrings, you will better understand why and how we use mappings (information between
braces). You can provide additional mappings as well, if you want to set a verb to move, for
instance, or other, extra information.</p>
<p>We override both hooks, but call the parent hook to display a different message. If you read the provided docstrings, you will better understand why and how we use mappings (information between braces). You can provide additional mappings as well, if you want to set a verb to move, for instance, or other, extra information.</p>
</section>
<section id="add-parsing-with-the-to-delimiter">
<h2>Add parsing with the “to” delimiter<a class="headerlink" href="#add-parsing-with-the-to-delimiter" title="Permalink to this headline"></a></h2>
<p><strong>Q:</strong> How do I change commands to undestand say <code class="docutils literal notranslate"><span class="pre">give</span> <span class="pre">obj</span> <span class="pre">to</span> <span class="pre">target</span></code> as well as the default <code class="docutils literal notranslate"><span class="pre">give</span> <span class="pre">obj</span> <span class="pre">=</span> <span class="pre">target</span></code>?</p>
<p><strong>A:</strong> You can make change the default <code class="docutils literal notranslate"><span class="pre">MuxCommand</span></code> parent with your own class making a small change
in its <code class="docutils literal notranslate"><span class="pre">parse</span></code> method:</p>
<p><strong>A:</strong> You can make change the default <code class="docutils literal notranslate"><span class="pre">MuxCommand</span></code> parent with your own class making a small change in its <code class="docutils literal notranslate"><span class="pre">parse</span></code> method:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="c1"># in mygame/commands/command.py</span>
<span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">default_cmds</span>
<span class="k">class</span> <span class="nc">MuxCommand</span><span class="p">(</span><span class="n">default_cmds</span><span class="o">.</span><span class="n">MuxCommand</span><span class="p">):</span>
@ -418,39 +350,9 @@ in its <code class="docutils literal notranslate"><span class="pre">parse</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="n">COMMAND_DEFAULT_CLASS</span> <span class="o">=</span> <span class="s2">&quot;commands.command.MuxCommand&quot;</span>
</pre></div>
</div>
<p>Do a <code class="docutils literal notranslate"><span class="pre">&#64;reload</span></code> and all default commands will now use your new tweaked parent class. A copy of the
<p>Do a <code class="docutils literal notranslate"><span class="pre">reload</span></code> and all default commands will now use your new tweaked parent class. A copy of the
MuxCommand class is also found commented-out in the <code class="docutils literal notranslate"><span class="pre">mygame/commands/command.py</span></code> file.</p>
</section>
<section id="store-last-used-session-ip-address">
<h2>Store last used session IP address<a class="headerlink" href="#store-last-used-session-ip-address" title="Permalink to this headline"></a></h2>
<p><strong>Q:</strong> If a user has already logged out of an Evennia account, their IP is no longer visible to
staff that wants to ban-by-ip (instead of the user) with <code class="docutils literal notranslate"><span class="pre">&#64;ban/ip</span></code>?</p>
<p><strong>A:</strong> One approach is to write the IP from the last session onto the “account” account object.</p>
<p><code class="docutils literal notranslate"><span class="pre">typeclasses/accounts.py</span></code></p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="k">def</span> <span class="nf">at_post_login</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">session</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="n">at_post_login</span><span class="p">(</span><span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
<span class="bp">self</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">lastsite</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">sessions</span><span class="o">.</span><span class="n">all</span><span class="p">()[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span><span class="o">.</span><span class="n">address</span>
</pre></div>
</div>
<p>Adding timestamp for login time and appending to a list to keep the last N login IP addresses and
timestamps is possible, also. Additionally, if you don’t want the list to grow beyond a
<code class="docutils literal notranslate"><span class="pre">do_not_exceed</span></code> length, conditionally pop a value after you’ve added it, if the length has grown too
long.</p>
<p><strong>NOTE:</strong> You’ll need to add <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">time</span></code> to generate the login timestamp.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="k">def</span> <span class="nf">at_post_login</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">session</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="n">at_post_login</span><span class="p">(</span><span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
<span class="n">do_not_exceed</span> <span class="o">=</span> <span class="mi">24</span> <span class="c1"># Keep the last two dozen entries</span>
<span class="n">session</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">sessions</span><span class="o">.</span><span class="n">all</span><span class="p">()[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span> <span class="c1"># Most recent session</span>
<span class="k">if</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">lastsite</span><span class="p">:</span>
<span class="bp">self</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">lastsite</span> <span class="o">=</span> <span class="p">[]</span>
<span class="bp">self</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">lastsite</span><span class="o">.</span><span class="n">insert</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="p">(</span><span class="n">session</span><span class="o">.</span><span class="n">address</span><span class="p">,</span> <span class="nb">int</span><span class="p">(</span><span class="n">time</span><span class="o">.</span><span class="n">time</span><span class="p">())))</span>
<span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">lastsite</span><span class="p">)</span> <span class="o">&gt;</span> <span class="n">do_not_exceed</span><span class="p">:</span>
<span class="bp">self</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">lastsite</span><span class="o">.</span><span class="n">pop</span><span class="p">()</span>
</pre></div>
</div>
<p>This only stores the data. You may want to interface the <code class="docutils literal notranslate"><span class="pre">&#64;ban</span></code> command or make a menu-driven viewer
for staff to browse the list and display how long ago the login occurred.</p>
</section>
<section id="non-latin-characters-in-evtable">
<h2>Non-latin characters in EvTable<a class="headerlink" href="#non-latin-characters-in-evtable" title="Permalink to this headline"></a></h2>
<p><strong>Q:</strong> When using e.g. Chinese characters in EvTable, some lines appear to be too wide, for example</p>
@ -461,11 +363,7 @@ for staff to browse the list and display how long ago the login occurred.</p>
<span class="o">+~~~~~~+~~~~~~+</span>
</pre></div>
</div>
<p><strong>A:</strong> The reason for this is because certain non-latin characters are <em>visually</em> much wider than
their len() suggests. There is little Evennia can (reliably) do about this. If you are using such
characters, you need to make sure to use a suitable mono-spaced font where are width are equal. You
can set this in your web client and need to recommend it for telnet-client users. See <a class="reference external" href="https://github.com/evennia/evennia/issues/1522">this
discussion</a> where some suitable fonts are suggested.</p>
<p><strong>A:</strong> The reason for this is because certain non-latin characters are <em>visually</em> much wider than their len() suggests. There is little Evennia can (reliably) do about this. If you are using such characters, you need to make sure to use a suitable mono-spaced font where are width are equal. You can set this in your web client and need to recommend it for telnet-client users. See <a class="reference external" href="https://github.com/evennia/evennia/issues/1522">this discussion</a> where some suitable fonts are suggested.</p>
</section>
</section>
@ -485,10 +383,10 @@ discussion</a> where some suitable fonts are suggested.</p>
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Debugging.html" title="Debugging"
<a href="Quirks.html" title="Quirks"
>next</a> |</li>
<li class="right" >
<a href="Coding-Introduction.html" title="Coding Introduction"
<a href="Evennia-Code-Style.html" title="Evennia Code Style"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Coding-Overview.html" >Coding and development help</a> &#187;</li>

268
docs/1.0-dev/Coding/Coding-Introduction.html
View file

@ -1,268 +0,0 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Coding Introduction &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Coding FAQ" href="Coding-FAQ.html" />
<link rel="prev" title="Updating Your Game" href="Updating-Your-Game.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Coding-FAQ.html" title="Coding FAQ"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Updating-Your-Game.html" title="Updating Your Game"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Coding-Overview.html" accesskey="U">Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Coding Introduction</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Coding Introduction</a><ul>
<li><a class="reference internal" href="#start-with-the-tutorial">Start with the tutorial</a></li>
<li><a class="reference internal" href="#explore-evennia-interactively">Explore Evennia interactively</a><ul>
<li><a class="reference internal" href="#jupyter-notebook-support">Jupyter Notebook Support</a></li>
<li><a class="reference internal" href="#more-exploration">More exploration</a></li>
</ul>
</li>
<li><a class="reference internal" href="#use-a-python-syntax-checker">Use a python syntax checker</a></li>
<li><a class="reference internal" href="#plan-before-you-code">Plan before you code</a></li>
<li><a class="reference internal" href="#code-in-your-game-folder-not-in-the-evennia-repository">Code in your game folder, not in the evennia/ repository</a></li>
<li><a class="reference internal" href="#learn-to-read-tracebacks">Learn to read tracebacks</a></li>
<li><a class="reference internal" href="#docs-are-here-to-help-you">Docs are here to help you</a></li>
<li><a class="reference internal" href="#the-most-important-point">The most important point</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="Updating-Your-Game.html"
title="previous chapter">Updating Your Game</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Coding-FAQ.html"
title="next chapter">Coding FAQ</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Coding/Coding-Introduction.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div><h3>Links</h3>
<ul>
<li><a href="https://www.evennia.com">Home page</a> </li>
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
<h3>Versions</h3>
<ul>
<li><a href="Coding-Introduction.html">1.0-dev (develop branch)</a></li>
<ul>
<li><a href="../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="coding-introduction">
<h1>Coding Introduction<a class="headerlink" href="#coding-introduction" title="Permalink to this headline"></a></h1>
<p>Evennia allows for a lot of freedom when designing your game - but to code efficiently you still
need to adopt some best practices as well as find a good place to start to learn.</p>
<p>Here are some pointers to get you going.</p>
<section id="start-with-the-tutorial">
<h2>Start with the tutorial<a class="headerlink" href="#start-with-the-tutorial" title="Permalink to this headline"></a></h2>
<p>It’s highly recommended that you jump in on the <a class="reference internal" href="../Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Part1-Overview.html"><span class="doc std std-doc">Starting Tutorial</span></a>. Even if
you only the beginning or some part of it, it covers much of the things needed to get started, including giving you are first introduction to Python.</p>
</section>
<section id="explore-evennia-interactively">
<h2>Explore Evennia interactively<a class="headerlink" href="#explore-evennia-interactively" title="Permalink to this headline"></a></h2>
<p>As mentioned in the Starting tutorial, it’s a good idea to use <a class="reference external" href="https://ipython.org/">ipython</a> to explore things using a python shell:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># [open a new console/terminal]
cd mygame
evennia shell
</pre></div>
</div>
<p>This will open an Evennia-aware python shell (using ipython). From within this shell, try</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>import evennia
evennia.&lt;TAB&gt;
</pre></div>
</div>
<section id="jupyter-notebook-support">
<h3>Jupyter Notebook Support<a class="headerlink" href="#jupyter-notebook-support" title="Permalink to this headline"></a></h3>
<p>You can also explore evennia interactively in a <a class="reference external" href="https://jupyter.readthedocs.io/en/latest/index.html">Jupyter notebook</a>. This offers
an in-browser view of your code similar to Matlab or similar programs. There are
a few extra steps that must be taken in order for this to work:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># [open a new console/terminal]
# [activate your evennia virtualenv in this console/terminal]
cd evennia
pip install -r requirements_extra.txt # if not done already above
</pre></div>
</div>
<p>Next, <code class="docutils literal notranslate"><span class="pre">cd</span></code> to your game folder. <em>It’s important that you are in the <em>root</em> of this folder for the next command</em>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia shell_plus --notebook &amp;
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">&amp;</span></code> at the end starts the process as a background process on Linux/Unix.
Skip it if your OS doesn’t support this syntax. Your browser should now open
with the Jupyter interface. If not, open a browser to the link given on the
command line.</p>
<p>In the window, open the <code class="docutils literal notranslate"><span class="pre">new</span></code> menu in the top right and start a <code class="docutils literal notranslate"><span class="pre">Django</span> <span class="pre">Shell-Plus</span></code> notebook (or
open an existing one if you had one from before). In the first cell you must initialize
Evennia like so:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">evennia</span>
<span class="n">evennia</span><span class="o">.</span><span class="n">_init</span><span class="p">()</span>
</pre></div>
</div>
<p><em>Note that the above initialization must be run every time a new new notebook/kernel is started or restarted.</em></p>
<p>After this you can import and access all of the Evennia system, same as with <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">shell</span></code>.</p>
</section>
<section id="more-exploration">
<h3>More exploration<a class="headerlink" href="#more-exploration" title="Permalink to this headline"></a></h3>
<p>You can complement your exploration by peeking at the sections of the much more detailed
<a class="reference internal" href="../Components/Components-Overview.html"><span class="doc std std-doc">Evennia Component overview</span></a>. The <a class="reference internal" href="../Howtos/Howtos-Overview.html"><span class="doc std std-doc">Tutorials</span></a> section also contains a growing collection
of system- or implementation-specific help.</p>
</section>
</section>
<section id="use-a-python-syntax-checker">
<h2>Use a python syntax checker<a class="headerlink" href="#use-a-python-syntax-checker" title="Permalink to this headline"></a></h2>
<p>Evennia works by importing your own modules and running them as part of the server. Whereas Evennia
should just gracefully tell you what errors it finds, it can nevertheless be a good idea for you to
check your code for simple syntax errors <em>before</em> you load it into the running server. There are
many python syntax checkers out there. A fast and easy one is
<a class="reference external" href="https://pypi.python.org/pypi/pyflakes">pyflakes</a>, a more verbose one is
<a class="reference external" href="https://www.pylint.org/">pylint</a>. You can also check so that your code looks up to snuff using
<a class="reference external" href="https://pypi.python.org/pypi/pep8">pep8</a>. Even with a syntax checker you will not be able to catch
every possible problem - some bugs or problems will only appear when you actually run the code. But
using such a checker can be a good start to weed out the simple problems.</p>
</section>
<section id="plan-before-you-code">
<h2>Plan before you code<a class="headerlink" href="#plan-before-you-code" title="Permalink to this headline"></a></h2>
<p>Before you start coding away at your dream game, take a look at our <a class="reference internal" href="../Howtos/Beginner-Tutorial/Part2/Beginner-Tutorial-Game-Planning.html"><span class="doc std std-doc">Game Planning</span></a>
page. It might hopefully help you avoid some common pitfalls and time sinks.</p>
</section>
<section id="code-in-your-game-folder-not-in-the-evennia-repository">
<h2>Code in your game folder, not in the evennia/ repository<a class="headerlink" href="#code-in-your-game-folder-not-in-the-evennia-repository" title="Permalink to this headline"></a></h2>
<p>As part of the Evennia setup you will create a game folder to host your game code. This is your
home. You should <em>never</em> need to modify anything in the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> library (anything you download
from us, really). You import useful functionality from here and if you see code you like, copy&amp;paste
it out into your game folder and edit it there.</p>
<p>If you find that Evennia doesn’t support some functionality you need, make a Feature Request about it. Same goes for bugs. If you add features or fix bugs yourself, please consider <a class="reference internal" href="../Contributing.html"><span class="doc std std-doc">Contributing</span></a> your changes upstream!</p>
</section>
<section id="learn-to-read-tracebacks">
<h2>Learn to read tracebacks<a class="headerlink" href="#learn-to-read-tracebacks" title="Permalink to this headline"></a></h2>
<p>Python is very good at reporting when and where things go wrong. A <em>traceback</em> shows everything you
need to know about crashing code. The text can be pretty long, but you usually are only interested
in the last bit, where it says what the error is and at which module and line number it happened -
armed with this info you can resolve most problems.</p>
<p>Evennia will usually not show the full traceback in-game though. Instead the server outputs errors
to the terminal/console from which you started Evennia in the first place. If you want more to show
in-game you can add <code class="docutils literal notranslate"><span class="pre">IN_GAME_ERRORS</span> <span class="pre">=</span> <span class="pre">True</span></code> to your settings file. This will echo most (but not all)
tracebacks both in-game as well as to the terminal/console. This is a potential security problem
though, so don’t keep this active when your game goes into production.</p>
<blockquote>
<div><p>A common confusing error is finding that objects in-game are suddenly of the type <code class="docutils literal notranslate"><span class="pre">DefaultObject</span></code>
rather than your custom typeclass. This happens when you introduce a critical Syntax error to the
module holding your custom class. Since such a module is not valid Python, Evennia can’t load it at
all. Instead of crashing, Evennia will then print the full traceback to the terminal/console and
temporarily fall back to the safe <code class="docutils literal notranslate"><span class="pre">DefaultObject</span></code> until you fix the problem and reload.</p>
</div></blockquote>
</section>
<section id="docs-are-here-to-help-you">
<h2>Docs are here to help you<a class="headerlink" href="#docs-are-here-to-help-you" title="Permalink to this headline"></a></h2>
<p>Some people find reading documentation extremely dull and shun it out of principle. That’s your
call, but reading docs really <em>does</em> help you, promise! Evennia’s documentation is pretty thorough
and knowing what is possible can often give you a lot of new cool game ideas. That said, if you
can’t find the answer in the docs, don’t be shy to ask questions! The <a class="reference external" href="https://sites.google.com/site/evenniaserver/discussions">discussion
group</a> and the <a class="reference external" href="https://webchat.freenode.net/?channels=evennia">irc
chat</a> are also there for you.</p>
</section>
<section id="the-most-important-point">
<h2>The most important point<a class="headerlink" href="#the-most-important-point" title="Permalink to this headline"></a></h2>
<p>And finally, of course, have fun!</p>
</section>
</section>
</div>
</div>
</div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Coding-FAQ.html" title="Coding FAQ"
>next</a> |</li>
<li class="right" >
<a href="Updating-Your-Game.html" title="Updating Your Game"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Coding-Overview.html" >Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Coding Introduction</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2022, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
</div>
</body>
</html>

100
docs/1.0-dev/Coding/Coding-Overview.html
View file

@ -17,7 +17,7 @@
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Version Control" href="Version-Control.html" />
<link rel="next" title="Coding using Version Control" href="Version-Control.html" />
<link rel="prev" title="Web Features" href="../Concepts/Web-Features.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
@ -30,7 +30,7 @@
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Version-Control.html" title="Version Control"
<a href="Version-Control.html" title="Coding using Version Control"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="../Concepts/Web-Features.html" title="Web Features"
@ -62,8 +62,6 @@
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Coding and development help</a><ul>
<li><a class="reference internal" href="#setting-up-a-workflow">Setting up a workflow</a></li>
<li><a class="reference internal" href="#coding-away">Coding away</a></li>
<li><a class="reference internal" href="#evennia-changelog">Evennia Changelog</a></li>
<li><a class="reference internal" href="#third-party-integrations">Third-party integrations</a></li>
</ul>
@ -75,7 +73,7 @@
title="previous chapter">Web Features</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Version-Control.html"
title="next chapter">Version Control</a></p>
title="next chapter">Coding using Version Control</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
@ -110,60 +108,15 @@
<h1>Coding and development help<a class="headerlink" href="#coding-and-development-help" title="Permalink to this headline"></a></h1>
<p>This documentation aims to help you set up a sane development environment to
make your game, also if you never coded before. If you are an experienced coder, much of this will be familiar to you, but some things may still be useful.</p>
<section id="setting-up-a-workflow">
<h2>Setting up a workflow<a class="headerlink" href="#setting-up-a-workflow" title="Permalink to this headline"></a></h2>
<p>See also the <a class="reference internal" href="../Howtos/Beginner-Tutorial/Beginner-Tutorial-Overview.html"><span class="doc std std-doc">Beginner Tutorial</span></a>.</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Version-Control.html">Version Control</a><ul>
<li class="toctree-l1"><a class="reference internal" href="Version-Control.html">Coding using Version Control</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Version-Control.html#setting-up-git">Setting up Git</a></li>
<li class="toctree-l2"><a class="reference internal" href="Version-Control.html#putting-your-game-folder-under-version-control">Putting your game folder under version control</a></li>
<li class="toctree-l2"><a class="reference internal" href="Version-Control.html#forking-evennia">Forking Evennia</a></li>
<li class="toctree-l2"><a class="reference internal" href="Version-Control.html#working-with-your-evennia-fork">Working with your Evennia fork</a></li>
<li class="toctree-l2"><a class="reference internal" href="Version-Control.html#sharing-your-evennia-fixes-on-github">Sharing your Evennia fixes on Github</a></li>
<li class="toctree-l2"><a class="reference internal" href="Version-Control.html#making-an-evennia-pull-request">Making an Evennia Pull Request</a></li>
<li class="toctree-l2"><a class="reference internal" href="Version-Control.html#git-tips-and-tricks">GIT tips and tricks</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Updating-Your-Game.html">Updating Your Game</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Updating-Your-Game.html#updating-with-the-latest-evennia-code-changes">Updating with the latest Evennia code changes</a></li>
<li class="toctree-l2"><a class="reference internal" href="Updating-Your-Game.html#upgrading-evennia-dependencies">Upgrading Evennia dependencies</a></li>
<li class="toctree-l2"><a class="reference internal" href="Updating-Your-Game.html#migrating-the-database-schema">Migrating the Database Schema</a></li>
<li class="toctree-l2"><a class="reference internal" href="Updating-Your-Game.html#resetting-your-database">Resetting your database</a></li>
<li class="toctree-l2"><a class="reference internal" href="Updating-Your-Game.html#more-about-schema-migrations">More about schema migrations</a></li>
</ul>
</li>
</ul>
</div>
</section>
<section id="coding-away">
<h2>Coding away<a class="headerlink" href="#coding-away" title="Permalink to this headline"></a></h2>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Coding-Introduction.html">Coding Introduction</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Coding-Introduction.html#start-with-the-tutorial">Start with the tutorial</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-Introduction.html#explore-evennia-interactively">Explore Evennia interactively</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-Introduction.html#use-a-python-syntax-checker">Use a python syntax checker</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-Introduction.html#plan-before-you-code">Plan before you code</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-Introduction.html#code-in-your-game-folder-not-in-the-evennia-repository">Code in your game folder, not in the evennia/ repository</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-Introduction.html#learn-to-read-tracebacks">Learn to read tracebacks</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-Introduction.html#docs-are-here-to-help-you">Docs are here to help you</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-Introduction.html#the-most-important-point">The most important point</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Coding-FAQ.html">Coding FAQ</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#table-of-contents">Table of Contents</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#removing-default-commands">Removing default commands</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#preventing-character-from-moving-based-on-a-condition">Preventing character from moving based on a condition</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#reference-initiating-object-in-an-evmenu-command">Reference initiating object in an EvMenu command.</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#adding-color-to-default-evennia-channels">Adding color to default Evennia Channels</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#selectively-turn-off-commands-in-a-room">Selectively turn off commands in a room</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#select-command-based-on-a-condition">Select Command based on a condition</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#automatically-updating-code-when-reloading">Automatically updating code when reloading</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#changing-all-exit-messages">Changing all exit messages</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#add-parsing-with-the-to-delimiter">Add parsing with the “to” delimiter</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#store-last-used-session-ip-address">Store last used session IP address</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#non-latin-characters-in-evtable">Non-latin characters in EvTable</a></li>
<li class="toctree-l2"><a class="reference internal" href="Version-Control.html#common-git-commands">Common Git commands</a></li>
<li class="toctree-l2"><a class="reference internal" href="Version-Control.html#putting-your-game-dir-under-version-control">Putting your game dir under version control</a></li>
<li class="toctree-l2"><a class="reference internal" href="Version-Control.html#contributing-to-evennia">Contributing to Evennia</a></li>
<li class="toctree-l2"><a class="reference internal" href="Version-Control.html#troubleshooting">Troubleshooting</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Debugging.html">Debugging</a><ul>
@ -182,12 +135,30 @@ make your game, also if you never coded before. If you are an experienced coder,
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Profiling.html">Profiling</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Profiling.html#introduction">Introduction</a></li>
<li class="toctree-l2"><a class="reference internal" href="Profiling.html#simple-timer-tests">Simple timer tests</a></li>
<li class="toctree-l2"><a class="reference internal" href="Profiling.html#using-cprofile">Using cProfile</a></li>
<li class="toctree-l2"><a class="reference internal" href="Profiling.html#the-dummyrunner">The Dummyrunner</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Evennia-Code-Style.html">Evennia Code Style</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Evennia-Code-Style.html#main-code-style-specification">Main code style specification</a></li>
<li class="toctree-l2"><a class="reference internal" href="Evennia-Code-Style.html#code-docstrings">Code Docstrings</a></li>
<li class="toctree-l2"><a class="reference internal" href="Evennia-Code-Style.html#default-command-docstrings">Default Command Docstrings</a></li>
<li class="toctree-l2"><a class="reference internal" href="Evennia-Code-Style.html#tools-for-auto-linting">Tools for auto-linting</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Coding-FAQ.html">Coding FAQ</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#removing-default-commands">Removing default commands</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#preventing-character-from-moving-based-on-a-condition">Preventing character from moving based on a condition</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#reference-initiating-object-in-an-evmenu-command">Reference initiating object in an EvMenu command.</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#selectively-turn-off-commands-in-a-room">Selectively turn off commands in a room</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#select-command-based-on-a-condition">Select Command based on a condition</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#automatically-updating-code-when-reloading">Automatically updating code when reloading</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#changing-all-exit-messages">Changing all exit messages</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#add-parsing-with-the-to-delimiter">Add parsing with the “to” delimiter</a></li>
<li class="toctree-l2"><a class="reference internal" href="Coding-FAQ.html#non-latin-characters-in-evtable">Non-latin characters in EvTable</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Quirks.html">Quirks</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Quirks.html#forgetting-to-use-reload-to-see-changes-to-your-typeclasses">Forgetting to use <code class="docutils literal notranslate"><span class="pre">reload</span></code> to see changes to your typeclasses</a></li>
<li class="toctree-l2"><a class="reference internal" href="Quirks.html#web-admin-to-create-new-account">Web admin to create new Account</a></li>
@ -200,7 +171,6 @@ make your game, also if you never coded before. If you are an experienced coder,
</li>
</ul>
</div>
</section>
<section id="evennia-changelog">
<h2>Evennia Changelog<a class="headerlink" href="#evennia-changelog" title="Permalink to this headline"></a></h2>
<div class="toctree-wrapper compound">
@ -242,18 +212,8 @@ make your game, also if you never coded before. If you are an experienced coder,
<h2>Third-party integrations<a class="headerlink" href="#third-party-integrations" title="Permalink to this headline"></a></h2>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Continuous-Integration.html">Continuous Integration</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Continuous-Integration.html#what-is-continuous-integration-ci">What is Continuous Integration (CI)?</a></li>
<li class="toctree-l2"><a class="reference internal" href="Continuous-Integration.html#list-of-continuous-integration-tools">List of continuous integration tools</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Setting-up-PyCharm.html">Setting up PyCharm with Evennia</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Setting-up-PyCharm.html#setting-up-the-project-interpreter">Setting up the project interpreter</a></li>
<li class="toctree-l2"><a class="reference internal" href="Setting-up-PyCharm.html#attaching-pycharm-debugger-to-evennia">Attaching PyCharm debugger to Evennia</a></li>
<li class="toctree-l2"><a class="reference internal" href="Setting-up-PyCharm.html#setting-up-an-evennia-run-configuration">Setting up an Evennia run configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="Setting-up-PyCharm.html#alternative-run-configuration-utilizing-logfiles-as-source-of-data">Alternative run configuration - utilizing logfiles as source of data</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Continuous-Integration.html">Continuous Integration (CI)</a></li>
<li class="toctree-l1"><a class="reference internal" href="Setting-up-PyCharm.html">Setting up PyCharm with Evennia</a></li>
</ul>
</div>
</section>
@ -275,7 +235,7 @@ make your game, also if you never coded before. If you are an experienced coder,
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Version-Control.html" title="Version Control"
<a href="Version-Control.html" title="Coding using Version Control"
>next</a> |</li>
<li class="right" >
<a href="../Concepts/Web-Features.html" title="Web Features"

4
docs/1.0-dev/Coding/Continuous-Integration-TeamCity.html
View file

@ -37,7 +37,7 @@
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Coding-Overview.html" >Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="Continuous-Integration.html" accesskey="U">Continuous Integration</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="Continuous-Integration.html" accesskey="U">Continuous Integration (CI)</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Continuous Integration - TeamCity (linux)</a></li>
</ul>
<div class="develop">develop branch</div>
@ -315,7 +315,7 @@ build steps could be added or removed at this point, adding some features like U
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Coding-Overview.html" >Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="Continuous-Integration.html" >Continuous Integration</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="Continuous-Integration.html" >Continuous Integration (CI)</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Continuous Integration - TeamCity (linux)</a></li>
</ul>
<div class="develop">develop branch</div>

12
docs/1.0-dev/Coding/Continuous-Integration-Travis.html
View file

@ -18,7 +18,7 @@
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Continuous Integration - TeamCity (linux)" href="Continuous-Integration-TeamCity.html" />
<link rel="prev" title="Continuous Integration" href="Continuous-Integration.html" />
<link rel="prev" title="Continuous Integration (CI)" href="Continuous-Integration.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
@ -33,11 +33,11 @@
<a href="Continuous-Integration-TeamCity.html" title="Continuous Integration - TeamCity (linux)"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Continuous-Integration.html" title="Continuous Integration"
<a href="Continuous-Integration.html" title="Continuous Integration (CI)"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Coding-Overview.html" >Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="Continuous-Integration.html" accesskey="U">Continuous Integration</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="Continuous-Integration.html" accesskey="U">Continuous Integration (CI)</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Continuous integration with Travis</a></li>
</ul>
<div class="develop">develop branch</div>
@ -63,7 +63,7 @@
<script>$('#searchbox').show(0);</script>
<h4>Previous topic</h4>
<p class="topless"><a href="Continuous-Integration.html"
title="previous chapter">Continuous Integration</a></p>
title="previous chapter">Continuous Integration (CI)</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Continuous-Integration-TeamCity.html"
title="next chapter">Continuous Integration - TeamCity (linux)</a></p>
@ -151,11 +151,11 @@ You should be able to refer to that for making tests fitting your game.</p>
<a href="Continuous-Integration-TeamCity.html" title="Continuous Integration - TeamCity (linux)"
>next</a> |</li>
<li class="right" >
<a href="Continuous-Integration.html" title="Continuous Integration"
<a href="Continuous-Integration.html" title="Continuous Integration (CI)"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Coding-Overview.html" >Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="Continuous-Integration.html" >Continuous Integration</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="Continuous-Integration.html" >Continuous Integration (CI)</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Continuous integration with Travis</a></li>
</ul>
<div class="develop">develop branch</div>

36
docs/1.0-dev/Coding/Continuous-Integration.html
View file

@ -6,7 +6,7 @@
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Continuous Integration &#8212; Evennia 1.0-dev documentation</title>
<title>Continuous Integration (CI) &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
@ -37,7 +37,7 @@
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Coding-Overview.html" accesskey="U">Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Continuous Integration</a></li>
<li class="nav-item nav-item-this"><a href="">Continuous Integration (CI)</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
@ -62,9 +62,8 @@
<script>$('#searchbox').show(0);</script>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Continuous Integration</a><ul>
<li><a class="reference internal" href="#what-is-continuous-integration-ci">What is Continuous Integration (CI)?</a></li>
<li><a class="reference internal" href="#list-of-continuous-integration-tools">List of continuous integration tools</a></li>
<li><a class="reference internal" href="#">Continuous Integration (CI)</a><ul>
<li><a class="reference internal" href="#list-of-ci-evennia-tutorials">List of CI Evennia tutorials</a></li>
</ul>
</li>
</ul>
@ -105,16 +104,10 @@
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="continuous-integration">
<h1>Continuous Integration<a class="headerlink" href="#continuous-integration" title="Permalink to this headline"></a></h1>
<p>One of the advantages of Evennia over traditional MU* development systems is that Evennia can
integrate into enterprise-level integration environments and source control.</p>
<section id="what-is-continuous-integration-ci">
<h2>What is Continuous Integration (CI)?<a class="headerlink" href="#what-is-continuous-integration-ci" title="Permalink to this headline"></a></h2>
<p><a class="reference external" href="https://www.thoughtworks.com/continuous-integration">Continuous Integration (CI)</a> is a development
practice that requires developers to integrate code into a shared repository.
Each check-in is then verified by an automated build, allowing teams to detect problems early. This
can be set up to safely deploy data to a production server only after tests have passed, for example.</p>
<section class="tex2jax_ignore mathjax_ignore" id="continuous-integration-ci">
<h1>Continuous Integration (CI)<a class="headerlink" href="#continuous-integration-ci" title="Permalink to this headline"></a></h1>
<p>One of the advantages of Evennia over traditional MU* development systems is that Evennia can integrate into enterprise-level integration environments and source control.</p>
<p><a class="reference external" href="https://www.thoughtworks.com/continuous-integration">Continuous Integration (CI)</a> is a development practice that requires developers to integrate code into a shared repository. Each check-in is then verified by an automated build, allowing teams to detect problems early. This can be set up to safely deploy data to a production server only after tests have passed, for example.</p>
<p>For Evennia, continuous integration allows an automated build process to:</p>
<ul class="simple">
<li><p>Pull down a latest build from Source Control.</p></li>
@ -124,19 +117,16 @@ can be set up to safely deploy data to a production server only after tests have
<li><p>Publish those files to the server directory</p></li>
<li><p>Reload the game.</p></li>
</ul>
</section>
<section id="list-of-continuous-integration-tools">
<h2>List of continuous integration tools<a class="headerlink" href="#list-of-continuous-integration-tools" title="Permalink to this headline"></a></h2>
<p>There are a lot of tools and services providing CI functionality. Here are a few that people have used
with Evennia:</p>
<section id="list-of-ci-evennia-tutorials">
<h2>List of CI Evennia tutorials<a class="headerlink" href="#list-of-ci-evennia-tutorials" title="Permalink to this headline"></a></h2>
<p>There are a lot of tools and services providing CI functionality. Here are a few that people have used with Evennia:</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Continuous-Integration-Travis.html">Continuous integration with Travis</a></li>
<li class="toctree-l1"><a class="reference internal" href="Continuous-Integration-TeamCity.html">Continuous Integration - TeamCity (linux)</a></li>
</ul>
</div>
<p><a class="reference external" href="https://www.atlassian.com/continuous-delivery/continuous-integration/tools">This is an overview of other tools</a>
(external link).</p>
<p><a class="reference external" href="https://www.atlassian.com/continuous-delivery/continuous-integration/tools">This is an overview of other tools</a> (external link).</p>
</section>
</section>
@ -163,7 +153,7 @@ with Evennia:</p>
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Coding-Overview.html" >Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Continuous Integration</a></li>
<li class="nav-item nav-item-this"><a href="">Continuous Integration (CI)</a></li>
</ul>
<div class="develop">develop branch</div>
</div>

87
docs/1.0-dev/Coding/Debugging.html
View file

@ -18,7 +18,7 @@
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Unit Testing" href="Unit-Testing.html" />
<link rel="prev" title="Coding FAQ" href="Coding-FAQ.html" />
<link rel="prev" title="Coding using Version Control" href="Version-Control.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
@ -33,7 +33,7 @@
<a href="Unit-Testing.html" title="Unit Testing"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Coding-FAQ.html" title="Coding FAQ"
<a href="Version-Control.html" title="Coding using Version Control"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Coding-Overview.html" accesskey="U">Coding and development help</a> &#187;</li>
@ -69,7 +69,6 @@
<li><a class="reference internal" href="#examining-variables">Examining variables</a></li>
<li><a class="reference internal" href="#executing-the-current-line">Executing the current line</a></li>
<li><a class="reference internal" href="#letting-the-program-run">Letting the program run</a></li>
<li><a class="reference internal" href="#stepping-through-a-function">Stepping through a function</a></li>
</ul>
</li>
<li><a class="reference internal" href="#cheat-sheet-of-pdb-pudb-commands">Cheat-sheet of pdb/pudb commands</a></li>
@ -78,8 +77,8 @@
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="Coding-FAQ.html"
title="previous chapter">Coding FAQ</a></p>
<p class="topless"><a href="Version-Control.html"
title="previous chapter">Coding using Version Control</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Unit-Testing.html"
title="next chapter">Unit Testing</a></p>
@ -115,12 +114,8 @@
<section class="tex2jax_ignore mathjax_ignore" id="debugging">
<h1>Debugging<a class="headerlink" href="#debugging" title="Permalink to this headline"></a></h1>
<p>Sometimes, an error is not trivial to resolve. A few simple <code class="docutils literal notranslate"><span class="pre">print</span></code> statements is not enough to find
the cause of the issue. Running a <em>debugger</em> can then be very helpful and save a lot of time.
Debugging
means running Evennia under control of a special <em>debugger</em> program. This allows you to stop the
action at a given point, view the current state and step forward through the program to see how its
logic works.</p>
<p>Sometimes, an error is not trivial to resolve. A few simple <code class="docutils literal notranslate"><span class="pre">print</span></code> statements is not enough to find the cause of the issue. The traceback is not informative or even non-existing.</p>
<p>Running a <em>debugger</em> can then be very helpful and save a lot of time. Debugging means running Evennia under control of a special <em>debugger</em> program. This allows you to stop the action at a given point, view the current state and step forward through the program to see how its logic works.</p>
<p>Evennia natively supports these debuggers:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://docs.python.org/2/library/pdb.html">Pdb</a> is a part of the Python distribution and
@ -138,18 +133,14 @@ point.</p>
</pre></div>
</div>
</li>
<li><p>(Re-)start Evennia in interactive (foreground) mode with <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">istart</span></code>. This is important -
without this step the debugger will not start correctly - it will start in this interactive
terminal.</p></li>
<li><p>Perform the steps that will trigger the line where you added the <code class="docutils literal notranslate"><span class="pre">set_trace()</span></code> call. The debugger
will start in the terminal from which Evennia was interactively started.</p></li>
<li><p>(Re-)start Evennia in interactive (foreground) mode with <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">istart</span></code>. This is important - without this step the debugger will not start correctly - it will start in this interactive terminal.</p></li>
<li><p>Perform the steps that will trigger the line where you added the <code class="docutils literal notranslate"><span class="pre">set_trace()</span></code> call. The debugger will start in the terminal from which Evennia was interactively started.</p></li>
</ol>
<p>The <code class="docutils literal notranslate"><span class="pre">evennia.set_trace</span></code> function takes the following arguments:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="n">evennia</span><span class="o">.</span><span class="n">set_trace</span><span class="p">(</span><span class="n">debugger</span><span class="o">=</span><span class="s1">&#39;auto&#39;</span><span class="p">,</span> <span class="n">term_size</span><span class="o">=</span><span class="p">(</span><span class="mi">140</span><span class="p">,</span> <span class="mi">40</span><span class="p">))</span>
</pre></div>
</div>
<p>Here, <code class="docutils literal notranslate"><span class="pre">debugger</span></code> is one of <code class="docutils literal notranslate"><span class="pre">pdb</span></code>, <code class="docutils literal notranslate"><span class="pre">pudb</span></code> or <code class="docutils literal notranslate"><span class="pre">auto</span></code>. If <code class="docutils literal notranslate"><span class="pre">auto</span></code>, use <code class="docutils literal notranslate"><span class="pre">pudb</span></code> if available, otherwise
use <code class="docutils literal notranslate"><span class="pre">pdb</span></code>. The <code class="docutils literal notranslate"><span class="pre">term_size</span></code> tuple sets the viewport size for <code class="docutils literal notranslate"><span class="pre">pudb</span></code> only (it’s ignored by <code class="docutils literal notranslate"><span class="pre">pdb</span></code>).</p>
<p>Here, <code class="docutils literal notranslate"><span class="pre">debugger</span></code> is one of <code class="docutils literal notranslate"><span class="pre">pdb</span></code>, <code class="docutils literal notranslate"><span class="pre">pudb</span></code> or <code class="docutils literal notranslate"><span class="pre">auto</span></code>. If <code class="docutils literal notranslate"><span class="pre">auto</span></code>, use <code class="docutils literal notranslate"><span class="pre">pudb</span></code> if available, otherwise use <code class="docutils literal notranslate"><span class="pre">pdb</span></code>. The <code class="docutils literal notranslate"><span class="pre">term_size</span></code> tuple sets the viewport size for <code class="docutils literal notranslate"><span class="pre">pudb</span></code> only (it’s ignored by <code class="docutils literal notranslate"><span class="pre">pdb</span></code>).</p>
</section>
<section id="a-simple-example-using-pdb">
<h2>A simple example using pdb<a class="headerlink" href="#a-simple-example-using-pdb" title="Permalink to this headline"></a></h2>
@ -178,9 +169,7 @@ default cmdset. Then restart Evennia in interactive mode with <code class="docut
</pre></div>
</div>
<p>If you type <code class="docutils literal notranslate"><span class="pre">test</span></code> in your game, everything will freeze. You won’t get any feedback from the game,
and you won’t be able to enter any command (nor anyone else). It’s because the debugger has started
in your console, and you will find it here. Below is an example with <code class="docutils literal notranslate"><span class="pre">pdb</span></code>.</p>
<p>If you type <code class="docutils literal notranslate"><span class="pre">test</span></code> in your game, everything will freeze. You won’t get any feedback from the game, and you won’t be able to enter any command (nor anyone else). It’s because the debugger has started in your console, and you will find it here. Below is an example with <code class="docutils literal notranslate"><span class="pre">pdb</span></code>.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">...</span>
<span class="o">&gt;</span> <span class="o">.../</span><span class="n">mygame</span><span class="o">/</span><span class="n">commands</span><span class="o">/</span><span class="n">command</span><span class="o">.</span><span class="n">py</span><span class="p">(</span><span class="mi">79</span><span class="p">)</span><span class="n">func</span><span class="p">()</span>
<span class="o">-&gt;</span> <span class="n">obj</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">args</span><span class="p">)</span>
@ -191,8 +180,7 @@ in your console, and you will find it here. Below is an example with <code class
<p><code class="docutils literal notranslate"><span class="pre">pdb</span></code> notes where it has stopped execution and, what line is about to be executed (in our case, <code class="docutils literal notranslate"><span class="pre">obj</span> <span class="pre">=</span> <span class="pre">self.search(self.args)</span></code>), and ask what you would like to do.</p>
<section id="listing-surrounding-lines-of-code">
<h3>Listing surrounding lines of code<a class="headerlink" href="#listing-surrounding-lines-of-code" title="Permalink to this headline"></a></h3>
<p>When you have the <code class="docutils literal notranslate"><span class="pre">pdb</span></code> prompt <code class="docutils literal notranslate"><span class="pre">(Pdb)</span></code>, you can type in different commands to explore the code. The
first one you should know is <code class="docutils literal notranslate"><span class="pre">list</span></code> (you can type <code class="docutils literal notranslate"><span class="pre">l</span></code> for short):</p>
<p>When you have the <code class="docutils literal notranslate"><span class="pre">pdb</span></code> prompt <code class="docutils literal notranslate"><span class="pre">(Pdb)</span></code>, you can type in different commands to explore the code. The first one you should know is <code class="docutils literal notranslate"><span class="pre">list</span></code> (you can type <code class="docutils literal notranslate"><span class="pre">l</span></code> for short):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">Pdb</span><span class="p">)</span> <span class="n">l</span>
<span class="mi">43</span>
<span class="mi">44</span> <span class="n">key</span> <span class="o">=</span> <span class="s2">&quot;test&quot;</span>
@ -208,17 +196,12 @@ first one you should know is <code class="docutils literal notranslate"><span cl
<span class="p">(</span><span class="n">Pdb</span><span class="p">)</span>
</pre></div>
</div>
<p>Okay, this didn’t do anything spectacular, but when you become more confident with <code class="docutils literal notranslate"><span class="pre">pdb</span></code> and find
yourself in lots of different files, you sometimes need to see what’s around in code. Notice that
there is a little arrow (<code class="docutils literal notranslate"><span class="pre">-&gt;</span></code>) before the line that is about to be executed.</p>
<p>This is important: <strong>about to be</strong>, not <strong>has just been</strong>. You need to tell <code class="docutils literal notranslate"><span class="pre">pdb</span></code> to go on (we’ll
soon see how).</p>
<p>Okay, this didn’t do anything spectacular, but when you become more confident with <code class="docutils literal notranslate"><span class="pre">pdb</span></code> and find yourself in lots of different files, you sometimes need to see what’s around in code. Notice that there is a little arrow (<code class="docutils literal notranslate"><span class="pre">-&gt;</span></code>) before the line that is about to be executed.</p>
<p>This is important: <strong>about to be</strong>, not <strong>has just been</strong>. You need to tell <code class="docutils literal notranslate"><span class="pre">pdb</span></code> to go on (we’ll soon see how).</p>
</section>
<section id="examining-variables">
<h3>Examining variables<a class="headerlink" href="#examining-variables" title="Permalink to this headline"></a></h3>
<p><code class="docutils literal notranslate"><span class="pre">pdb</span></code> allows you to examine variables (or really, to run any Python instruction). It is very useful
to know the values of variables at a specific line. To see a variable, just type its name (as if
you were in the Python interpreter:</p>
<p><code class="docutils literal notranslate"><span class="pre">pdb</span></code> allows you to examine variables (or really, to run any Python instruction). It is very useful to know the values of variables at a specific line. To see a variable, just type its name (as if you were in the Python interpreter:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">Pdb</span><span class="p">)</span> <span class="bp">self</span>
<span class="o">&lt;</span><span class="n">commands</span><span class="o">.</span><span class="n">command</span><span class="o">.</span><span class="n">CmdTest</span> <span class="nb">object</span> <span class="n">at</span> <span class="mh">0x045A0990</span><span class="o">&gt;</span>
<span class="p">(</span><span class="n">Pdb</span><span class="p">)</span> <span class="bp">self</span><span class="o">.</span><span class="n">args</span>
@ -253,26 +236,19 @@ shorten it by just typing <code class="docutils literal notranslate"><span class
<span class="p">(</span><span class="n">Pdb</span><span class="p">)</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">Pdb</span></code> is complaining that you try to call the <code class="docutils literal notranslate"><span class="pre">search</span></code> method on a command… whereas there’s no
<code class="docutils literal notranslate"><span class="pre">search</span></code> method on commands. The character executing the command is in <code class="docutils literal notranslate"><span class="pre">self.caller</span></code>, so we might
change our line:</p>
<p><code class="docutils literal notranslate"><span class="pre">Pdb</span></code> is complaining that you try to call the <code class="docutils literal notranslate"><span class="pre">search</span></code> method on a command… whereas there’s no <code class="docutils literal notranslate"><span class="pre">search</span></code> method on commands. The character executing the command is in <code class="docutils literal notranslate"><span class="pre">self.caller</span></code>, so we might change our line:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">obj</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">caller</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">args</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="letting-the-program-run">
<h3>Letting the program run<a class="headerlink" href="#letting-the-program-run" title="Permalink to this headline"></a></h3>
<p><code class="docutils literal notranslate"><span class="pre">pdb</span></code> is waiting to execute the same instruction… it provoked an error but it’s ready to try
again, just in case. We have fixed it in theory, but we need to reload, so we need to enter a
command. To tell <code class="docutils literal notranslate"><span class="pre">pdb</span></code> to terminate and keep on running the program, use the <code class="docutils literal notranslate"><span class="pre">continue</span></code> (or <code class="docutils literal notranslate"><span class="pre">c</span></code>)
command:</p>
<p><code class="docutils literal notranslate"><span class="pre">pdb</span></code> is waiting to execute the same instruction… it provoked an error but it’s ready to try again, just in case. We have fixed it in theory, but we need to reload, so we need to enter a command. To tell <code class="docutils literal notranslate"><span class="pre">pdb</span></code> to terminate and keep on running the program, use the <code class="docutils literal notranslate"><span class="pre">continue</span></code> (or <code class="docutils literal notranslate"><span class="pre">c</span></code>) command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">Pdb</span><span class="p">)</span> <span class="n">c</span>
<span class="o">...</span>
</pre></div>
</div>
<p>You see an error being caught, that’s the error we have fixed… or hope to have. Let’s reload the
game and try again. You need to run <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">istart</span></code> again and then run <code class="docutils literal notranslate"><span class="pre">test</span></code> to get into the
command again.</p>
<p>You see an error being caught, that’s the error we have fixed… or hope to have. Let’s reload the game and try again. You need to run <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">istart</span></code> again and then run <code class="docutils literal notranslate"><span class="pre">test</span></code> to get into the command again.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">&gt;</span> <span class="o">.../</span><span class="n">mygame</span><span class="o">/</span><span class="n">commands</span><span class="o">/</span><span class="n">command</span><span class="o">.</span><span class="n">py</span><span class="p">(</span><span class="mi">79</span><span class="p">)</span><span class="n">func</span><span class="p">()</span>
<span class="o">-&gt;</span> <span class="n">obj</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">caller</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">args</span><span class="p">)</span>
<span class="p">(</span><span class="n">Pdb</span><span class="p">)</span>
@ -301,8 +277,7 @@ fix that bug too, it would be better):</p>
<span class="o">...</span>
</pre></div>
</div>
<p>Notice that you’ll have an error in the game this time. Let’s try with a valid parameter. I have
another character, <code class="docutils literal notranslate"><span class="pre">barkeep</span></code>, in this room:</p>
<p>Notice that you’ll have an error in the game this time. Let’s try with a valid parameter. I have another character, <code class="docutils literal notranslate"><span class="pre">barkeep</span></code>, in this room:</p>
<p><code class="docutils literal notranslate"><span class="pre">test</span> <span class="pre">barkeep</span></code></p>
<p>And again, the command freezes, and we have the debugger opened in the console.</p>
<p>Let’s execute this line right away:</p>
@ -324,32 +299,17 @@ another character, <code class="docutils literal notranslate"><span class="pre">
<span class="p">(</span><span class="n">Pdb</span><span class="p">)</span>
</pre></div>
</div>
<p>As an exercise, fix this error, reload and run the debugger again. Nothing better than some
experimenting!</p>
<p>As an exercise, fix this error, reload and run the debugger again. Nothing better than some experimenting!</p>
<p>Your debugging will often follow the same strategy:</p>
<ol class="simple">
<li><p>Receive an error you don’t understand.</p></li>
<li><p>Put a breaking point <strong>BEFORE</strong> the error occurs.</p></li>
<li><p>Run <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">istart</span></code></p></li>
<li><p>Run the code again and see the debugger open.</p></li>
<li><p>Run the program line by line,examining variables, checking the logic of instructions.</p></li>
<li><p>Run the program line by line, examining variables, checking the logic of instructions.</p></li>
<li><p>Continue and try again, each step a bit further toward the truth and the working feature.</p></li>
</ol>
</section>
<section id="stepping-through-a-function">
<h3>Stepping through a function<a class="headerlink" href="#stepping-through-a-function" title="Permalink to this headline"></a></h3>
<p><code class="docutils literal notranslate"><span class="pre">n</span></code> is useful, but it will avoid stepping inside of functions if it can. But most of the time, when
we have an error we don’t understand, it’s because we use functions or methods in a way that wasn’t
intended by the developer of the API. Perhaps using wrong arguments, or calling the function in a
situation that would cause a bug. When we have a line in the debugger that calls a function or
method, we can “step” to examine it further. For instance, in the previous example, when <code class="docutils literal notranslate"><span class="pre">pdb</span></code> was
about to execute <code class="docutils literal notranslate"><span class="pre">obj</span> <span class="pre">=</span> <span class="pre">self.caller.search(self.args)</span></code>, we may want to see what happens inside of
the <code class="docutils literal notranslate"><span class="pre">search</span></code> method.</p>
<p>To do so, use the <code class="docutils literal notranslate"><span class="pre">step</span></code> (or <code class="docutils literal notranslate"><span class="pre">s</span></code>) command. This command will show you the definition of the
function/method and you can then use <code class="docutils literal notranslate"><span class="pre">n</span></code> as before to see it line-by-line. In our little example,
stepping through a function or method isn’t that useful, but when you have an impressive set of
commands, functions and so on, it might really be handy to examine some feature and make sure they
operate as planned.</p>
</section>
</section>
<section id="cheat-sheet-of-pdb-pudb-commands">
<h2>Cheat-sheet of pdb/pudb commands<a class="headerlink" href="#cheat-sheet-of-pdb-pudb-commands" title="Permalink to this headline"></a></h2>
@ -391,8 +351,7 @@ command is not needed much in <code class="docutils literal notranslate"><span c
</tr>
</tbody>
</table>
<p>If you want to learn more about debugging with Pdb, you will find an <a class="reference external" href="https://pymotw.com/3/pdb/">interesting tutorial on that
topic here</a>.</p>
<p>If you want to learn more about debugging with Pdb, you will find an <a class="reference external" href="https://pymotw.com/3/pdb/">interesting tutorial on that topic here</a>.</p>
</section>
</section>
@ -415,7 +374,7 @@ topic here</a>.</p>
<a href="Unit-Testing.html" title="Unit Testing"
>next</a> |</li>
<li class="right" >
<a href="Coding-FAQ.html" title="Coding FAQ"
<a href="Version-Control.html" title="Coding using Version Control"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Coding-Overview.html" >Coding and development help</a> &#187;</li>

403
docs/1.0-dev/Coding/Evennia-Code-Style.html Normal file
View file

@ -0,0 +1,403 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Evennia Code Style &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Coding FAQ" href="Coding-FAQ.html" />
<link rel="prev" title="Profiling" href="Profiling.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Coding-FAQ.html" title="Coding FAQ"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Profiling.html" title="Profiling"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Coding-Overview.html" accesskey="U">Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Evennia Code Style</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Evennia Code Style</a><ul>
<li><a class="reference internal" href="#main-code-style-specification">Main code style specification</a></li>
<li><a class="reference internal" href="#code-docstrings">Code Docstrings</a><ul>
<li><a class="reference internal" href="#module-docstrings">Module docstrings</a></li>
<li><a class="reference internal" href="#class-docstrings">Class docstrings</a></li>
<li><a class="reference internal" href="#function-method-docstrings">Function / method docstrings</a></li>
</ul>
</li>
<li><a class="reference internal" href="#default-command-docstrings">Default Command Docstrings</a></li>
<li><a class="reference internal" href="#tools-for-auto-linting">Tools for auto-linting</a><ul>
<li><a class="reference internal" href="#black">black</a></li>
<li><a class="reference internal" href="#pycharm">PyCharm</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="Profiling.html"
title="previous chapter">Profiling</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Coding-FAQ.html"
title="next chapter">Coding FAQ</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Coding/Evennia-Code-Style.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div><h3>Links</h3>
<ul>
<li><a href="https://www.evennia.com">Home page</a> </li>
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
<h3>Versions</h3>
<ul>
<li><a href="Evennia-Code-Style.html">1.0-dev (develop branch)</a></li>
<ul>
<li><a href="../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="evennia-code-style">
<h1>Evennia Code Style<a class="headerlink" href="#evennia-code-style" title="Permalink to this headline"></a></h1>
<p>All code submitted or committed to the Evennia project should aim to follow the
guidelines outlined in <a class="reference external" href="http://www.python.org/dev/peps/pep-0008">Python PEP 8</a>. Keeping the code style uniform
makes it much easier for people to collaborate and read the code.</p>
<p>A good way to check if your code follows PEP8 is to use the <a class="reference external" href="https://pypi.python.org/pypi/pep8">PEP8 tool</a>
on your sources.</p>
<section id="main-code-style-specification">
<h2>Main code style specification<a class="headerlink" href="#main-code-style-specification" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p>4-space indentation, NO TABS!</p></li>
<li><p>Unix line endings.</p></li>
<li><p>100 character line widths</p></li>
<li><p>CamelCase is only used for classes, nothing else.</p></li>
<li><p>All non-global variable names and all function names are to be
lowercase, words separated by underscores. Variable names should
always be more than two letters long.</p></li>
<li><p>Module-level global variables (only) are to be in CAPITAL letters.</p></li>
<li><p>Imports should be done in this order:</p>
<ul>
<li><p>Python modules (builtins and standard library)</p></li>
<li><p>Twisted modules</p></li>
<li><p>Django modules</p></li>
<li><p>Evennia library modules (<code class="docutils literal notranslate"><span class="pre">evennia</span></code>)</p></li>
<li><p>Evennia contrib modules (<code class="docutils literal notranslate"><span class="pre">evennia.contrib</span></code>)</p></li>
</ul>
</li>
<li><p>All modules, classes, functions and methods should have doc strings formatted
as outlined below.</p></li>
<li><p>All default commands should have a consistent docstring formatted as
outlined below.</p></li>
</ul>
</section>
<section id="code-docstrings">
<h2>Code Docstrings<a class="headerlink" href="#code-docstrings" title="Permalink to this headline"></a></h2>
<p>All modules, classes, functions and methods should have docstrings
formatted with <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html">Google style</a> -inspired indents, using
<a class="reference external" href="https://help.github.com/articles/github-flavored-markdown/">Markdown</a> formatting where needed. Evennia’s <code class="docutils literal notranslate"><span class="pre">api2md</span></code>
parser will use this to create pretty API documentation.</p>
<section id="module-docstrings">
<h3>Module docstrings<a class="headerlink" href="#module-docstrings" title="Permalink to this headline"></a></h3>
<p>Modules should all start with at least a few lines of docstring at
their top describing the contents and purpose of the module.</p>
<p>Example of module docstring (top of file):</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">This module handles the creation of `Objects` that</span>
<span class="sd">are useful in the game ...</span>
<span class="sd">&quot;&quot;&quot;</span>
</pre></div>
</div>
<p>Sectioning (<code class="docutils literal notranslate"><span class="pre">#</span> <span class="pre">title</span></code>, <code class="docutils literal notranslate"><span class="pre">##</span> <span class="pre">subtile</span></code> etc) should not be used in
freeform docstrings - this will confuse the sectioning of the auto
documentation page and the auto-api will create this automatically.
Write just the section name bolded on its own line to mark a section.
Beyond sections markdown should be used as needed to format
the text.</p>
<p>Code examples should use <a class="reference external" href="https://help.github.com/articles/github-flavored-markdown/#syntax-highlighting">multi-line syntax highlighting</a>
to mark multi-line code blocks, using the “python” identifier. Just
indenting code blocks (common in markdown) will not produce the
desired look.</p>
<p>When using any code tags (inline or blocks) it’s recommended that you
don’t let the code extend wider than about 70 characters or it will
need to be scrolled horizontally in the wiki (this does not affect any
other text, only code).</p>
</section>
<section id="class-docstrings">
<h3>Class docstrings<a class="headerlink" href="#class-docstrings" title="Permalink to this headline"></a></h3>
<p>The root class docstring should describe the over-arching use of the
class. It should usually not describe the exact call sequence nor list
important methods, this tends to be hard to keep updated as the API
develops. Don’t use section markers (<code class="docutils literal notranslate"><span class="pre">#</span></code>, <code class="docutils literal notranslate"><span class="pre">##</span></code> etc).</p>
<p>Example of class docstring:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">MyClass</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> This class describes the creation of `Objects`. It is useful</span>
<span class="sd"> in many situations, such as ...</span>
<span class="sd"> &quot;&quot;&quot;</span>
</pre></div>
</div>
</section>
<section id="function-method-docstrings">
<h3>Function / method docstrings<a class="headerlink" href="#function-method-docstrings" title="Permalink to this headline"></a></h3>
<p>Example of function or method docstring:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span>
<span class="k">def</span> <span class="nf">funcname</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">,</span> <span class="n">c</span><span class="p">,</span> <span class="n">d</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> This is a brief introduction to the function/class/method</span>
<span class="sd"> Args:</span>
<span class="sd"> a (str): This is a string argument that we can talk about</span>
<span class="sd"> over multiple lines.</span>
<span class="sd"> b (int or str): Another argument.</span>
<span class="sd"> c (list): A list argument.</span>
<span class="sd"> d (bool, optional): An optional keyword argument.</span>
<span class="sd"> Keyword Args:</span>
<span class="sd"> test (list): A test keyword.</span>
<span class="sd"> Returns:</span>
<span class="sd"> str: The result of the function.</span>
<span class="sd"> Raises:</span>
<span class="sd"> RuntimeException: If there is a critical error,</span>
<span class="sd"> this is raised.</span>
<span class="sd"> IOError: This is only raised if there is a</span>
<span class="sd"> problem with the database.</span>
<span class="sd"> Notes:</span>
<span class="sd"> This is an example function. If `d=True`, something</span>
<span class="sd"> amazing will happen.</span>
<span class="sd"> &quot;&quot;&quot;</span>
</pre></div>
</div>
<p>The syntax is very “loose” but the indentation matters. That is, you
should end the block headers (like <code class="docutils literal notranslate"><span class="pre">Args:</span></code>) with a line break followed by
an indent. When you need to break a line you should start the next line
with another indent. For consistency with the code we recommend all
indents to be 4 spaces wide (no tabs!).</p>
<p>Here are all the supported block headers:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Args</span>
<span class="sd"> argname (freeform type): Description endind with period.</span>
<span class="sd"> Keyword Args:</span>
<span class="sd"> argname (freeform type): Description.</span>
<span class="sd"> Returns/Yields:</span>
<span class="sd"> type: Description.</span>
<span class="sd"> Raises:</span>
<span class="sd"> Exceptiontype: Description.</span>
<span class="sd"> Notes/Note/Examples/Example:</span>
<span class="sd"> Freeform text.</span>
<span class="sd"> &quot;&quot;&quot;</span>
</pre></div>
</div>
<p>Parts marked with “freeform” means that you can in principle put any
text there using any formatting except for sections markers (<code class="docutils literal notranslate"><span class="pre">#</span></code>, <code class="docutils literal notranslate"><span class="pre">##</span></code>
etc). You must also keep indentation to mark which block you are part
of. You should normally use the specified format rather than the
freeform counterpart (this will produce nicer output) but in some
cases the freeform may produce a more compact and readable result
(such as when describing an <code class="docutils literal notranslate"><span class="pre">*args</span></code> or <code class="docutils literal notranslate"><span class="pre">**kwargs</span></code> statement in general
terms). The first <code class="docutils literal notranslate"><span class="pre">self</span></code> argument of class methods should never be
documented.</p>
<p>Note that</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">Args:</span>
<span class="sd"> argname (type, optional): Description.</span>
<span class="sd">&quot;&quot;&quot;</span>
</pre></div>
</div>
<p>and</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">Keyword Args:</span>
<span class="sd"> sargname (type): Description.</span>
<span class="sd">&quot;&quot;&quot;</span>
</pre></div>
</div>
<p>mean the same thing! Which one is used depends on the function or
method documented, but there are no hard rules; If there is a large
<code class="docutils literal notranslate"><span class="pre">**kwargs</span></code> block in the function, using the <code class="docutils literal notranslate"><span class="pre">Keyword</span> <span class="pre">Args:</span></code> block may be a
good idea, for a small number of arguments though, just using <code class="docutils literal notranslate"><span class="pre">Args:</span></code>
and marking keywords as <code class="docutils literal notranslate"><span class="pre">optional</span></code> will shorten the docstring and make
it easier to read.</p>
</section>
</section>
<section id="default-command-docstrings">
<h2>Default Command Docstrings<a class="headerlink" href="#default-command-docstrings" title="Permalink to this headline"></a></h2>
<p>These represent a special case since Commands in Evennia use their class
docstrings to represent the in-game help entry for that command.</p>
<p>All the commands in the <em>default command</em> sets should have their doc-strings
formatted on a similar form. For contribs, this is loosened, but if there is
no particular reason to use a different form, one should aim to use the same
style for contrib-command docstrings as well.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Short header</span>
<span class="sd"> Usage:</span>
<span class="sd"> key[/switches, if any] &lt;mandatory args&gt; [optional] choice1||choice2||choice3</span>
<span class="sd"> Switches:</span>
<span class="sd"> switch1 - description</span>
<span class="sd"> switch2 - description</span>
<span class="sd"> Examples:</span>
<span class="sd"> Usage example and output</span>
<span class="sd"> Longer documentation detailing the command.</span>
<span class="sd"> &quot;&quot;&quot;</span>
</pre></div>
</div>
<ul class="simple">
<li><p>Two spaces are used for <em>indentation</em> in all default commands.</p></li>
<li><p>Square brackets <code class="docutils literal notranslate"><span class="pre">[</span> <span class="pre">]</span></code> surround <em>optional, skippable arguments</em>.</p></li>
<li><p>Angled brackets <code class="docutils literal notranslate"><span class="pre">&lt;</span> <span class="pre">&gt;</span></code> surround a <em>description</em> of what to write rather than the exact syntax.</p></li>
<li><p>Explicit choices are separated by <code class="docutils literal notranslate"><span class="pre">|</span></code>. To avoid this being parsed as a color code, use <code class="docutils literal notranslate"><span class="pre">||</span></code> (this
will come out as a single <code class="docutils literal notranslate"><span class="pre">|</span></code>) or put spaces around the character (“<code class="docutils literal notranslate"><span class="pre">|</span></code>”) if there’s plenty of room.</p></li>
<li><p>The <code class="docutils literal notranslate"><span class="pre">Switches</span></code> and <code class="docutils literal notranslate"><span class="pre">Examples</span></code> blocks are optional and based on the Command.</p></li>
</ul>
<p>Here is the <code class="docutils literal notranslate"><span class="pre">nick</span></code> command as an example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Define a personal alias/nick</span>
<span class="sd"> Usage:</span>
<span class="sd"> nick[/switches] &lt;nickname&gt; = [&lt;string&gt;]</span>
<span class="sd"> alias &#39;&#39;</span>
<span class="sd"> Switches:</span>
<span class="sd"> object - alias an object</span>
<span class="sd"> account - alias an account</span>
<span class="sd"> clearall - clear all your aliases</span>
<span class="sd"> list - show all defined aliases (also &quot;nicks&quot; works)</span>
<span class="sd"> Examples:</span>
<span class="sd"> nick hi = say Hello, I&#39;m Sarah!</span>
<span class="sd"> nick/object tom = the tall man</span>
<span class="sd"> A &#39;nick&#39; is a personal shortcut you create for your own use [...]</span>
<span class="sd"> &quot;&quot;&quot;</span>
</pre></div>
</div>
<p>For commands that <em>require arguments</em>, the policy is for it to return a <code class="docutils literal notranslate"><span class="pre">Usage:</span></code>
string if the command is entered without any arguments. So for such commands,
the Command body should contain something to the effect of</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="k">if</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">args</span><span class="p">:</span>
<span class="bp">self</span><span class="o">.</span><span class="n">caller</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="s2">&quot;Usage: nick[/switches] &lt;nickname&gt; = [&lt;string&gt;]&quot;</span><span class="p">)</span>
<span class="k">return</span>
</pre></div>
</div>
</section>
<section id="tools-for-auto-linting">
<h2>Tools for auto-linting<a class="headerlink" href="#tools-for-auto-linting" title="Permalink to this headline"></a></h2>
<section id="black">
<h3>black<a class="headerlink" href="#black" title="Permalink to this headline"></a></h3>
<p>Automatic pep8 compliant formatting and linting can be performed using the
<code class="docutils literal notranslate"><span class="pre">black</span></code> formatter:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>black --line-length 100
</pre></div>
</div>
</section>
<section id="pycharm">
<h3>PyCharm<a class="headerlink" href="#pycharm" title="Permalink to this headline"></a></h3>
<p>The Python IDE <a class="reference external" href="https://www.jetbrains.com/pycharm/">Pycharm</a> can auto-generate empty doc-string stubs. The
default is to use <code class="docutils literal notranslate"><span class="pre">reStructuredText</span></code> form, however. To change to Evennia’s
Google-style docstrings, follow <a class="reference external" href="https://www.jetbrains.com/help/pycharm/2016.3/python-integrated-tools.html">this guide</a>.</p>
</section>
</section>
</section>
</div>
</div>
</div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Coding-FAQ.html" title="Coding FAQ"
>next</a> |</li>
<li class="right" >
<a href="Profiling.html" title="Profiling"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Coding-Overview.html" >Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Evennia Code Style</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2022, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
</div>
</body>
</html>

119
docs/1.0-dev/Coding/Profiling.html
View file

@ -17,7 +17,7 @@
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Quirks" href="Quirks.html" />
<link rel="next" title="Evennia Code Style" href="Evennia-Code-Style.html" />
<link rel="prev" title="Unit Testing" href="Unit-Testing.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
@ -30,7 +30,7 @@
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Quirks.html" title="Quirks"
<a href="Evennia-Code-Style.html" title="Evennia Code Style"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Unit-Testing.html" title="Unit Testing"
@ -63,7 +63,6 @@
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Profiling</a><ul>
<li><a class="reference internal" href="#introduction">Introduction</a></li>
<li><a class="reference internal" href="#simple-timer-tests">Simple timer tests</a></li>
<li><a class="reference internal" href="#using-cprofile">Using cProfile</a><ul>
<li><a class="reference internal" href="#analyzing-the-profile">Analyzing the profile</a></li>
@ -81,8 +80,8 @@
<p class="topless"><a href="Unit-Testing.html"
title="previous chapter">Unit Testing</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Quirks.html"
title="next chapter">Quirks</a></p>
<p class="topless"><a href="Evennia-Code-Style.html"
title="next chapter">Evennia Code Style</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
@ -115,24 +114,16 @@
<section class="tex2jax_ignore mathjax_ignore" id="profiling">
<h1>Profiling<a class="headerlink" href="#profiling" title="Permalink to this headline"></a></h1>
<p><em>This is considered an advanced topic mainly of interest to server developers.</em></p>
<section id="introduction">
<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline"></a></h2>
<p>Sometimes it can be useful to try to determine just how efficient a particular
piece of code is, or to figure out if one could speed up things more than they
are. There are many ways to test the performance of Python and the running
server.</p>
<p>Before digging into this section, remember Donald Knuth’s
<a class="reference external" href="https://en.wikipedia.org/wiki/Program_optimization#When_to_optimize">words of wisdom</a>:</p>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>This is considered an advanced topic. It’s mainly of interest to server developers.</p>
</div>
<p>Sometimes it can be useful to try to determine just how efficient a particular piece of code is, or to figure out if one could speed up things more than they are. There are many ways to test the performance of Python and the running server.</p>
<p>Before digging into this section, remember Donald Knuth’s <a class="reference external" href="https://en.wikipedia.org/wiki/Program_optimization#When_to_optimize">words of wisdom</a>:</p>
<blockquote>
<div><p><em>[…]about 97% of the time: Premature optimization is the root of all evil</em>.</p>
</div></blockquote>
<p>That is, don’t start to try to optimize your code until you have actually
identified a need to do so. This means your code must actually be working before
you start to consider optimization. Optimization will also often make your code
more complex and harder to read. Consider readability and maintainability and
you may find that a small gain in speed is just not worth it.</p>
</section>
<p>That is, don’t start to try to optimize your code until you have actually identified a need to do so. This means your code must actually be working before you start to consider optimization. Optimization will also often make your code more complex and harder to read. Consider readability and maintainability and you may find that a small gain in speed is just not worth it.</p>
<section id="simple-timer-tests">
<h2>Simple timer tests<a class="headerlink" href="#simple-timer-tests" title="Permalink to this headline"></a></h2>
<p>Python’s <code class="docutils literal notranslate"><span class="pre">timeit</span></code> module is very good for testing small things. For example, in
@ -147,46 +138,24 @@ could use the following code:</p>
<span class="o">&lt;&lt;&lt;</span> <span class="mf">5.358283996582031</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">setup</span></code> keyword is used to set up things that should not be included in the
time measurement, like <code class="docutils literal notranslate"><span class="pre">a</span> <span class="pre">=</span> <span class="pre">[]</span></code> in the first call.</p>
<p>By default the <code class="docutils literal notranslate"><span class="pre">timeit</span></code> function will re-run the given test 1000000 times and
returns the <em>total time</em> to do so (so <em>not</em> the average per test). A hint is to
not use this default for testing something that includes database writes - for
that you may want to use a lower number of repeats (say 100 or 1000) using the
<code class="docutils literal notranslate"><span class="pre">number=100</span></code> keyword.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">setup</span></code> keyword is used to set up things that should not be included in the time measurement, like <code class="docutils literal notranslate"><span class="pre">a</span> <span class="pre">=</span> <span class="pre">[]</span></code> in the first call.</p>
<p>By default the <code class="docutils literal notranslate"><span class="pre">timeit</span></code> function will re-run the given test 1000000 times and returns the <em>total time</em> to do so (so <em>not</em> the average per test). A hint is to not use this default for testing something that includes database writes - for that you may want to use a lower number of repeats (say 100 or 1000) using the <code class="docutils literal notranslate"><span class="pre">number=100</span></code> keyword.</p>
<p>In the example above, we see that this number of calls, using a list comprehension is about twice as fast as building a list using <code class="docutils literal notranslate"><span class="pre">.append()</span></code>.</p>
</section>
<section id="using-cprofile">
<h2>Using cProfile<a class="headerlink" href="#using-cprofile" title="Permalink to this headline"></a></h2>
<p>Python comes with its own profiler, named cProfile (this is for cPython, no
tests have been done with <code class="docutils literal notranslate"><span class="pre">pypy</span></code> at this point). Due to the way Evennia’s
processes are handled, there is no point in using the normal way to start the
profiler (<code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-m</span> <span class="pre">cProfile</span> <span class="pre">evennia.py</span></code>). Instead you start the profiler
through the launcher:</p>
<p>Python comes with its own profiler, named cProfile (this is for cPython, no tests have been done with <code class="docutils literal notranslate"><span class="pre">pypy</span></code> at this point). Due to the way Evennia’s processes are handled, there is no point in using the normal way to start the profiler (<code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-m</span> <span class="pre">cProfile</span> <span class="pre">evennia.py</span></code>). Instead you start the profiler through the launcher:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia --profiler start
</pre></div>
</div>
<p>This will start Evennia with the Server component running (in daemon mode) under
cProfile. You could instead try <code class="docutils literal notranslate"><span class="pre">--profile</span></code> with the <code class="docutils literal notranslate"><span class="pre">portal</span></code> argument to
profile the Portal (you would then need to
<a class="reference internal" href="../Setup/Start-Stop-Reload.html"><span class="doc std std-doc">start the Server separately</span></a>).</p>
<p>Please note that while the profiler is running, your process will use a lot more
memory than usual. Memory usage is even likely to climb over time. So don’t
leave it running perpetually but monitor it carefully (for example using the
<code class="docutils literal notranslate"><span class="pre">top</span></code> command on Linux or the Task Manager’s memory display on Windows).</p>
<p>Once you have run the server for a while, you need to stop it so the profiler
can give its report. Do <em>not</em> kill the program from your task manager or by
sending it a kill signal - this will most likely also mess with the profiler.
Instead either use <code class="docutils literal notranslate"><span class="pre">evennia.py</span> <span class="pre">stop</span></code> or (which may be even better), use
<code class="docutils literal notranslate"><span class="pre">&#64;shutdown</span></code> from inside the game.</p>
<p>Once the server has fully shut down (this may be a lot slower than usual) you
will find that profiler has created a new file <code class="docutils literal notranslate"><span class="pre">mygame/server/logs/server.prof</span></code>.</p>
<p>This will start Evennia with the Server component running (in daemon mode) under cProfile. You could instead try <code class="docutils literal notranslate"><span class="pre">--profile</span></code> with the <code class="docutils literal notranslate"><span class="pre">portal</span></code> argument to profile the Portal (you would then need to <a class="reference internal" href="../Setup/Running-Evennia.html"><span class="doc std std-doc">start the Server separately</span></a>).</p>
<p>Please note that while the profiler is running, your process will use a lot more memory than usual. Memory usage is even likely to climb over time. So don’t leave it running perpetually but monitor it carefully (for example using the <code class="docutils literal notranslate"><span class="pre">top</span></code> command on Linux or the Task Manager’s memory display on Windows).</p>
<p>Once you have run the server for a while, you need to stop it so the profiler can give its report. Do <em>not</em> kill the program from your task manager or by sending it a kill signal - this will most likely also mess with the profiler. Instead either use <code class="docutils literal notranslate"><span class="pre">evennia.py</span> <span class="pre">stop</span></code> or (which may be even better), use <code class="docutils literal notranslate"><span class="pre">&#64;shutdown</span></code> from inside the game.</p>
<p>Once the server has fully shut down (this may be a lot slower than usual) you will find that profiler has created a new file <code class="docutils literal notranslate"><span class="pre">mygame/server/logs/server.prof</span></code>.</p>
<section id="analyzing-the-profile">
<h3>Analyzing the profile<a class="headerlink" href="#analyzing-the-profile" title="Permalink to this headline"></a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre">server.prof</span></code> file is a binary file. There are many ways to analyze and
display its contents, all of which has only been tested in Linux (If you are a
Windows/Mac user, let us know what works).</p>
<p>You can look at the contents of the profile file with Python’s in-built <code class="docutils literal notranslate"><span class="pre">pstats</span></code>
module in the evennia shell (it’s recommended you install <code class="docutils literal notranslate"><span class="pre">ipython</span></code> with <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">ipython</span></code> in your virtualenv first, for prettier output):</p>
<p>The <code class="docutils literal notranslate"><span class="pre">server.prof</span></code> file is a binary file. There are many ways to analyze and display its contents, all of which has only been tested in Linux (If you are a Windows/Mac user, let us know what works).</p>
<p>You can look at the contents of the profile file with Python’s in-built <code class="docutils literal notranslate"><span class="pre">pstats</span></code> module in the evennia shell (it’s recommended you install <code class="docutils literal notranslate"><span class="pre">ipython</span></code> with <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">ipython</span></code> in your virtualenv first, for prettier output):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia shell
</pre></div>
</div>
@ -199,9 +168,7 @@ module in the evennia shell (it’s recommended you install <code class="docutil
</pre></div>
</div>
<p>See the
<a class="reference external" href="https://docs.python.org/3/library/profile.html#instant-user-s-manual">Python profiling documentation</a>
for more information.</p>
<p>See the <a class="reference external" href="https://docs.python.org/3/library/profile.html#instant-user-s-manual">Python profiling documentation</a> for more information.</p>
<p>You can also visualize the data in various ways.</p>
<ul class="simple">
<li><p><a class="reference external" href="https://pypi.org/project/RunSnakeRun/">Runsnake</a> visualizes the profile to
@ -214,21 +181,12 @@ KCachegrind work with Python profiles you also need the wrapper script
<code class="docutils literal notranslate"><span class="pre">pyprof2calltree</span></code> via <code class="docutils literal notranslate"><span class="pre">pip</span></code> whereas KCacheGrind is something you need to get
via your package manager or their homepage.</p></li>
</ul>
<p>How to analyze and interpret profiling data is not a trivial issue and depends
on what you are profiling for. Evennia being an asynchronous server can also
confuse profiling. Ask on the mailing list if you need help and be ready to be
able to supply your <code class="docutils literal notranslate"><span class="pre">server.prof</span></code> file for comparison, along with the exact
conditions under which it was obtained.</p>
<p>How to analyze and interpret profiling data is not a trivial issue and depends on what you are profiling for. Evennia being an asynchronous server can also confuse profiling. Ask on the mailing list if you need help and be ready to be able to supply your <code class="docutils literal notranslate"><span class="pre">server.prof</span></code> file for comparison, along with the exact conditions under which it was obtained.</p>
</section>
</section>
<section id="the-dummyrunner">
<h2>The Dummyrunner<a class="headerlink" href="#the-dummyrunner" title="Permalink to this headline"></a></h2>
<p>It is difficult to test “actual” game performance without having players in your
game. For this reason Evennia comes with the <em>Dummyrunner</em> system. The
Dummyrunner is a stress-testing system: a separate program that logs into your
game with simulated players (aka “bots” or “dummies”). Once connected, these
dummies will semi-randomly perform various tasks from a list of possible
actions. Use <code class="docutils literal notranslate"><span class="pre">Ctrl-C</span></code> to stop the Dummyrunner.</p>
<p>It is difficult to test “actual” game performance without having players in your game. For this reason Evennia comes with the <em>Dummyrunner</em> system. The Dummyrunner is a stress-testing system: a separate program that logs into your game with simulated players (aka “bots” or “dummies”). Once connected, these dummies will semi-randomly perform various tasks from a list of possible actions. Use <code class="docutils literal notranslate"><span class="pre">Ctrl-C</span></code> to stop the Dummyrunner.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>You should not run the Dummyrunner on a production database. It
@ -243,9 +201,7 @@ will spawn many objects and also needs to run with general permissions.
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> from evennia.server.profiling.settings_mixin import *
</pre></div>
</div>
<p>This will override your settings and disable Evennia’s rate limiters and
DoS-protections, which would otherwise block mass-connecting clients from
one IP. Notably, it will also change to a different (faster) password hasher.</p>
<p>This will override your settings and disable Evennia’s rate limiters and DoS-protections, which would otherwise block mass-connecting clients from one IP. Notably, it will also change to a different (faster) password hasher.</p>
</li>
<li><p>(recommended): Build a new database. If you use default Sqlite3 and want to
keep your existing database, just rename <code class="docutils literal notranslate"><span class="pre">mygame/server/evennia.db3</span></code> to
@ -260,28 +216,16 @@ be able to connect with an <em>existing</em> user since the password hasher chan
<p>Use <code class="docutils literal notranslate"><span class="pre">Ctrl-C</span></code> (or <code class="docutils literal notranslate"><span class="pre">Cmd-C</span></code>) to stop it.</p>
</li>
</ol>
<p>If you want to see what the dummies are actually doing you can run with a single
dummy:</p>
<p>If you want to see what the dummies are actually doing you can run with a single dummy:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia --dummyrunner 1
</pre></div>
</div>
<p>The inputs/outputs from the dummy will then be printed. By default the runner
uses the ‘looker’ profile, which just logs in and sends the ‘look’ command
over and over. To change the settings, copy the file
<code class="docutils literal notranslate"><span class="pre">evennia/server/profiling/dummyrunner_settings.py</span></code> to your <code class="docutils literal notranslate"><span class="pre">mygame/server/conf/</span></code>
directory, then add this line to your settings file to use it in the new
location:</p>
<p>The inputs/outputs from the dummy will then be printed. By default the runner uses the ‘looker’ profile, which just logs in and sends the ‘look’ command over and over. To change the settings, copy the file <code class="docutils literal notranslate"><span class="pre">evennia/server/profiling/dummyrunner_settings.py</span></code> to your <code class="docutils literal notranslate"><span class="pre">mygame/server/conf/</span></code> directory, then add this line to your settings file to use it in the new location:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>DUMMYRUNNER_SETTINGS_MODULE = &quot;server/conf/dummyrunner_settings.py&quot;
</pre></div>
</div>
<p>The dummyrunner settings file is a python code module in its own right - it
defines the actions available to the dummies. These are just tuples of command
strings (like “look here”) for the dummy to send to the server along with a
probability of them happening. The dummyrunner looks for a global variable
<code class="docutils literal notranslate"><span class="pre">ACTIONS</span></code>, a list of tuples, where the first two elements define the
commands for logging in/out of the server.</p>
<p>Below is a simplified minimal setup (the default settings file adds a lot more
functionality and info):</p>
<p>The dummyrunner settings file is a python code module in its own right - it defines the actions available to the dummies. These are just tuples of command strings (like “look here”) for the dummy to send to the server along with a probability of them happening. The dummyrunner looks for a global variable <code class="docutils literal notranslate"><span class="pre">ACTIONS</span></code>, a list of tuples, where the first two elements define the commands for logging in/out of the server.</p>
<p>Below is a simplified minimal setup (the default settings file adds a lot more functionality and info):</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># minimal dummyrunner setup file</span>
<span class="c1"># Time between each dummyrunner &quot;tick&quot;, in seconds. Each dummy will be called</span>
@ -325,8 +269,7 @@ functionality and info):</p>
</pre></div>
</div>
<p>At the bottom of the default file are a few default profiles you can test out
by just setting the <code class="docutils literal notranslate"><span class="pre">PROFILE</span></code> variable to one of the options.</p>
<p>At the bottom of the default file are a few default profiles you can test out by just setting the <code class="docutils literal notranslate"><span class="pre">PROFILE</span></code> variable to one of the options.</p>
<section id="dummyrunner-hints">
<h3>Dummyrunner hints<a class="headerlink" href="#dummyrunner-hints" title="Permalink to this headline"></a></h3>
<ul class="simple">
@ -372,7 +315,7 @@ For this, actual real-game testing is required.</p></li>
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Quirks.html" title="Quirks"
<a href="Evennia-Code-Style.html" title="Evennia Code Style"
>next</a> |</li>
<li class="right" >
<a href="Unit-Testing.html" title="Unit Testing"

10
docs/1.0-dev/Coding/Quirks.html
View file

@ -18,7 +18,7 @@
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Changelog" href="Changelog.html" />
<link rel="prev" title="Profiling" href="Profiling.html" />
<link rel="prev" title="Coding FAQ" href="Coding-FAQ.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
@ -33,7 +33,7 @@
<a href="Changelog.html" title="Changelog"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Profiling.html" title="Profiling"
<a href="Coding-FAQ.html" title="Coding FAQ"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Coding-Overview.html" accesskey="U">Coding and development help</a> &#187;</li>
@ -78,8 +78,8 @@
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="Profiling.html"
title="previous chapter">Profiling</a></p>
<p class="topless"><a href="Coding-FAQ.html"
title="previous chapter">Coding FAQ</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Changelog.html"
title="next chapter">Changelog</a></p>
@ -258,7 +258,7 @@ package imports from.</p>
<a href="Changelog.html" title="Changelog"
>next</a> |</li>
<li class="right" >
<a href="Profiling.html" title="Profiling"
<a href="Coding-FAQ.html" title="Coding FAQ"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Coding-Overview.html" >Coding and development help</a> &#187;</li>

62
docs/1.0-dev/Coding/Setting-up-PyCharm.html
View file

@ -66,7 +66,7 @@
<li><a class="reference internal" href="#setting-up-the-project-interpreter">Setting up the project interpreter</a></li>
<li><a class="reference internal" href="#attaching-pycharm-debugger-to-evennia">Attaching PyCharm debugger to Evennia</a></li>
<li><a class="reference internal" href="#setting-up-an-evennia-run-configuration">Setting up an Evennia run configuration</a></li>
<li><a class="reference internal" href="#alternative-run-configuration-utilizing-logfiles-as-source-of-data">Alternative run configuration - utilizing logfiles as source of data</a></li>
<li><a class="reference internal" href="#alternative-config-utilizing-logfiles-as-source-of-data">Alternative config - utilizing logfiles as source of data</a></li>
</ul>
</li>
</ul>
@ -109,16 +109,11 @@
<section class="tex2jax_ignore mathjax_ignore" id="setting-up-pycharm-with-evennia">
<h1>Setting up PyCharm with Evennia<a class="headerlink" href="#setting-up-pycharm-with-evennia" title="Permalink to this headline"></a></h1>
<p><a class="reference external" href="https://www.jetbrains.com/pycharm/">PyCharm</a> is a Python developer’s IDE from Jetbrains available
for Windows, Mac and Linux. It is a commercial product but offer free trials, a scaled-down
community edition and also generous licenses for OSS projects like Evennia.</p>
<p><a class="reference external" href="https://www.jetbrains.com/pycharm/">PyCharm</a> is a Python developer’s IDE from Jetbrains available for Windows, Mac and Linux. It is a commercial product but offer free trials, a scaled-down community edition and also generous licenses for OSS projects like Evennia.</p>
<blockquote>
<div><p>This page was originally tested on Windows (so use Windows-style path examples), but should work
the same for all platforms.</p>
<div><p>This page was originally tested on Windows (so use Windows-style path examples), but should work the same for all platforms.</p>
</div></blockquote>
<p>First, install Evennia on your local machine with [[Getting Started]]. If you’re new to PyCharm,
loading your project is as easy as selecting the <code class="docutils literal notranslate"><span class="pre">Open</span></code> option when PyCharm starts, and browsing to
your game folder (the one created with <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">--init</span></code>). We refer to it as <code class="docutils literal notranslate"><span class="pre">mygame</span></code> here.</p>
<p>First, install Evennia on your local machine with [[Getting Started]]. If you’re new to PyCharm, loading your project is as easy as selecting the <code class="docutils literal notranslate"><span class="pre">Open</span></code> option when PyCharm starts, and browsing to your game folder (the one created with <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">--init</span></code>). We refer to it as <code class="docutils literal notranslate"><span class="pre">mygame</span></code> here.</p>
<p>If you want to be able to examine evennia’s core code or the scripts inside your virtualenv, you’ll
need to add them to your project too:</p>
<ol class="simple">
@ -148,63 +143,42 @@ project is already configured in PyCharm.</p>
<p>Of course you can attach to the <code class="docutils literal notranslate"><span class="pre">portal</span></code> process as well. If you want to debug the Evennia launcher
or runner for some reason (or just learn how they work!), see Run Configuration below.</p>
<blockquote>
<div><p>NOTE: Whenever you reload Evennia, the old Server process will die and a new one start. So when
you restart you have to detach from the old and then reattach to the new process that was created.</p>
<div><p>NOTE: Whenever you reload Evennia, the old Server process will die and a new one start. So when you restart you have to detach from the old and then reattach to the new process that was created.</p>
</div></blockquote>
<blockquote>
<div><p>To make the process less tedious you can apply a filter in settings to show only the <a class="reference external" href="http://server.py">server.py</a>
process in the list. To do that navigate to: <code class="docutils literal notranslate"><span class="pre">Settings/Preferences</span> <span class="pre">|</span> <span class="pre">Build,</span> <span class="pre">Execution,</span> <span class="pre">Deployment</span> <span class="pre">|</span> <span class="pre">Python</span> <span class="pre">Debugger</span></code> and then in <code class="docutils literal notranslate"><span class="pre">Attach</span> <span class="pre">to</span> <span class="pre">process</span></code> field put in: <code class="docutils literal notranslate"><span class="pre">twistd.exe&quot;</span> <span class="pre">--nodaemon</span></code>. This is an
example for windows, I don’t have a working mac/linux box.
<img alt="Example process filter configuration" src="https://i.imgur.com/vkSheR8.png" /></p>
<div><p>To make the process less tedious you can apply a filter in settings to show only the <a class="reference external" href="http://server.py">server.py</a> process in the list. To do that navigate to: <code class="docutils literal notranslate"><span class="pre">Settings/Preferences</span> <span class="pre">|</span> <span class="pre">Build,</span> <span class="pre">Execution,</span> <span class="pre">Deployment</span> <span class="pre">|</span> <span class="pre">Python</span> <span class="pre">Debugger</span></code> and then in <code class="docutils literal notranslate"><span class="pre">Attach</span> <span class="pre">to</span> <span class="pre">process</span></code> field put in: <code class="docutils literal notranslate"><span class="pre">twistd.exe&quot;</span> <span class="pre">--nodaemon</span></code>. This is an example for windows, I don’t have a working mac/linux box.</p>
</div></blockquote>
<p><img alt="Example process filter configuration" src="https://i.imgur.com/vkSheR8.png" /></p>
</section>
<section id="setting-up-an-evennia-run-configuration">
<h2>Setting up an Evennia run configuration<a class="headerlink" href="#setting-up-an-evennia-run-configuration" title="Permalink to this headline"></a></h2>
<p>This configuration allows you to launch Evennia from inside PyCharm. Besides convenience, it also
allows suspending and debugging the evennia_launcher or evennia_runner at points earlier than you
could by running them externally and attaching. In fact by the time the server and/or portal are
running the launcher will have exited already.</p>
<p>This configuration allows you to launch Evennia from inside PyCharm. Besides convenience, it also allows suspending and debugging the evennia_launcher or evennia_runner at points earlier than you could by running them externally and attaching. In fact by the time the server and/or portal are running the launcher will have exited already.</p>
<ol class="simple">
<li><p>Go to <code class="docutils literal notranslate"><span class="pre">Run</span> <span class="pre">&gt;</span> <span class="pre">Edit</span> <span class="pre">Configutations...</span></code></p></li>
<li><p>Click the plus-symbol to add a new configuration and choose Python</p></li>
<li><p>Add the script: <code class="docutils literal notranslate"><span class="pre">\&lt;yourrepo\&gt;\evenv\Scripts\evennia_launcher.py</span></code> (substitute your virtualenv if
it’s not named <code class="docutils literal notranslate"><span class="pre">evenv</span></code>)</p></li>
<li><p>Add the script: <code class="docutils literal notranslate"><span class="pre">\&lt;yourrepo\&gt;\evenv\Scripts\evennia_launcher.py</span></code> (substitute your virtualenv if it’s not named <code class="docutils literal notranslate"><span class="pre">evenv</span></code>)</p></li>
<li><p>Set script parameters to: <code class="docutils literal notranslate"><span class="pre">start</span> <span class="pre">-l</span></code> (-l enables console logging)</p></li>
<li><p>Ensure the chosen interpreter is from your virtualenv</p></li>
<li><p>Set Working directory to your <code class="docutils literal notranslate"><span class="pre">mygame</span></code> folder (not evenv nor evennia)</p></li>
<li><p>You can refer to the PyCharm documentation for general info, but you’ll want to set at least a
config name (like “MyMUD start” or similar).</p></li>
<li><p>You can refer to the PyCharm documentation for general info, but you’ll want to set at least a config name (like “MyMUD start” or similar).</p></li>
</ol>
<p>Now set up a “stop” configuration by following the same steps as above, but set your Script
parameters to: stop (and name the configuration appropriately).</p>
<p>A dropdown box holding your new configurations should appear next to your PyCharm run button.
Select MyMUD start and press the debug icon to begin debugging. Depending on how far you let the
program run, you may need to run your “MyMUD stop” config to actually stop the server, before you’ll
be able start it again.</p>
<p>Now set up a “stop” configuration by following the same steps as above, but set your Script parameters to: stop (and name the configuration appropriately).</p>
<p>A dropdown box holding your new configurations should appear next to your PyCharm run button. Select MyMUD start and press the debug icon to begin debugging. Depending on how far you let the program run, you may need to run your “MyMUD stop” config to actually stop the server, before you’ll be able start it again.</p>
</section>
<section id="alternative-run-configuration-utilizing-logfiles-as-source-of-data">
<h2>Alternative run configuration - utilizing logfiles as source of data<a class="headerlink" href="#alternative-run-configuration-utilizing-logfiles-as-source-of-data" title="Permalink to this headline"></a></h2>
<p>This configuration takes a bit different approach as instead of focusing on getting the data back
through logfiles. Reason for that is this way you can easily separate data streams, for example you
rarely want to follow both server and portal at the same time, and this will allow it. This will
also make sure to stop the evennia before starting it, essentially working as reload command (it
will also include instructions how to disable that part of functionality). We will start by defining
a configuration that will stop evennia. This assumes that <code class="docutils literal notranslate"><span class="pre">upfire</span></code> is your pycharm project name, and
also the game name, hence the <code class="docutils literal notranslate"><span class="pre">upfire/upfire</span></code> path.</p>
<section id="alternative-config-utilizing-logfiles-as-source-of-data">
<h2>Alternative config - utilizing logfiles as source of data<a class="headerlink" href="#alternative-config-utilizing-logfiles-as-source-of-data" title="Permalink to this headline"></a></h2>
<p>This configuration takes a bit different approach as instead of focusing on getting the data back through logfiles. Reason for that is this way you can easily separate data streams, for example you rarely want to follow both server and portal at the same time, and this will allow it. This will also make sure to stop the evennia before starting it, essentially working as reload command (it will also include instructions how to disable that part of functionality). We will start by defining a configuration that will stop evennia. This assumes that <code class="docutils literal notranslate"><span class="pre">upfire</span></code> is your pycharm project name, and also the game name, hence the <code class="docutils literal notranslate"><span class="pre">upfire/upfire</span></code> path.</p>
<ol class="simple">
<li><p>Go to <code class="docutils literal notranslate"><span class="pre">Run</span> <span class="pre">&gt;</span> <span class="pre">Edit</span> <span class="pre">Configutations...</span></code>\</p></li>
<li><p>Click the plus-symbol to add a new configuration and choose the python interpreter to use (should
be project default)</p></li>
<li><p>Click the plus-symbol to add a new configuration and choose the python interpreter to use (should be project default)</p></li>
<li><p>Name the configuration as “stop evennia” and fill rest of the fields accordingly to the image:
<img alt="Stop run configuration" src="https://i.imgur.com/gbkXhlG.png" /></p></li>
<li><p>Press <code class="docutils literal notranslate"><span class="pre">Apply</span></code></p></li>
</ol>
<p>Now we will define the start/reload command that will make sure that evennia is not running already,
and then start the server in one go.</p>
<p>Now we will define the start/reload command that will make sure that evennia is not running already, and then start the server in one go.</p>
<ol class="simple">
<li><p>Go to <code class="docutils literal notranslate"><span class="pre">Run</span> <span class="pre">&gt;</span> <span class="pre">Edit</span> <span class="pre">Configutations...</span></code>\</p></li>
<li><p>Click the plus-symbol to add a new configuration and choose the python interpreter to use (should
be project default)</p></li>
<li><p>Click the plus-symbol to add a new configuration and choose the python interpreter to use (should be project default)</p></li>
<li><p>Name the configuration as “start evennia” and fill rest of the fields accordingly to the image:
<img alt="Start run configuration" src="https://i.imgur.com/5YEjeHq.png" /></p></li>
<li><p>Navigate to the <code class="docutils literal notranslate"><span class="pre">Logs</span></code> tab and add the log files you would like to follow. The picture shows

14
docs/1.0-dev/Coding/Unit-Testing.html
View file

@ -115,17 +115,9 @@
<section class="tex2jax_ignore mathjax_ignore" id="unit-testing">
<h1>Unit Testing<a class="headerlink" href="#unit-testing" title="Permalink to this headline"></a></h1>
<p><em>Unit testing</em> means testing components of a program in isolation from each other to make sure every
part works on its own before using it with others. Extensive testing helps avoid new updates causing
unexpected side effects as well as alleviates general code rot (a more comprehensive wikipedia
article on unit testing can be found <a class="reference external" href="https://en.wikipedia.org/wiki/Unit_test">here</a>).</p>
<p>A typical unit test set calls some function or method with a given input, looks at the result and
makes sure that this result looks as expected. Rather than having lots of stand-alone test programs,
Evennia makes use of a central <em>test runner</em>. This is a program that gathers all available tests all
over the Evennia source code (called <em>test suites</em>) and runs them all in one go. Errors and
tracebacks are reported.</p>
<p>By default Evennia only tests itself. But you can also add your own tests to your game code and have
Evennia run those for you.</p>
<p><em>Unit testing</em> means testing components of a program in isolation from each other to make sure every part works on its own before using it with others. Extensive testing helps avoid new updates causing unexpected side effects as well as alleviates general code rot (a more comprehensive wikipedia article on unit testing can be found <a class="reference external" href="https://en.wikipedia.org/wiki/Unit_test">here</a>).</p>
<p>A typical unit test set calls some function or method with a given input, looks at the result and makes sure that this result looks as expected. Rather than having lots of stand-alone test programs, Evennia makes use of a central <em>test runner</em>. This is a program that gathers all available tests all over the Evennia source code (called <em>test suites</em>) and runs them all in one go. Errors and tracebacks are reported.</p>
<p>By default Evennia only tests itself. But you can also add your own tests to your game code and have Evennia run those for you.</p>
<section id="running-the-evennia-test-suite">
<h2>Running the Evennia test suite<a class="headerlink" href="#running-the-evennia-test-suite" title="Permalink to this headline"></a></h2>
<p>To run the full Evennia test suite, go to your game folder and issue the command</p>

273
docs/1.0-dev/Coding/Updating-Your-Game.html
View file

@ -1,273 +0,0 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Updating Your Game &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Coding Introduction" href="Coding-Introduction.html" />
<link rel="prev" title="Version Control" href="Version-Control.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Coding-Introduction.html" title="Coding Introduction"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Version-Control.html" title="Version Control"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Coding-Overview.html" accesskey="U">Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Updating Your Game</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Updating Your Game</a><ul>
<li><a class="reference internal" href="#updating-with-the-latest-evennia-code-changes">Updating with the latest Evennia code changes</a></li>
<li><a class="reference internal" href="#upgrading-evennia-dependencies">Upgrading Evennia dependencies</a></li>
<li><a class="reference internal" href="#migrating-the-database-schema">Migrating the Database Schema</a></li>
<li><a class="reference internal" href="#resetting-your-database">Resetting your database</a></li>
<li><a class="reference internal" href="#more-about-schema-migrations">More about schema migrations</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="Version-Control.html"
title="previous chapter">Version Control</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Coding-Introduction.html"
title="next chapter">Coding Introduction</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Coding/Updating-Your-Game.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div><h3>Links</h3>
<ul>
<li><a href="https://www.evennia.com">Home page</a> </li>
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
<h3>Versions</h3>
<ul>
<li><a href="Updating-Your-Game.html">1.0-dev (develop branch)</a></li>
<ul>
<li><a href="../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="updating-your-game">
<h1>Updating Your Game<a class="headerlink" href="#updating-your-game" title="Permalink to this headline"></a></h1>
<p>Fortunately, it’s extremely easy to keep your Evennia server up-to-date. If you haven’t already, see
the <a class="reference internal" href="../Setup/Installation.html"><span class="doc std std-doc">Getting Started guide</span></a> and get everything running.</p>
<section id="updating-with-the-latest-evennia-code-changes">
<h2>Updating with the latest Evennia code changes<a class="headerlink" href="#updating-with-the-latest-evennia-code-changes" title="Permalink to this headline"></a></h2>
<p>Very commonly we make changes to the Evennia code to improve things. There are many ways to get told
when to update: You can subscribe to the RSS feed or manually check up on the feeds from
<a class="reference external" href="https://www.evennia.com">https://www.evennia.com</a>. You can also simply fetch the latest regularly.</p>
<p>When you’re wanting to apply updates, simply <code class="docutils literal notranslate"><span class="pre">cd</span></code> to your cloned <code class="docutils literal notranslate"><span class="pre">evennia</span></code> root directory and type:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> git pull
</pre></div>
</div>
<p>assuming you’ve got the command line client. If you’re using a graphical client, you will probably
want to navigate to the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> directory and either right click and find your client’s pull
function, or use one of the menus (if applicable).</p>
<p>You can review the latest changes with</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> git log
</pre></div>
</div>
<p>or the equivalent in the graphical client. You can also see the latest changes online
<a class="reference external" href="https://github.com/evennia/evennia/blob/master/CHANGELOG.md">here</a>.</p>
<p>You will always need to do <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">reload</span></code> (or <code class="docutils literal notranslate"><span class="pre">reload</span></code> from -in-game) from your game-dir to have
the new code affect your game. If you want to be really sure you should run a full <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">reboot</span></code>
so that both Server and Portal can restart (this will disconnect everyone though, so if you know the
Portal has had no updates you don’t have to do that).</p>
</section>
<section id="upgrading-evennia-dependencies">
<h2>Upgrading Evennia dependencies<a class="headerlink" href="#upgrading-evennia-dependencies" title="Permalink to this headline"></a></h2>
<p>On occasion we update the versions of third-party libraries Evennia depend on (or we may add a new
dependency). This will be announced on the mailing list/forum. If you run into errors when starting
Evennia, always make sure you have the latest versions of everything. In some cases, like for
Django, starting the server may also give warning saying that you are using a working, but too-old
version that should not be used in production.</p>
<p>Upgrading <code class="docutils literal notranslate"><span class="pre">evennia</span></code> will automatically fetch all the latest packages that it now need. First <code class="docutils literal notranslate"><span class="pre">cd</span></code> to
your cloned <code class="docutils literal notranslate"><span class="pre">evennia</span></code> folder. Make sure your <code class="docutils literal notranslate"><span class="pre">virtualenv</span></code> is active and use</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>pip install --upgrade -e .
</pre></div>
</div>
<p>Remember the period (<code class="docutils literal notranslate"><span class="pre">.</span></code>) at the end - that applies the upgrade to the current location (your
<code class="docutils literal notranslate"><span class="pre">evennia</span></code> dir).</p>
<blockquote>
<div><p>The <code class="docutils literal notranslate"><span class="pre">-e</span></code> means that we are <em>linking</em> the evennia sources rather than copying them into the
environment. This means we can most of the time just update the sources (with <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">pull</span></code>) and see
those changes directly applied to our installed <code class="docutils literal notranslate"><span class="pre">evennia</span></code> package. Without installing/upgrading the
package with <code class="docutils literal notranslate"><span class="pre">-e</span></code>, we would have to remember to upgrade the package every time we downloaded any new
source-code changes.</p>
</div></blockquote>
<p>Follow the upgrade output to make sure it finishes without errors. To check what packages are
currently available in your python environment after the upgrade, use</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>pip list
</pre></div>
</div>
<p>This will show you the version of all installed packages. The <code class="docutils literal notranslate"><span class="pre">evennia</span></code> package will also show the
location of its source code.</p>
</section>
<section id="migrating-the-database-schema">
<h2>Migrating the Database Schema<a class="headerlink" href="#migrating-the-database-schema" title="Permalink to this headline"></a></h2>
<p>Whenever we change the database layout of Evennia upstream (such as when we add new features) you
will need to <em>migrate</em> your existing database. When this happens it will be clearly noted in the
<code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">log</span></code> (it will say something to the effect of “Run migrations”). Database changes will also be
announced on the Evennia <a class="reference external" href="https://groups.google.com/forum/#%21forum/evennia">mailing list</a>.</p>
<p>When the database schema changes, you just go to your game folder and run</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> evennia migrate
</pre></div>
</div>
<blockquote>
<div><p>Hint: If the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> command is not found, you most likely need to activate your
<a class="reference internal" href="../Glossary.html#virtualenv"><span class="std std-doc">virtualenv</span></a>.</p>
</div></blockquote>
</section>
<section id="resetting-your-database">
<h2>Resetting your database<a class="headerlink" href="#resetting-your-database" title="Permalink to this headline"></a></h2>
<p>Should you ever want to start over completely from scratch, there is no need to re-download Evennia
or anything like that. You just need to clear your database. Once you are done, you just rebuild it
from scratch by running</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia migrate
</pre></div>
</div>
<p>The first step in wiping your database is to stop Evennia completely with</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia stop
</pre></div>
</div>
<p>If you run the default <code class="docutils literal notranslate"><span class="pre">SQlite3</span></code> database (to change this you need to edit your <code class="docutils literal notranslate"><span class="pre">settings.py</span></code> file),
the database is actually just a normal file in <code class="docutils literal notranslate"><span class="pre">mygame/server/</span></code> called <code class="docutils literal notranslate"><span class="pre">evennia.db3</span></code>. <em>Simply delete
that file</em> - that’s it. Now run <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">migrate</span></code> to recreate a new, fresh one.</p>
<p>If you run some other database system you can instead flush the database:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia flush
</pre></div>
</div>
<p>This will empty the database. However, it will not reset the internal counters of the database, so
you will start with higher dbref values. If this is okay, this is all you need.</p>
<p>Django also offers an easy way to start the database’s own management should we want more direct
control:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> evennia dbshell
</pre></div>
</div>
<p>In e.g. MySQL you can then do something like this (assuming your MySQL database is named “Evennia”:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>mysql&gt; DROP DATABASE Evennia;
mysql&gt; exit
</pre></div>
</div>
<blockquote>
<div><p>NOTE: Under Windows OS, in order to access SQLite dbshell you need to <a class="reference external" href="https://www.sqlite.org/download.html">download the SQLite
command-line shell program</a>. It’s a single executable file
(sqlite3.exe) that you should place in the root of either your MUD folder or Evennia’s (it’s the
same, in both cases Django will find it).</p>
</div></blockquote>
</section>
<section id="more-about-schema-migrations">
<h2>More about schema migrations<a class="headerlink" href="#more-about-schema-migrations" title="Permalink to this headline"></a></h2>
<p>If and when an Evennia update modifies the database <em>schema</em> (that is, the under-the-hood details as
to how data is stored in the database), you must update your existing database correspondingly to
match the change. If you don’t, the updated Evennia will complain that it cannot read the database
properly. Whereas schema changes should become more and more rare as Evennia matures, it may still
happen from time to time.</p>
<p>One way one could handle this is to apply the changes manually to your database using the database’s
command line. This often means adding/removing new tables or fields as well as possibly convert
existing data to match what the new Evennia version expects. It should be quite obvious that this
quickly becomes cumbersome and error-prone. If your database doesn’t contain anything critical yet
it’s probably easiest to simply reset it and start over rather than to bother converting.</p>
<p>Enter <em>migrations</em>. Migrations keeps track of changes in the database schema and applies them
automatically for you. Basically, whenever the schema changes we distribute small files called
“migrations” with the source. Those tell the system exactly how to implement the change so you don’t
have to do so manually. When a migration has been added we will tell you so on Evennia’s mailing
lists and in commit messages -
you then just run <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">migrate</span></code> to be up-to-date again.</p>
</section>
</section>
</div>
</div>
</div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Coding-Introduction.html" title="Coding Introduction"
>next</a> |</li>
<li class="right" >
<a href="Version-Control.html" title="Version Control"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Coding-Overview.html" >Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Updating Your Game</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2022, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
</div>
</body>
</html>

680
docs/1.0-dev/Coding/Version-Control.html
View file

@ -6,7 +6,7 @@
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Version Control &#8212; Evennia 1.0-dev documentation</title>
<title>Coding using Version Control &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
@ -17,7 +17,7 @@
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Updating Your Game" href="Updating-Your-Game.html" />
<link rel="next" title="Debugging" href="Debugging.html" />
<link rel="prev" title="Coding and development help" href="Coding-Overview.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
@ -30,14 +30,14 @@
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Updating-Your-Game.html" title="Updating Your Game"
<a href="Debugging.html" title="Debugging"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Coding-Overview.html" title="Coding and development help"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Coding-Overview.html" accesskey="U">Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Version Control</a></li>
<li class="nav-item nav-item-this"><a href="">Coding using Version Control</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
@ -62,36 +62,30 @@
<script>$('#searchbox').show(0);</script>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Version Control</a><ul>
<li><a class="reference internal" href="#setting-up-git">Setting up Git</a><ul>
<li><a class="reference internal" href="#step-1-install-git">Step 1: Install Git</a></li>
<li><a class="reference internal" href="#step-2-define-user-e-mail-settings-for-git">Step 2: Define user/e-mail Settings for Git</a></li>
<li><a class="reference internal" href="#">Coding using Version Control</a><ul>
<li><a class="reference internal" href="#setting-up-git">Setting up Git</a></li>
<li><a class="reference internal" href="#common-git-commands">Common Git commands</a><ul>
<li><a class="reference internal" href="#git-init"><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">init</span></code></a></li>
<li><a class="reference internal" href="#git-add"><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">add</span></code></a></li>
<li><a class="reference internal" href="#git-commit"><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span></code></a></li>
<li><a class="reference internal" href="#git-status-git-diff-and-git-log"><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">status</span></code>, <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">diff</span></code> and <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">log</span></code></a></li>
<li><a class="reference internal" href="#git-branch-checkout-and-merge"><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">branch</span></code>, <code class="docutils literal notranslate"><span class="pre">checkout</span></code> and <code class="docutils literal notranslate"><span class="pre">merge</span></code></a></li>
<li><a class="reference internal" href="#git-glone-git-push-and-git-pull"><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">glone</span></code>, <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span></code> and <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">pull</span></code></a></li>
<li><a class="reference internal" href="#other-git-commands">Other git commands</a></li>
</ul>
</li>
<li><a class="reference internal" href="#putting-your-game-folder-under-version-control">Putting your game folder under version control</a><ul>
<li><a class="reference internal" href="#tracking-files">Tracking files</a></li>
<li><a class="reference internal" href="#committing-your-code">Committing your Code</a></li>
<li><a class="reference internal" href="#changing-your-mind">Changing your mind</a></li>
<li><a class="reference internal" href="#putting-your-game-dir-under-version-control">Putting your game dir under version control</a><ul>
<li><a class="reference internal" href="#pushing-your-code-online">Pushing your code online</a></li>
</ul>
</li>
<li><a class="reference internal" href="#forking-evennia">Forking Evennia</a><ul>
<li><a class="reference internal" href="#step-1-fork-the-evennia-master-repository">Step 1: Fork the evennia/master repository</a></li>
<li><a class="reference internal" href="#step-2-clone-your-online-fork-of-evennia">Step 2: Clone your online fork of Evennia</a></li>
<li><a class="reference internal" href="#step-3-configure-remotes">Step 3: Configure remotes</a></li>
<li><a class="reference internal" href="#contributing-to-evennia">Contributing to Evennia</a><ul>
<li><a class="reference internal" href="#fixing-an-evennia-bug-or-feature">Fixing an Evennia bug or feature</a></li>
</ul>
</li>
<li><a class="reference internal" href="#working-with-your-evennia-fork">Working with your Evennia fork</a><ul>
<li><a class="reference internal" href="#updating-to-latest-evennia">Updating to latest Evennia</a></li>
<li><a class="reference internal" href="#making-changes">Making changes</a></li>
<li><a class="reference internal" href="#troubleshooting">Troubleshooting</a><ul>
<li><a class="reference internal" href="#getting-403-forbidden-access">Getting 403: Forbidden access</a></li>
</ul>
</li>
<li><a class="reference internal" href="#sharing-your-evennia-fixes-on-github">Sharing your Evennia fixes on Github</a><ul>
<li><a class="reference internal" href="#troubleshooting">Troubleshooting</a></li>
</ul>
</li>
<li><a class="reference internal" href="#making-an-evennia-pull-request">Making an Evennia Pull Request</a></li>
<li><a class="reference internal" href="#git-tips-and-tricks">GIT tips and tricks</a></li>
</ul>
</li>
</ul>
@ -100,8 +94,8 @@
<p class="topless"><a href="Coding-Overview.html"
title="previous chapter">Coding and development help</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Updating-Your-Game.html"
title="next chapter">Updating Your Game</a></p>
<p class="topless"><a href="Debugging.html"
title="next chapter">Debugging</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
@ -132,25 +126,16 @@
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="version-control">
<h1>Version Control<a class="headerlink" href="#version-control" title="Permalink to this headline"></a></h1>
<p>Version control software allows you to track the changes you make to your code, as well as being
able to easily backtrack these changes, share your development efforts and more.</p>
<p>It’s strongly recommended that you put your game code under version control. Version
control is also the way to contribue to Evennia itself.</p>
<p>For an introduction to the concept, start with the Wikipedia article
<a class="reference external" href="https://en.wikipedia.org/wiki/Version_control">here</a>. Evennia uses the version
control system <a class="reference external" href="https://git-scm.com/">Git</a> and this is what will be covered
henceforth. Note that this page primarily shows commands for Linux, but the
syntax should be the same for Windows and Mac.</p>
<p>For more help on using Git, please refer to the <a class="reference external" href="https://help.github.com/articles/set-up-git#platform-all">Official GitHub
documentation</a>.</p>
<section class="tex2jax_ignore mathjax_ignore" id="coding-using-version-control">
<h1>Coding using Version Control<a class="headerlink" href="#coding-using-version-control" title="Permalink to this headline"></a></h1>
<p><a class="reference external" href="https://en.wikipedia.org/wiki/Version_control">Version control</a> allows you to track changes to your code. You can save ‘snapshots’ of your progress which means you can roll back undo things easily. Version control also allows you to easily back up your code to an online <em>repository</em> such as Github. It also allows you to collaborate with others on the same code without clashing or worry about who changed what.</p>
<aside class="sidebar">
<p class="sidebar-title">Do it!</p>
<p>It’s <em>strongly</em> recommended that you <a class="reference internal" href="#putting-your-game-dir-under-version-control"><span class="std std-doc">put your game folder under version control</span></a>. Using git is is also the way to contribue to Evennia itself.</p>
</aside>
<p>Evennia uses the most commonly used version control system, <a class="reference external" href="https://git-scm.com/">Git</a> . For additional help on using Git, please refer to the <a class="reference external" href="https://help.github.com/articles/set-up-git#platform-all">Official GitHub documentation</a>.</p>
<section id="setting-up-git">
<h2>Setting up Git<a class="headerlink" href="#setting-up-git" title="Permalink to this headline"></a></h2>
<p>You can find expanded instructions for
installation <a class="reference external" href="https://git-scm.com/book/en/Getting-Started-Installing-Git">here</a>.</p>
<section id="step-1-install-git">
<h3>Step 1: Install Git<a class="headerlink" href="#step-1-install-git" title="Permalink to this headline"></a></h3>
<ul>
<li><p><strong>Fedora Linux</strong></p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> yum install git-core
@ -163,21 +148,16 @@ installation <a class="reference external" href="https://git-scm.com/book/en/Get
</div>
</li>
<li><p><strong>Windows</strong>: It is recommended to use <a class="reference external" href="https://gitforwindows.org/">Git for Windows</a>.</p></li>
<li><p><strong>Mac</strong>: Mac platforms offer two methods for installation, one via MacPorts, which you can find
out about <a class="reference external" href="https://git-scm.com/book/en/Getting-Started-Installing-Git#Installing-on-Mac">here</a>, or
you can use the <a class="reference external" href="https://sourceforge.net/projects/git-osx-installer/">Git OSX Installer</a>.</p></li>
<li><p><strong>Mac</strong>: Mac platforms offer two methods for installation, one via MacPorts, which you can find out about <a class="reference external" href="https://git-scm.com/book/en/Getting-Started-Installing-Git#Installing-on-Mac">here</a>, or you can use the <a class="reference external" href="https://sourceforge.net/projects/git-osx-installer/">Git OSX Installer</a>.</p></li>
</ul>
</section>
<section id="step-2-define-user-e-mail-settings-for-git">
<h3>Step 2: Define user/e-mail Settings for Git<a class="headerlink" href="#step-2-define-user-e-mail-settings-for-git" title="Permalink to this headline"></a></h3>
<p>To avoid a common issue later, you will need to set a couple of settings; first you will need to
tell Git your username, followed by your e-mail address, so that when you commit code later you will
be properly credited.</p>
<blockquote>
<div><p>Note that your commit information will be visible to everyone if you ever contribute to Evennia or
use an online service like github to host your code. So if you are not comfortable with using your
real, full name online, put a nickname here.</p>
<div><p>You can find expanded instructions for installation <a class="reference external" href="https://git-scm.com/book/en/Getting-Started-Installing-Git">here</a>.</p>
</div></blockquote>
<aside class="sidebar">
<p class="sidebar-title">Git user nickname</p>
<p>If you ever make your code available online (or contribute to Evennia), your name will be visible to those reading the code-commit history. So if you are not comfortable with using your real, full name online, put a nickname (or your github handler) here.</p>
</aside>
<p>To avoid a common issue later, you will need to set a couple of settings; first you will need to tell Git your username, followed by your e-mail address, so that when you commit code later you will be properly credited.</p>
<ol>
<li><p>Set the default name for git to use when you commit:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> git config --global user.name &quot;Your Name Here&quot;
@ -190,298 +170,290 @@ real, full name online, put a nickname here.</p>
</div>
</li>
</ol>
</section>
</section>
<section id="putting-your-game-folder-under-version-control">
<h2>Putting your game folder under version control<a class="headerlink" href="#putting-your-game-folder-under-version-control" title="Permalink to this headline"></a></h2>
<blockquote>
<div><p>Note: The game folder’s version control is completely separate from Evennia’s repository.</p>
<div><p>To get a running start with Git, here’s <a class="reference external" href="https://www.youtube.com/watch?v=1ffBJ4sVUb4#t=1m58s">a good YouTube talk about it</a>. It’s a bit long but it will help you understand the underlying ideas behind GIT (which in turn makes it a lot more intuitive to use).</p>
</div></blockquote>
<p>After you have set up your game you will have created a new folder to host your particular game
(let’s call this folder <code class="docutils literal notranslate"><span class="pre">mygame</span></code> for now).</p>
<p>This folder is <em>not</em> under version control at this point.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git init mygame
</section>
<section id="common-git-commands">
<h2>Common Git commands<a class="headerlink" href="#common-git-commands" title="Permalink to this headline"></a></h2>
<aside class="sidebar">
<p class="sidebar-title">Git repository</p>
<p>This is just a fancy name for the folder you have designated to be under version control. We will make your <code class="docutils literal notranslate"><span class="pre">mygame</span></code> game folder into such a repository. The Evennia code is also in a (separate) git repository.</p>
</aside>
<p>Git can be controlled via a GUI. But it’s often easier to use the base terminal/console commands, since it makes it clear if something goes wrong.</p>
<p>All these actions need to be done from inside the <em>git repository</em> .</p>
<p>Git may seem daunting at first. But when working with git, you’ll be using the same 2-3 commands 99% of the time. And you can make git <em>aliases</em> to have them be even easier to remember.</p>
<section id="git-init">
<h3><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">init</span></code><a class="headerlink" href="#git-init" title="Permalink to this headline"></a></h3>
<p>This initializes a folder/directory on your drive as a ‘git repository’</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git init .
</pre></div>
</div>
<p>Your mygame folder is now ready for version control! Add all the content and make a first
commit:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>cd mygame
<p>The <code class="docutils literal notranslate"><span class="pre">.</span></code> means to apply to the current directory. If you are inside <code class="docutils literal notranslate"><span class="pre">mygame</span></code>, this makes your game dir into a git repository. That’s all there is to it, really. You only need to do this once.</p>
</section>
<section id="git-add">
<h3><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">add</span></code><a class="headerlink" href="#git-add" title="Permalink to this headline"></a></h3>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git add &lt;file&gt;
</pre></div>
</div>
<p>This tells Git to start to <em>track</em> the file under version control. You need to do this when you create a new file. You can also add all files in your current directory:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git add .
</pre></div>
</div>
<p>Or</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git add *
</pre></div>
</div>
<p>All files in the current directory are now tracked by Git. You only need to do this once for every file you want to track.</p>
</section>
<section id="git-commit">
<h3><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span></code><a class="headerlink" href="#git-commit" title="Permalink to this headline"></a></h3>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git commit -a -m &quot;This is the initial commit&quot;
</pre></div>
</div>
<p>This <em>commits</em> your changes. It stores a snapshot of all (<code class="docutils literal notranslate"><span class="pre">-a</span></code>) your code at the current time, adding a message <code class="docutils literal notranslate"><span class="pre">-m</span></code> so you know what you did. Later you can <em>check out</em> your code the way it was at a given time. The message is mandatory and you will thank yourself later if write clear and descriptive log messages. If you don’t add <code class="docutils literal notranslate"><span class="pre">-m</span></code>, a text editor opens for you to write the message instead.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span></code> is something you’ll be using all the time, so it can be useful to make a <em>git alias</em> for it:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git config --global alias.cma &#39;commit -a -m&#39;
</pre></div>
</div>
<p>After you’ve run this, you can commit much simpler, like this:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git cma &quot;This is the initial commit&quot;
</pre></div>
</div>
<p>Much easier to remember!</p>
</section>
<section id="git-status-git-diff-and-git-log">
<h3><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">status</span></code>, <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">diff</span></code> and <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">log</span></code><a class="headerlink" href="#git-status-git-diff-and-git-log" title="Permalink to this headline"></a></h3>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git status -s
</pre></div>
</div>
<p>This gives a short (<code class="docutils literal notranslate"><span class="pre">-s</span></code>) of the files that changes since your last <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span></code>.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git diff --word-diff`
</pre></div>
</div>
<p>This shows exactly what changed in each file since you last made a <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span></code>. The <code class="docutils literal notranslate"><span class="pre">--word-diff</span></code> option means it will mark if a single word changed on a line.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git log
</pre></div>
</div>
<p>This shows the log of all <code class="docutils literal notranslate"><span class="pre">commits</span></code> done. Each log will show you who made the change, the commit-message and a unique <em>hash</em> (like <code class="docutils literal notranslate"><span class="pre">ba214f12ab12e123...</span></code>) that uniquely describes that commit.</p>
<p>You can make the <code class="docutils literal notranslate"><span class="pre">log</span></code> command more succinct with some more options:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>ls=log --pretty=format:%C(green)%h\ %C(yellow)[%ad]%Cred%d\ %Creset%s%Cblue\ [%an] --decorate --date=relative
</pre></div>
</div>
<p>This adds coloration and another fancy effects (use <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">help</span> <span class="pre">log</span></code> to see what they mean).</p>
<p>Let’s add aliases:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git config --global alias.st &#39;status -s&#39;
git config --global alias.df &#39;diff --word-diff&#39;
git config --global alias.ls &#39;log --pretty=format:%C(green)%h\ %C(yellow)[%ad]%Cred%d\ %Creset%s%Cblue\ [%an] --decorate --date=relative&#39;
</pre></div>
</div>
<p>You can now use the much shorter</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git st # short status
git dif # diff with word-marking
git ls # log with pretty formatting
</pre></div>
</div>
<p>for these useful functions.</p>
</section>
<section id="git-branch-checkout-and-merge">
<h3><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">branch</span></code>, <code class="docutils literal notranslate"><span class="pre">checkout</span></code> and <code class="docutils literal notranslate"><span class="pre">merge</span></code><a class="headerlink" href="#git-branch-checkout-and-merge" title="Permalink to this headline"></a></h3>
<p>Git allows you to work with <em>branches</em>. These are separate development paths your code may take, completely separate from each other. You can later <em>merge</em> the code from a branch back into another branch. Evennia’s <code class="docutils literal notranslate"><span class="pre">master</span></code> and <code class="docutils literal notranslate"><span class="pre">develop</span></code> branches are examples of this.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git branch -b branchaname
</pre></div>
</div>
<p>This creates a new branch, exactly identical to the branch you were on. It also moves you to that branch.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git branch -D branchname
</pre></div>
</div>
<p>Deletes a branch.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git branch
</pre></div>
</div>
<p>Shows all your branches, marking which one you are currently on.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git checkout branchname
</pre></div>
</div>
<p>This checks out another branch. As long as you are in a branch all <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span></code>s will commit the code to that branch only.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git checkout .
</pre></div>
</div>
<p>This checks out your <em>current branch</em> and has the effect of throwing away all your changes since your last commit. This is like undoing what you did since the last save point.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git checkout b2342bc21c124
</pre></div>
</div>
<p>This checks out a particular <em>commit</em>, identified by the hash you find with <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">log</span></code>. This open a ‘temporary branch’ where the code is as it was when you made this commit. As an example, you can use this to check where a bug was introduced. Check out an existing branch to go back to your normal timeline, or use <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">branch</span> <span class="pre">-b</span> <span class="pre">newbranch</span></code> to break this code off into a new branch you can continue working from.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git merge branchname
</pre></div>
</div>
<p>This <em>merges</em> the code from <code class="docutils literal notranslate"><span class="pre">branchname</span></code> into the branch you are currently in. Doing so may lead to <em>merge conflicts</em> if the same code changed in different ways in the two branches. See <a class="reference external" href="https://phoenixnap.com/kb/how-to-resolve-merge-conflicts-in-git">how to resolve merge conflicts in git</a> for more help.</p>
</section>
<section id="git-glone-git-push-and-git-pull">
<h3><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">glone</span></code>, <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span></code> and <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">pull</span></code><a class="headerlink" href="#git-glone-git-push-and-git-pull" title="Permalink to this headline"></a></h3>
<p>All of these other commands have dealt with code only sitting in your local repository-folder. These commands instead allows you to exchange code with a <em>remote</em> repository - usually one that is online (like on github).</p>
<blockquote>
<div><p>How you actually set up a remote repository is described <a class="reference internal" href="#pushing-your-code-online"><span class="std std-doc">in the next section</span></a>.</p>
</div></blockquote>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git clone repository/path
</pre></div>
</div>
<p>This copies the remote repository to your current location. If you used the <a class="reference internal" href="../Setup/Installation-Git.html"><span class="doc std std-doc">Git installation instructions</span></a> to install Evennia, this is what you used to get your local copy of the Evennia repository.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git pull
</pre></div>
</div>
<p>Once you cloned or otherwise set up a remote repository, using <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">pull</span></code> will re-sync the remote with what you have locally. If what you download clashes with local changes, git will force you to <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span></code> your changes before you can continue with <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">pull</span></code>.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git push
</pre></div>
</div>
<p>This uploads your local changes <em>of your current branch</em> to the same-named branch on the remote repository. To be able to do this you must have write-permissions to the remote repository.</p>
</section>
<section id="other-git-commands">
<h3>Other git commands<a class="headerlink" href="#other-git-commands" title="Permalink to this headline"></a></h3>
<p>There are <em>many</em> other git commands. Read up on them online:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git reflog
</pre></div>
</div>
<p>Shows hashes of individual git actions. This allows you to go back in the git event history itself.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git reset
</pre></div>
</div>
<p>Force reset a branch to an earlier commit. This could throw away some history, so be careful.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git grep -n -I -i &lt;query&gt;
</pre></div>
</div>
<p>Quickly search for a phrase/text in all files tracked by git. Very useful to quickly find where things are. Set up an alias <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">gr</span></code> with</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">gr</span> <span class="s1">&#39;grep -n -I -i&#39;</span>
</pre></div>
</div>
</section>
</section>
<section id="putting-your-game-dir-under-version-control">
<h2>Putting your game dir under version control<a class="headerlink" href="#putting-your-game-dir-under-version-control" title="Permalink to this headline"></a></h2>
<p>This makes use of the git commands listed in the previous section.</p>
<aside class="sidebar">
<p class="sidebar-title">git aliases</p>
<p>If you set up the git aliases for commands suggested in the previous section, you can use them instead!</p>
</aside>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>cd mygame
git init .
git add *
git commit -a -m &quot;Initial commit&quot;
</pre></div>
</div>
<p>In turn these commands:</p>
<ul class="simple">
<li><p>Move us into the <code class="docutils literal notranslate"><span class="pre">mygame</span></code> folder</p></li>
<li><p>Tell <code class="docutils literal notranslate"><span class="pre">git</span></code> that everything <code class="docutils literal notranslate"><span class="pre">*</span></code> means everything) in this folder should be put
under version control.</p></li>
<li><p><em>Commit</em> all (<code class="docutils literal notranslate"><span class="pre">-a</span></code>) those newly added files to git and add a message <code class="docutils literal notranslate"><span class="pre">-m</span></code> so you remember
what you did at this point. Doing a commit is like saving a snapshot of the
current state of everything.</p></li>
</ul>
<p>Read on for details!</p>
<section id="tracking-files">
<h3>Tracking files<a class="headerlink" href="#tracking-files" title="Permalink to this headline"></a></h3>
<p>When working on your code or fix bugs in your local branches you may end up creating new files. If
you do you must tell Git to track them by using the add command.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git add &lt;filename&gt;
</pre></div>
</div>
<p>You only need to do this once per file.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git status
</pre></div>
</div>
<p>will show if you have any modified, added or otherwise changed files. Some
files, like database files, logs and temporary PID files are usually <em>not</em>
tracked in version control. These should either not show up or have a question
mark in front of them.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>You will notice that some files are not covered by your git version control,
notably your settings file (<code class="docutils literal notranslate"><span class="pre">mygame/server/conf/settings.py</span></code>) and your sqlite3
database file <code class="docutils literal notranslate"><span class="pre">mygame/server/evennia.db3</span></code>. What is auto-ignored by is controlled
by the hidden file <code class="docutils literal notranslate"><span class="pre">mygame/.gitignore</span></code>. Evennia creates this file as part of
the creation of your game directory. Everything matched in this file will be
ignored by git. If you want to, for example, include your settings file for
collaborators to access, remove that entry in <code class="docutils literal notranslate"><span class="pre">.gitignore</span></code>.</p>
</div>
<p>Your game-dir is now tracked by git.</p>
<p>You will notice that some files are not covered by your git version control, notably your secret-settings file (<code class="docutils literal notranslate"><span class="pre">mygame/server/conf/secret_settings.py</span></code>) and your sqlite3 database file <code class="docutils literal notranslate"><span class="pre">mygame/server/evennia.db3</span></code>. This is intentional and controlled from the file <code class="docutils literal notranslate"><span class="pre">mygame/.gitignore</span></code>.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>You should <em>never</em> put your sqlite3 database file into git by removing its entry
in <code class="docutils literal notranslate"><span class="pre">.gitignore</span></code>. GIT is for backing up your code, not your database. That way
lies madness and a good chance you’ll confuse yourself so that after a few
commits and reverts don’t know what is in your database or not. If you want to
backup your database, do so by simply copying the file on your hard drive to a
backup-name.</p>
lies madness and a good chance you’ll confuse yourself. Make one mistake or local change and after a few commits and reverts you will have lost track of what is in your database or not. If you want to backup your SQlite3 database, do so by simply copying the database file to a safe location.</p>
</div>
</section>
<section id="committing-your-code">
<h3>Committing your Code<a class="headerlink" href="#committing-your-code" title="Permalink to this headline"></a></h3>
<p><em>Committing</em> your code means storing the current snapshot of your code within
git. This creates a “save point” or “history” of your development process. You
can later jump back and forth in your history, for example to figure out just
when a bug was introduced or see what results the code used to produce compared
to now. Or just wiping everything since the last commit, if you did something
stupid.</p>
<p>It’s usually a good idea to commit your changes often. Committing is fast and
local only - you will never commit anything online at this point. To commit your
changes, use</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git commit --all
</pre></div>
</div>
<p>Also <code class="docutils literal notranslate"><span class="pre">-a</span></code> works. This will open a text editor for you to describe your change.
Be brief but informative in your message - you’ll appreciate it later. When you
save and close the editor, the commit will be saved. You can create the message
directly with</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git commit -a -m &quot;This fixes a bug in the combat code.&quot;
</pre></div>
</div>
</section>
<section id="changing-your-mind">
<h3>Changing your mind<a class="headerlink" href="#changing-your-mind" title="Permalink to this headline"></a></h3>
<p>If you have non-committed changes that you realize you want to throw away, you
‘check out’ the file you want - this will re-load it from the last committed
state:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git checkout &lt;file_to_revert&gt;
git checkout foo/bar/dummy.py
</pre></div>
</div>
<p>If you want to revert <em>all</em> changes you did since last commit, do</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git checkout .
</pre></div>
</div>
<p>(that is, add a single <code class="docutils literal notranslate"><span class="pre">.</span></code> at the end).</p>
</section>
<section id="pushing-your-code-online">
<h3>Pushing your code online<a class="headerlink" href="#pushing-your-code-online" title="Permalink to this headline"></a></h3>
<p>So far your code is only located on your private machine. A good idea is to back
it up online. The easiest way to do this is to push it to your own remote
repository on GitHub.</p>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>Just to avoid confusion, be aware that Github’s documentation has changed to
calling the primary branch ‘main’ rather than ‘master’. While Evennia still
uses ‘master’ branch (and this is what we refer to below), you can use either
name for your personal primary branch - they are equivalent.</p>
<p>So far your code is only located on your private machine. A good idea is to back it up online. The easiest way to do this is to <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span></code> it to your own remote repository on GitHub. So for this you need a (free) Github account.</p>
<p>If you don’t want your code to be publicly visible, Github also allows you set up a <em>private</em> repository, only visible to you.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Github’s defaults have changed to calling the primary branch ‘main’ rather than ‘master’. While Evennia still uses ‘master’ branch (and this is what we refer to below), you can use either name for your personal primary branch - they are equivalent.</p>
</div>
<ol class="simple">
<li><p>Make sure you have your game directory setup under git version control as
described in the previous section. Make sure to commit any changes you did.</p></li>
<li><p>Create a new, empty repository on Github. Github explains how
<a class="reference external" href="https://help.github.com/articles/create-a-repo/">here</a> (do <em>not</em> “Initialize
the repository with a README” or else you’ll create unrelated histories).</p></li>
<li><p>From your local game dir, do <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">remote</span> <span class="pre">add</span> <span class="pre">origin</span> <span class="pre">&lt;github</span> <span class="pre">URL&gt;</span></code> where
<code class="docutils literal notranslate"><span class="pre">&lt;github</span> <span class="pre">URL&gt;</span></code> is the URL to your online repo. This tells your game dir that
it should be pushing to the remote online dir.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">remote</span> <span class="pre">-v</span></code> to verify the online dir.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span> <span class="pre">origin</span> <span class="pre">master</span></code> (or <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span> <span class="pre">origin</span> <span class="pre">main</span></code>) now pushes your game dir
online so you can see it on <a class="reference external" href="http://github.com">github.com</a>.</p></li>
</ol>
<p>You can commit your work locally (<code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span> <span class="pre">--all</span> <span class="pre">-m</span> <span class="pre">&quot;Make</span> <span class="pre">a</span> <span class="pre">change</span> <span class="pre">that</span> <span class="pre">...&quot;</span></code>) as many times as you want. When you want to push those changes to your
online repo, you do <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span></code>. You can also <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">clone</span> <span class="pre">&lt;url_to_online_repo&gt;</span></code>
from your online repo to somewhere else (like your production server) and
henceforth do <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">pull</span></code> to update that to the latest thing you pushed.</p>
<p>Note that GitHub’s repos are, by default publicly visible by all. Creating a
publicly visible online clone might not be what you want for all parts of your
development process - you may prefer a more private venue when sharing your
revolutionary work with your team. If that’s the case you can change your
repository to “Private” in the github settings. Then your code will only be
visible to those you specifically grant access.</p>
</section>
</section>
<section id="forking-evennia">
<h2>Forking Evennia<a class="headerlink" href="#forking-evennia" title="Permalink to this headline"></a></h2>
<p>This helps you set up an online <em>fork</em> of the main Evennia repository so you can
easily commit fixes and help with upstream development. You can do this step
also if you <em>didn’t</em> put your game dir under version control like in the
previous section - the evennia repo and your game dir repo are completely
separate.</p>
<section id="step-1-fork-the-evennia-master-repository">
<h3>Step 1: Fork the evennia/master repository<a class="headerlink" href="#step-1-fork-the-evennia-master-repository" title="Permalink to this headline"></a></h3>
<blockquote>
<div><p>Before proceeding with the following step, make sure you have registered and
created an account on <a class="reference external" href="https://github.com/">GitHub.com</a>. This is necessary in order to create a fork
of Evennia’s master repository, and to push your commits to your fork either for
yourself or for contributing to
Evennia.</p>
</div></blockquote>
<p>A <em>fork</em> is a clone of the master repository that you can make your own commits
and changes to. At the top of <a class="reference external" href="https://github.com/evennia/evennia">this page</a>,
click the “Fork” button, as it appears below.
<img alt="" src="https://github-images.s3.amazonaws.com/help/bootcamp/Bootcamp-Fork.png" /></p>
</section>
<section id="step-2-clone-your-online-fork-of-evennia">
<h3>Step 2: Clone your online fork of Evennia<a class="headerlink" href="#step-2-clone-your-online-fork-of-evennia" title="Permalink to this headline"></a></h3>
<p>The fork only exists online as of yet. In a terminal, change your directory to
the folder you wish to develop in. From this directory run the following
command:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git clone https://github.com/yourusername/evennia.git
<p>Create a new, empty repository on Github. <a class="reference external" href="https://help.github.com/articles/create-a-repo/">Github explains how here</a> . <em>Don’t</em> allow it to add a README, license etc, that will just clash with what we upload later.</p>
<aside class="sidebar">
<p class="sidebar-title">Origin</p>
<p>We label the remote repository ‘origin’. This is the git default and means we won’t need to specify it explicitly later.</p>
</aside>
<p>Make sure you are in your local game dir (previously initialized as a git repo).</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git remote add origin &lt;github URL&gt;
</pre></div>
</div>
<p>This will download your fork to your computer. It creates a new folder
<code class="docutils literal notranslate"><span class="pre">evennia/</span></code> at your current location.</p>
<p>This tells Git that there is a remote repository at <code class="docutils literal notranslate"><span class="pre">&lt;github</span> <span class="pre">URL&gt;</span></code>. See the github docs as to which URL to use. Verify that the remote works with <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">remote</span> <span class="pre">-v</span></code></p>
<p>Now we push to the remote (labeled ‘origin’ which is the default):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git push
</pre></div>
</div>
<p>Depending on how you set up your authentication with github, you may be asked to enter your github username and password. If you set up SSH authentication, this command will just work.</p>
<p>You use <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span></code> to upload your local changes so the remote repository is in sync with your local one. If you edited a file online using the Github editor (or a collaborator pushed code), you use <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">pull</span></code> to sync in the other direction.</p>
</section>
<section id="step-3-configure-remotes">
<h3>Step 3: Configure remotes<a class="headerlink" href="#step-3-configure-remotes" title="Permalink to this headline"></a></h3>
<p>Your Evennia-fork is now separate from upstream, ‘official’ Evennia. You will
want to set it up so that you can easily sync our updates and changes to your
fork.</p>
<p>We do this by setting up a new <em>remote</em>. We actually already have one remote,
that is our own github form of Evennia. This got created when you cloned the
repo and defaults to being called <code class="docutils literal notranslate"><span class="pre">origin</span></code>.</p>
<p>We will now create a new remote called <code class="docutils literal notranslate"><span class="pre">upstream</span></code>.</p>
</section>
<section id="contributing-to-evennia">
<h2>Contributing to Evennia<a class="headerlink" href="#contributing-to-evennia" title="Permalink to this headline"></a></h2>
<p>If you want to help contributing to Evennia you must do so by <em>forking</em> - making your own remote copy of the Evennia repository on Github. So for this, you need a (free) Github account. Doing so is a completely separate process from <a class="reference internal" href="#putting-your-game-dir-under-version-control"><span class="std std-doc">putting your game dir under version control</span></a> (which you should also do!).</p>
<p>At the top right of <a class="reference external" href="https://github.com/evennia/evennia">the evennia github page</a>, click the “Fork” button:</p>
<p><img alt="fork button" src="../_images/fork_button.png" /></p>
<p>This will create a new online fork Evennia under your github account.</p>
<p>The fork only exists online as of yet. In a terminal, <code class="docutils literal notranslate"><span class="pre">cd</span></code> to the folder you wish to develop in. This folder should <em>not</em> be your game dir, nor the place you cloned Evennia into if you used the <a class="reference internal" href="../Setup/Installation-Git.html"><span class="doc std std-doc">Git installation</span></a>.</p>
<p>From this directory run the following command:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git clone https://github.com/yourusername/evennia.git evennia
</pre></div>
</div>
<p>This will download your fork to your computer. It creates a new folder <code class="docutils literal notranslate"><span class="pre">evennia/</span></code> at your current location. If you installed Evennia using the <a class="reference internal" href="../Setup/Installation-Git.html"><span class="doc std std-doc">Git installation</span></a>, this folder will be identical in content to the <code class="docutils literal notranslate"><span class="pre">evennia</span></code> folder you cloned during that installation. The difference is that this repo is connected to your remote fork and not to the ‘original’ <em>upstream</em> Evennia.</p>
<p>When we cloned our fork, git automatically set up a ‘remote repository’ labeled <code class="docutils literal notranslate"><span class="pre">origin</span></code> pointing to it. So if we do <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">pull</span></code> and <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span></code>, we’ll push to our fork.</p>
<p>We now want to add a second remote repository linked to the original Evennia repo. We will label this remote repository <code class="docutils literal notranslate"><span class="pre">upstream</span></code>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>cd evennia
git remote add upstream https://github.com/evennia/evennia.git
</pre></div>
</div>
<p>This adds a remote to the main evennia repo.</p>
<p>If you also want to access Evennia’s <code class="docutils literal notranslate"><span class="pre">develop</span></code> branch (the bleeding edge
development) do the following:</p>
<p>If you also want to access Evennia’s <code class="docutils literal notranslate"><span class="pre">develop</span></code> branch (the bleeding edge development) do the following:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git fetch upstream develop
git checkout develop
</pre></div>
</div>
<p>Use
git checkout master
git checkout develop</p>
<p>to switch between the branches. If you want to contribute a fix, ask first which
branch to use. Normally <code class="docutils literal notranslate"><span class="pre">master</span></code> is for bug fixes and <code class="docutils literal notranslate"><span class="pre">develop</span></code> is for new
features, but late in the development of a new Evennia version, all changes
often go into <code class="docutils literal notranslate"><span class="pre">develop</span></code>.</p>
</section>
</section>
<section id="working-with-your-evennia-fork">
<h2>Working with your Evennia fork<a class="headerlink" href="#working-with-your-evennia-fork" title="Permalink to this headline"></a></h2>
<p><em>Branches</em> are stand-alone editions of the same code. You make a commit to a
branch. Switching to a branch will change the code on-disk. You can easily
make a new branch off a parent branch, and then merge it back into the same
branch later (or throw it away). This is a very common way to work on new
features in safety and isolation.</p>
<section id="updating-to-latest-evennia">
<h3>Updating to latest Evennia<a class="headerlink" href="#updating-to-latest-evennia" title="Permalink to this headline"></a></h3>
<p>When Evennia’s official repository updates, first make sure to commit all your
changes to your branch and then checkout the “clean” master branch:</p>
<p>Use</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git checkout master
git pull upstream master
git checkout develop
</pre></div>
</div>
<p>Or, if you are working against Evennia’s development branch:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git checkout develop
git pull upstream develop
<p>to switch between the branches.</p>
<p>To pull the latest from upstream Evennia, just checkout the branch you want and do</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git pull upstream
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">pull</span></code> command will fetch all the changes from the “upstream” remote and
merge it into your local master/develop branch. It should now be a perfect copy
of the latest Evennia changes.</p>
</section>
<section id="making-changes">
<h3>Making changes<a class="headerlink" href="#making-changes" title="Permalink to this headline"></a></h3>
<p>As a rule of thumb you should <em>never</em> work directly in Evennia’s <code class="docutils literal notranslate"><span class="pre">master</span></code> or
<code class="docutils literal notranslate"><span class="pre">develop</span></code> branches. Instead you make a <em>new</em> branch off the branch you want
and change <em>that</em>.</p>
<aside class="sidebar">
<p class="sidebar-title">Pushing to upstream</p>
<p>You can’t do <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span> <span class="pre">upstream</span></code> unless you have write-access to the upstream Evennia repository. So there is no risk of you accidentally pushing your own code into the main, public repository.</p>
</aside>
<section id="fixing-an-evennia-bug-or-feature">
<h3>Fixing an Evennia bug or feature<a class="headerlink" href="#fixing-an-evennia-bug-or-feature" title="Permalink to this headline"></a></h3>
<p>This should be done in your fork of Evennia. You should <em>always</em> do this in a <em>separate git branch</em> based off the Evennia branch you want to improve.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git checkout master (or develop)
check checkout -b strange_bug
git branch - b myfixbranch
</pre></div>
</div>
<p>You now have a new branch <code class="docutils literal notranslate"><span class="pre">strange_bug</span></code> that is an exact replica of the branch you
had checked out when you created it. Here you can now make your own
modifications.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git branches
</pre></div>
</div>
<p>will show you which branches are available and which one you are currently
using. Use <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">checkout</span> <span class="pre">&lt;branch&gt;</span></code> to move between them, but remember to commit
your changes before you do.</p>
<p>You often want to make sure also your work-branch has the latest upstream
changes. To do this, you need to first update your copy of the
<code class="docutils literal notranslate"><span class="pre">master</span></code>/<code class="docutils literal notranslate"><span class="pre">develop</span></code> branch and then <em>merge</em> those changes into your work branch.
Make sure you have committed everything first!</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git commit -a -m &quot;My latest changes ...&quot; # on your strange_bug branch
git checkout master (or develop)
git pull upstream develop
git checkout strange_bug
<p>Now fix whatever needs fixing. Abide by the <a class="reference internal" href="Evennia-Code-Style.html"><span class="doc std std-doc">Evennia code style</span></a>. You can <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span></code> commit your changes along the way as normal.</p>
<p>Upstream Evennia is not standing still, so you want to make sure that your work is up-to-date with upstream changes. Make sure to first commit your <code class="docutils literal notranslate"><span class="pre">myfixbranch</span></code> changes, then</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git checkout master (or develop)
git pull upstream
git checkout myfixbranch
git merge master (or develop)
</pre></div>
</div>
<p>If everything went well, your <code class="docutils literal notranslate"><span class="pre">strange_bug</span></code> branch will now have the latest version
of Evennia merged with whatever changes you have done.</p>
<p>Now work away on your code and commit with reasonable commit messages</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git commit -a -m &quot;Fixed the issue in ...&quot;
git commit -a -m &quot;Adding unit tests. This resolves #123.&quot;
</pre></div>
</div>
<p>Use</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git diff
</pre></div>
</div>
<p>to see what you changed since last commit, and</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git log
</pre></div>
</div>
<p>to see past commits (including those made by Evennia upstream, remember that
your branch is a copy of the upstream one, including its history!)</p>
</section>
</section>
<section id="sharing-your-evennia-fixes-on-github">
<h2>Sharing your Evennia fixes on Github<a class="headerlink" href="#sharing-your-evennia-fixes-on-github" title="Permalink to this headline"></a></h2>
<p>Up to this point your <code class="docutils literal notranslate"><span class="pre">strange_bug</span></code> branch only exists on your local computer. No
one else can see it. If you want a copy of this branch to also appear in your
online fork on GitHub, make sure to have checked out your “myfixes” branch and
then run the following:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git push -u origin strange_bug
</pre></div>
</div>
<p>You only need to do this once, the <code class="docutils literal notranslate"><span class="pre">-u</span></code> makes this the default push-location. In
the future, you can just push things online like this:</p>
<p>Up to this point your <code class="docutils literal notranslate"><span class="pre">myfixbranch</span></code> branch only exists on your local computer. No
one else can see it.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git push
</pre></div>
</div>
<p>This will automatically create a matching <code class="docutils literal notranslate"><span class="pre">myfixbranch</span></code> in your forked version of Evennia and push to it. On github you will be able to see appear it in the <code class="docutils literal notranslate"><span class="pre">branches</span></code> dropdown. You can keep pushing to your remote <code class="docutils literal notranslate"><span class="pre">myfixbranch</span></code> as much as you like.</p>
<p>Once you feel you have something to share, you need to <a class="reference external" href="https://github.com/evennia/evennia/pulls">create a pull request</a> (PR):
This is a formal request for upstream Evennia to adopt and pull your code into the main repository.</p>
<ol class="simple">
<li><p>Click <code class="docutils literal notranslate"><span class="pre">New</span> <span class="pre">pull</span> <span class="pre">request</span></code></p></li>
<li><p>Choose <code class="docutils literal notranslate"><span class="pre">compare</span> <span class="pre">across</span> <span class="pre">forks</span></code></p></li>
<li><p>Select your fork from dropdown list of <code class="docutils literal notranslate"><span class="pre">head</span> <span class="pre">repository</span></code> repos. Pick the right branch to <code class="docutils literal notranslate"><span class="pre">compare</span></code>.</p></li>
<li><p>On the Evennia side (to the left) make sure to pick the right <code class="docutils literal notranslate"><span class="pre">base</span></code> branch: If you want to contribute a change to the <code class="docutils literal notranslate"><span class="pre">develop</span></code> branch, you must pick <code class="docutils literal notranslate"><span class="pre">develop</span></code> as the <code class="docutils literal notranslate"><span class="pre">base</span></code>.</p></li>
<li><p>Then click <code class="docutils literal notranslate"><span class="pre">Create</span> <span class="pre">pull</span> <span class="pre">request</span></code> and fill in as much information as you can in the form.</p></li>
<li><p>Optional: Once you saved your PR, you can go into your code (on github) and add some per-line comments; this can help reviewers by explaining complex code or decisions you made.</p></li>
</ol>
<p>Now you just need to wait for your code to be reviewed. Expect to get feedback and be asked to make changes, add more documentation etc. Getting as PR merged can take a few iterations.</p>
<aside class="sidebar">
<p class="sidebar-title">Not all PRs can merge</p>
<p>While most PRs get merged, Evennia can’t <strong>guarantee</strong> that your PR code will be deemed suitable to merge into upstream Evennia. For this reason it’s a good idea to check in with the community <em>before</em> you spend a lot of time on a large piece of code (fixing bugs is always a safe bet though!)</p>
</aside>
</section>
</section>
<section id="troubleshooting">
<h3>Troubleshooting<a class="headerlink" href="#troubleshooting" title="Permalink to this headline"></a></h3>
<p>If you hadn’t setup a public key on GitHub or aren’t asked for a
username/password, you might get an error <code class="docutils literal notranslate"><span class="pre">403:</span> <span class="pre">Forbidden</span> <span class="pre">Access</span></code> at this stage.
In that case, some users have reported that the workaround is to create a file
<code class="docutils literal notranslate"><span class="pre">.netrc</span></code> under your home directory and add your github credentials there:</p>
<h2>Troubleshooting<a class="headerlink" href="#troubleshooting" title="Permalink to this headline"></a></h2>
<section id="getting-403-forbidden-access">
<h3>Getting 403: Forbidden access<a class="headerlink" href="#getting-403-forbidden-access" title="Permalink to this headline"></a></h3>
<p>Some users have experienced this on <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span></code> to their remote repository. They are not asked for username/password (and don’t have a ssh key set up).</p>
<p>Some users have reported that the workaround is to create a file <code class="docutils literal notranslate"><span class="pre">.netrc</span></code> under your home directory and add your github credentials there:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>machine github.com
login &lt;my_github_username&gt;
password &lt;my_github_password&gt;
@ -489,98 +461,6 @@ password &lt;my_github_password&gt;
</div>
</section>
</section>
<section id="making-an-evennia-pull-request">
<h2>Making an Evennia Pull Request<a class="headerlink" href="#making-an-evennia-pull-request" title="Permalink to this headline"></a></h2>
<p>If you think that the fixes you did in your <code class="docutils literal notranslate"><span class="pre">strange_bug</span></code> branch should be a
part of the regular Evennia, you should create a <em>Pull Request</em> (PR). This is a
call for the Evennia maintainer to pull your change into an upstream branch.</p>
<blockquote>
<div><p>It is wise to make separate branches for every fix or series of fixes you want
to contribute.</p>
</div></blockquote>
<p>Assuming you have followed the instructions above and have pushed your changes
online, <a class="reference external" href="https://github.com/evennia/evennia/pulls">create a pull request</a> and
follow the instructions. Make sure to specifically select your <code class="docutils literal notranslate"><span class="pre">strange_bug</span></code>
branch to be the source of the merge and use the branch you based that branch
off (<code class="docutils literal notranslate"><span class="pre">master</span></code> or <code class="docutils literal notranslate"><span class="pre">develop</span></code>) as the target.</p>
<p>Evennia developers will then be able to examine your request and merge it if
it’s deemed suitable. They may also come back with feedback and request you do
some changes.</p>
<p>Once approved and merged, your change will now be available in the upstream
branch:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git checkout master (or develope)
git pull upstream master (or develop)
</pre></div>
</div>
<p>Since your changes are now in upstream, your local <code class="docutils literal notranslate"><span class="pre">strange_bug</span></code> branch is now
superfluous and should be deleted:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git branch -D strange_bug
</pre></div>
</div>
<p>You can also safely delete your online <code class="docutils literal notranslate"><span class="pre">strange_bug</span></code> branch in your fork
(you can do this from the PR page on github).</p>
</section>
<section id="git-tips-and-tricks">
<h2>GIT tips and tricks<a class="headerlink" href="#git-tips-and-tricks" title="Permalink to this headline"></a></h2>
<p>Some of the GIT commands can feel a little long and clunky if you need to do them often. Luckily you
can create aliases for those. Here are some useful commands to run:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git st</span>
<span class="c1"># - view brief status info</span>
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">st</span> <span class="s1">&#39;status -s&#39;</span>
</pre></div>
</div>
<p>Above, you only need to ever enter the <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">config</span> <span class="pre">...</span></code> command once - you have then added the new
alias. Afterwards, just do <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">st</span></code> to get status info. All the examples below follow the same
template.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git cl</span>
<span class="c1"># - clone a repository</span>
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">cl</span> <span class="n">clone</span>
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git cma &quot;commit message&quot;</span>
<span class="c1"># - commit all changes without opening editor for message</span>
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">cma</span> <span class="s1">&#39;commit -a -m&#39;</span>
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git ca</span>
<span class="c1"># - amend text to your latest commit message</span>
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">ca</span> <span class="s1">&#39;commit --amend&#39;</span>
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git fl</span>
<span class="c1"># - file log; shows diffs of files in latest commits</span>
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">fl</span> <span class="s1">&#39;log -u&#39;</span>
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git co [branchname]</span>
<span class="c1"># - checkout</span>
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">co</span> <span class="n">checkout</span>
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git br &lt;branchname&gt;</span>
<span class="c1"># - create branch</span>
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">br</span> <span class="n">branch</span>
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git ls</span>
<span class="c1"># - view log tree</span>
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">ls</span> <span class="s1">&#39;log --pretty=format:&quot;%C(green)%h\ %C(yellow)[</span><span class="si">%a</span><span class="s1">d]%Cred</span><span class="si">%d</span><span class="se">\</span>
<span class="s1">%Creset</span><span class="si">%s</span><span class="s1">%Cblue\ [</span><span class="si">%c</span><span class="s1">n]&quot; --decorate --date=relative --graph&#39;</span>
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git diff</span>
<span class="c1"># - show current uncommitted changes</span>
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">diff</span> <span class="s1">&#39;diff --word-diff&#39;</span>
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git grep &lt;query&gt;</span>
<span class="c1"># - search (grep) codebase for a search criterion</span>
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">grep</span> <span class="s1">&#39;grep -Ii&#39;</span>
</pre></div>
</div>
<p>To get a further feel for GIT there is also <a class="reference external" href="https://www.youtube.com/watch?v=1ffBJ4sVUb4#t=1m58s">a good YouTube talk about it</a> - it’s a bit long but it will help you understand the underlying ideas behind GIT
(which in turn makes it a lot more intuitive to use).</p>
</section>
</section>
@ -599,14 +479,14 @@ template.</p>
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Updating-Your-Game.html" title="Updating Your Game"
<a href="Debugging.html" title="Debugging"
>next</a> |</li>
<li class="right" >
<a href="Coding-Overview.html" title="Coding and development help"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Coding-Overview.html" >Coding and development help</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Version Control</a></li>
<li class="nav-item nav-item-this"><a href="">Coding using Version Control</a></li>
</ul>
<div class="develop">develop branch</div>
</div>