<h1>Coding using Version Control<aclass="headerlink"href="#coding-using-version-control"title="Permalink to this headline">¶</a></h1>
<p><aclass="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>
<asideclass="sidebar">
<pclass="sidebar-title">Do it!</p>
<p>It’s <em>strongly</em> recommended that you <aclass="reference internal"href="#putting-your-game-dir-under-version-control"><spanclass="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, <aclass="reference external"href="https://git-scm.com/">Git</a> . For additional help on using Git, please refer to the <aclass="reference external"href="https://help.github.com/articles/set-up-git#platform-all">Official GitHub documentation</a>.</p>
<li><p><strong>Mac</strong>: Mac platforms offer two methods for installation, one via MacPorts, which you can find out about <aclass="reference external"href="https://git-scm.com/book/en/Getting-Started-Installing-Git#Installing-on-Mac">here</a>, or you can use the <aclass="reference external"href="https://sourceforge.net/projects/git-osx-installer/">Git OSX Installer</a>.</p></li>
<div><p>You can find expanded instructions for installation <aclass="reference external"href="https://git-scm.com/book/en/Getting-Started-Installing-Git">here</a>.</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>
<div><p>To get a running start with Git, here’s <aclass="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>
<h2>Common Git commands<aclass="headerlink"href="#common-git-commands"title="Permalink to this headline">¶</a></h2>
<asideclass="sidebar">
<pclass="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 <codeclass="docutils literal notranslate"><spanclass="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>
<sectionid="git-init">
<h3><codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">init</span></code><aclass="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>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">.</span></code> means to apply to the current directory. If you are inside <codeclass="docutils literal notranslate"><spanclass="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>
<sectionid="git-add">
<h3><codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">add</span></code><aclass="headerlink"href="#git-add"title="Permalink to this headline">¶</a></h3>
<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>
<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>
<sectionid="git-commit">
<h3><codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">commit</span></code><aclass="headerlink"href="#git-commit"title="Permalink to this headline">¶</a></h3>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>git commit -a -m "This is the initial commit"
<p>This <em>commits</em> your changes. It stores a snapshot of all (<codeclass="docutils literal notranslate"><spanclass="pre">-a</span></code>) your code at the current time, adding a message <codeclass="docutils literal notranslate"><spanclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">-m</span></code>, a text editor opens for you to write the message instead.</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="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>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>git config --global alias.cma 'commit -a -m'
<h3><codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">status</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">diff</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">log</span></code><aclass="headerlink"href="#git-status-git-diff-and-git-log"title="Permalink to this headline">¶</a></h3>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>git status -s
<p>This gives a short (<codeclass="docutils literal notranslate"><spanclass="pre">-s</span></code>) of the files that changes since your last <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">commit</span></code>.</p>
<p>This shows exactly what changed in each file since you last made a <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">commit</span></code>. The <codeclass="docutils literal notranslate"><spanclass="pre">--word-diff</span></code> option means it will mark if a single word changed on a line.</p>
<p>This shows the log of all <codeclass="docutils literal notranslate"><spanclass="pre">commits</span></code> done. Each log will show you who made the change, the commit-message and a unique <em>hash</em> (like <codeclass="docutils literal notranslate"><spanclass="pre">ba214f12ab12e123...</span></code>) that uniquely describes that commit.</p>
<p>You can make the <codeclass="docutils literal notranslate"><spanclass="pre">log</span></code> command more succinct with some more options:</p>
<p>This adds coloration and another fancy effects (use <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">help</span><spanclass="pre">log</span></code> to see what they mean).</p>
<h3><codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">branch</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">checkout</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">merge</span></code><aclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">main</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">develop</span></code> branches are examples of this.</p>
<p>This checks out another branch. As long as you are in a branch all <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">commit</span></code>s will commit the code to that branch only.</p>
<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>
<p>This checks out a particular <em>commit</em>, identified by the hash you find with <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">branch</span><spanclass="pre">-b</span><spanclass="pre">newbranch</span></code> to break this code off into a new branch you can continue working from.</p>
<p>This <em>merges</em> the code from <codeclass="docutils literal notranslate"><spanclass="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 <aclass="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>
<h3><codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">glone</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">push</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">pull</span></code><aclass="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 <aclass="reference internal"href="#pushing-your-code-online"><spanclass="std std-doc">in the next section</span></a>.</p>
<p>This copies the remote repository to your current location. If you used the <aclass="reference internal"href="../Setup/Installation-Git.html"><spanclass="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>
<p>Once you cloned or otherwise set up a remote repository, using <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">commit</span></code> your changes before you can continue with <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">pull</span></code>.</p>
<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>
<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 <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">gr</span></code> with</p>
<h2>Putting your game dir under version control<aclass="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>
<asideclass="sidebar">
<pclass="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>
<p>You will notice that some files are not covered by your git version control, notably your secret-settings file (<codeclass="docutils literal notranslate"><spanclass="pre">mygame/server/conf/secret_settings.py</span></code>) and your sqlite3 database file <codeclass="docutils literal notranslate"><spanclass="pre">mygame/server/evennia.db3</span></code>. This is intentional and controlled from the file <codeclass="docutils literal notranslate"><spanclass="pre">mygame/.gitignore</span></code>.</p>
<divclass="admonition warning">
<pclass="admonition-title">Warning</p>
<p>You should <em>never</em> put your sqlite3 database file into git by removing its entry
in <codeclass="docutils literal notranslate"><spanclass="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. 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>
<sectionid="pushing-your-code-online">
<h3>Pushing your code online<aclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="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>
<p>Create a new, empty repository on Github. <aclass="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>
<asideclass="sidebar">
<pclass="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>
<p>This tells Git that there is a remote repository at <codeclass="docutils literal notranslate"><spanclass="pre"><github</span><spanclass="pre">URL></span></code>. See the github docs as to which URL to use. Verify that the remote works with <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">remote</span><spanclass="pre">-v</span></code></p>
<p>Now we push to the remote (labeled ‘origin’ which is the default):</p>
<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 <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">pull</span></code> to sync in the other direction.</p>
</section>
</section>
<sectionid="contributing-to-evennia">
<h2>Contributing to Evennia<aclass="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 <aclass="reference internal"href="#putting-your-game-dir-under-version-control"><spanclass="std std-doc">putting your game dir under version control</span></a> (which you should also do!).</p>
<p>At the top right of <aclass="reference external"href="https://github.com/evennia/evennia">the evennia github page</a>, click the “Fork” button:</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, <codeclass="docutils literal notranslate"><spanclass="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 <aclass="reference internal"href="../Setup/Installation-Git.html"><spanclass="doc std std-doc">Git installation</span></a>.</p>
<p>From this directory run the following command:</p>
<p>This will download your fork to your computer. It creates a new folder <codeclass="docutils literal notranslate"><spanclass="pre">evennia/</span></code> at your current location. If you installed Evennia using the <aclass="reference internal"href="../Setup/Installation-Git.html"><spanclass="doc std std-doc">Git installation</span></a>, this folder will be identical in content to the <codeclass="docutils literal notranslate"><spanclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">origin</span></code> pointing to it. So if we do <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">pull</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">upstream</span></code>:</p>
<p>If you also want to access Evennia’s <codeclass="docutils literal notranslate"><spanclass="pre">develop</span></code> branch (the bleeding edge development) do the following:</p>
<p>You can’t do <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">push</span><spanclass="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>
<sectionid="fixing-an-evennia-bug-or-feature">
<h3>Fixing an Evennia bug or feature<aclass="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>
<p>Now fix whatever needs fixing. Abide by the <aclass="reference internal"href="Evennia-Code-Style.html"><spanclass="doc std std-doc">Evennia code style</span></a>. You can <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">myfixbranch</span></code> changes, then</p>
<p>Up to this point your <codeclass="docutils literal notranslate"><spanclass="pre">myfixbranch</span></code> branch only exists on your local computer. No
<p>This will automatically create a matching <codeclass="docutils literal notranslate"><spanclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">branches</span></code> dropdown. You can keep pushing to your remote <codeclass="docutils literal notranslate"><spanclass="pre">myfixbranch</span></code> as much as you like.</p>
<p>Once you feel you have something to share, you need to <aclass="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>
<li><p>Select your fork from dropdown list of <codeclass="docutils literal notranslate"><spanclass="pre">head</span><spanclass="pre">repository</span></code> repos. Pick the right branch to <codeclass="docutils literal notranslate"><spanclass="pre">compare</span></code>.</p></li>
<li><p>On the Evennia side (to the left) make sure to pick the right <codeclass="docutils literal notranslate"><spanclass="pre">base</span></code> branch: If you want to contribute a change to the <codeclass="docutils literal notranslate"><spanclass="pre">develop</span></code> branch, you must pick <codeclass="docutils literal notranslate"><spanclass="pre">develop</span></code> as the <codeclass="docutils literal notranslate"><spanclass="pre">base</span></code>.</p></li>
<li><p>Then click <codeclass="docutils literal notranslate"><spanclass="pre">Create</span><spanclass="pre">pull</span><spanclass="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>
<asideclass="sidebar">
<pclass="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>
<sectionid="troubleshooting">
<h2>Troubleshooting<aclass="headerlink"href="#troubleshooting"title="Permalink to this headline">¶</a></h2>
<sectionid="getting-403-forbidden-access">
<h3>Getting 403: Forbidden access<aclass="headerlink"href="#getting-403-forbidden-access"title="Permalink to this headline">¶</a></h3>
<p>Some users have experienced this on <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">.netrc</span></code> under your home directory and add your github credentials there:</p>
