Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-03-18 22:06:30 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
evennia/docs/1.0-dev/Version-Control.html
Griatch c62d004150 Updated HTML docs
2020-06-14 21:48:02 +02:00

528 lines
No EOL
45 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Version Control &mdash; Evennia 1.0-dev documentation</title>
<link rel="shortcut icon" href="_static/favicon.ico"/>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="index" title="Index"
href="genindex.html"/>
<link rel="search" title="Search" href="search.html"/>
<link rel="top" title="Evennia 1.0-dev documentation" href="index.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search">
<a href="index.html" class="icon icon-home"> Evennia
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<!-- Local TOC -->
<div class="local-toc"><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>
</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="#controlling-tracking">Controlling tracking</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="#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-fork">Step 2: Clone your fork</a></li>
<li><a class="reference internal" href="#step-3-configure-remotes">Step 3: Configure remotes</a></li>
</ul>
</li>
<li><a class="reference internal" href="#working-with-your-fork">Working with your fork</a><ul>
<li><a class="reference internal" href="#making-a-work-branch">Making a work branch</a></li>
<li><a class="reference internal" href="#updating-with-upstream-changes">Updating with upstream changes</a></li>
</ul>
</li>
<li><a class="reference internal" href="#sharing-your-code-publicly">Sharing your Code Publicly</a></li>
<li><a class="reference internal" href="#committing-fixes-to-evennia">Committing fixes to Evennia</a></li>
<li><a class="reference internal" href="#git-tips-and-tricks">GIT tips and tricks</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">Evennia</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html">Docs</a> &raquo;</li>
<li>Version Control</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/Version-Control.md.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" 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. Even if you are not contributing to Evennia itself, and only wish to develop your own MU* using Evennia, having a version control system in place is a good idea (and standard coding practice). For an introduction to the concept, start with the Wikipedia article <a class="reference external" href="http://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 also deals with commands for Linux operating systems, and the steps below may vary for other systems, however where possible links will be provided for alternative instructions.</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>
<div class="section" id="setting-up-git">
<h2>Setting up Git<a class="headerlink" href="#setting-up-git" title="Permalink to this headline"></a></h2>
<p>If you have gotten Evennia installed, you will have Git already and can skip to <strong>Step 2</strong> below. Otherwise you will need to install Git on your platform. You can find expanded instructions for installation <a class="reference external" href="http://git-scm.com/book/en/Getting-Started-Installing-Git">here</a>.</p>
<div class="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-default notranslate"><div class="highlight"><pre><span></span> <span class="n">yum</span> <span class="n">install</span> <span class="n">git</span><span class="o">-</span><span class="n">core</span>
</pre></div>
</div>
</li>
<li><p><strong>Debian Linux</strong> <em>(Ubuntu, Linux Mint, etc.)</em></p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="n">apt</span><span class="o">-</span><span class="n">get</span> <span class="n">install</span> <span class="n">git</span>
</pre></div>
</div>
</li>
<li><p><strong>Windows</strong>: It is recommended to use <a class="reference external" href="http://msysgit.github.io/">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="http://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>
</div>
<div class="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></blockquote>
<ol>
<li><p>Set the default name for git to use when you commit:</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">user</span><span class="o">.</span><span class="n">name</span> <span class="s2">&quot;Your Name Here&quot;</span>
</pre></div>
</div>
</li>
<li><p>Set the default email for git to use when you commit:</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">user</span><span class="o">.</span><span class="n">email</span> <span class="s2">&quot;your_email@example.com&quot;</span>
</pre></div>
</div>
</li>
</ol>
</div>
</div>
<div class="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></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-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">init</span> <span class="n">mygame</span>
</pre></div>
</div>
<p>Your mygame folder is now ready for version control! Now add all the content and make a first commit:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="n">mygame</span>
<span class="n">git</span> <span class="n">add</span> <span class="o">*</span>
<span class="n">git</span> <span class="n">commit</span> <span class="o">-</span><span class="n">m</span> <span class="s2">&quot;Initial commit&quot;</span>
</pre></div>
</div>
<p>Read on for help on what these commands do.</p>
<div class="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-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">add</span> <span class="o">&lt;</span><span class="n">filename</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>You can check the current status of version control with <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">status</span></code>. This 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>
<div class="section" id="controlling-tracking">
<h3>Controlling tracking<a class="headerlink" href="#controlling-tracking" title="Permalink to this headline"></a></h3>
<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>. This 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>
<blockquote>
<div><p>Note: 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>
</div></blockquote>
</div>
<div class="section" id="committing-your-code">
<h3>Committing your Code<a class="headerlink" href="#committing-your-code" title="Permalink to this headline"></a></h3>
<blockquote>
<div><p>Committing 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.</p>
</div></blockquote>
<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-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">commit</span> <span class="o">--</span><span class="nb">all</span>
</pre></div>
</div>
<p>This will save all changes you made since last commit. The command will open a text editor where you can add a message detailing the changes you’ve made. Make it brief but informative. You can see the history of commits with <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">log</span></code>. If you don’t want to use the editor you can set the message directly by using the <code class="docutils literal notranslate"><span class="pre">-m</span></code> flag:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">commit</span> <span class="o">--</span><span class="nb">all</span> <span class="o">-</span><span class="n">m</span> <span class="s2">&quot;This fixes a bug in the combat code.&quot;</span>
</pre></div>
</div>
</div>
<div class="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 can do the following:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">checkout</span> <span class="o">&lt;</span><span class="n">file</span> <span class="n">to</span> <span class="n">revert</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>This will revert the file to the state it was in at your last <code class="docutils literal notranslate"><span class="pre">commit</span></code>, throwing away the changes you did to it since. It’s a good way to make wild experiments without having to remember just what you changed. If you do <code class="docutils literal notranslate"> <span class="pre">git</span> <span class="pre">checkout</span> <span class="pre">.</span></code> you will throw away <em>all</em> changes since the last commit.</p>
</div>
<div class="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>
<ol class="simple">
<li><p>Make sure you have your game directory setup under git version control as described above. Make sure to commit any changes.</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> now pushes your game dir online so you can see it on github.com.</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>
</div>
</div>
<div class="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 Evennia so you can easily commit fixes and help with upstream development.</p>
<div class="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="https://github-images.s3.amazonaws.com/help/bootcamp/Bootcamp-Fork.png" src="https://github-images.s3.amazonaws.com/help/bootcamp/Bootcamp-Fork.png" /></p>
</div>
<div class="section" id="step-2-clone-your-fork">
<h3>Step 2: Clone your fork<a class="headerlink" href="#step-2-clone-your-fork" 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-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">yourusername</span><span class="o">/</span><span class="n">evennia</span><span class="o">.</span><span class="n">git</span>
</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>
</div>
<div class="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>A <em>remote</em> is a repository stored on another computer, in this case on GitHub’s server. When a repository is cloned, it has a default remote called <code class="docutils literal notranslate"><span class="pre">origin</span></code>. This points to your fork on GitHub, not the original repository it was forked from. To easily keep track of the original repository (that is, Evennia’s official repository), you need to add another remote. The standard name for this remote is “upstream”.</p>
<p>Below we change the active directory to the newly cloned “evennia” directory and then assign the original Evennia repository to a remote called “upstream”:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="n">evennia</span>
<span class="n">git</span> <span class="n">remote</span> <span class="n">add</span> <span class="n">upstream</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">evennia</span><span class="o">/</span><span class="n">evennia</span><span class="o">.</span><span class="n">git</span>
</pre></div>
</div>
<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 branch) do the following:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">fetch</span> <span class="n">upstream</span> <span class="n">develop</span>
<span class="n">git</span> <span class="n">checkout</span> <span class="n">develop</span>
</pre></div>
</div>
<p>You should now have the upstream branch available locally. You can use this instead of <code class="docutils literal notranslate"><span class="pre">master</span></code> below if you are contributing new features rather than bug fixes.</p>
</div>
</div>
<div class="section" id="working-with-your-fork">
<h2>Working with your fork<a class="headerlink" href="#working-with-your-fork" title="Permalink to this headline"></a></h2>
<blockquote>
<div><p>A <em>branch</em> is a separate instance of your code. Changes you do to code in a branch does not affect that in other branches (so if you for example add/commit a file to one branch and then switches to another branch, that file will be gone until you switch back to the first branch again). One can switch between branches at will and create as many branches as one needs for a given project. The content of branches can also be merged together or deleted without affecting other branches. This is not only a common way to organize development but also to test features without messing with existing code.</p>
</div></blockquote>
<p>The default <em>branch</em> of git is called the “master” branch. As a rule of thumb, you should <em>never</em> make modifications directly to your local copy of the master branch. Rather keep the master clean and only update it by pulling our latest changes to it. Any work you do should instead happen in a local, other branches.</p>
<div class="section" id="making-a-work-branch">
<h3>Making a work branch<a class="headerlink" href="#making-a-work-branch" title="Permalink to this headline"></a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">checkout</span> <span class="o">-</span><span class="n">b</span> <span class="n">myfixes</span>
</pre></div>
</div>
<p>This command will checkout and automatically create the new branch <code class="docutils literal notranslate"><span class="pre">myfixes</span></code> on your machine. If you stared out in the master branch, <em>myfixes</em> will be a perfect copy of the master branch. You can see which branch you are on with <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">branch</span></code> and change between different branches with <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">checkout</span> <span class="pre">&lt;branchname&gt;</span></code>.</p>
<p>Branches are fast and cheap to create and manage. It is common practice to create a new branch for every bug you want to work on or feature you want to create, then create a <em>pull request</em> for that branch to be merged upstream (see below). Not only will this organize your work, it will also make sure that <em>your</em> master branch version of Evennia is always exactly in sync with the upstream version’s master branch.</p>
</div>
<div class="section" id="updating-with-upstream-changes">
<h3>Updating with upstream changes<a class="headerlink" href="#updating-with-upstream-changes" 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>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">commit</span> <span class="o">--</span><span class="nb">all</span>
<span class="n">git</span> <span class="n">checkout</span> <span class="n">master</span>
</pre></div>
</div>
<p>Pull the latest changes from upstream:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">pull</span> <span class="n">upstream</span> <span class="n">master</span>
</pre></div>
</div>
<p>This should sync your local master branch with upstream Evennia’s master branch. Now we go back to our own work-branch (let’s say it’s still called “myfixes”) and <em>merge</em> the updated master into our branch.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">checkout</span> <span class="n">myfixes</span>
<span class="n">git</span> <span class="n">merge</span> <span class="n">master</span>
</pre></div>
</div>
<p>If everything went well, your <code class="docutils literal notranslate"><span class="pre">myfixes</span></code> branch will now have the latest version of Evennia merged with whatever changes you have done. Use <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">log</span></code> to see what has changed. You may need to restart the server or run <code class="docutils literal notranslate"><span class="pre">manage.py</span> <span class="pre">migrate</span></code> if the database schema changed (this will be seen in the commit log and on the mailing list). See the <a class="reference external" href="http://git-scm.com/documentation">Git manuals</a> for learning more about useful day-to-day commands, and special situations such as dealing with merge collisions.</p>
</div>
</div>
<div class="section" id="sharing-your-code-publicly">
<h2>Sharing your Code Publicly<a class="headerlink" href="#sharing-your-code-publicly" title="Permalink to this headline"></a></h2>
<p>Up to this point your <code class="docutils literal notranslate"><span class="pre">myfixes</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-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">push</span> <span class="o">-</span><span class="n">u</span> <span class="n">origin</span> <span class="n">myfixes</span>
</pre></div>
</div>
<p>This will create a new <em>remote branch</em> named “myfixes” in your online repository (which is refered to as “origin” by default); the <code class="docutils literal notranslate"><span class="pre">-u</span></code> flag makes sure to set this to the default push location. Henceforth you can just use <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span></code> from your myfixes branch to push your changes online. This is a great way to keep your source backed-up and accessible. Remember though that by default your repository will be public so everyone will be able to browse and download your code (same way as you can with Evennia itself). If you want secrecy you can change your repository to “Private” in the Github settings. Note though that if you do, you might have trouble contributing to Evennia (since we can’t see the code you want to share).</p>
<p><em>Note: 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 credentials there:</em></p>
<div class="highlight-bash notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
2
3</pre></div></td><td class="code"><div class="highlight"><pre><span></span>machine github.com
login &lt;my_github_username&gt;
password &lt;my_github_password&gt;
</pre></div>
</td></tr></table></div>
</div>
<div class="section" id="committing-fixes-to-evennia">
<h2>Committing fixes to Evennia<a class="headerlink" href="#committing-fixes-to-evennia" title="Permalink to this headline"></a></h2>
<p><em>Contributing</em> can mean both bug-fixes or adding new features to Evennia. Please note that if your change is not already listed and accepted in the <a class="reference external" href="https://github.com/evennia/evennia/issues">Issue Tracker</a>, it is recommended that you first hit the developer mailing list or IRC chat to see beforehand if your feature is deemed suitable to include as a core feature in the engine. When it comes to bug-fixes, other developers may also have good input on how to go about resolving the issue.</p>
<p>To contribute you need to have <a class="reference external" href="/Version-Control.html#forking-evennia">forked Evennia</a> first. As described above you should do your modification in a separate local branch (not in the master branch). This branch is what you then present to us (as a <em>Pull request</em>, PR, see below). We can then merge your change into the upstream master and you then do <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">pull</span></code> to update master usual. Now that the master is updated with your fixes, you can safely delete your local work branch. Below we describe this work flow.</p>
<p>First update the Evennia master branch to the latest Evennia version:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">checkout</span> <span class="n">master</span>
<span class="n">git</span> <span class="n">pull</span> <span class="n">upstream</span> <span class="n">master</span>
</pre></div>
</div>
<p>Next, create a new branch to hold your contribution. Let’s call it the “fixing_strange_bug” branch:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">checkout</span> <span class="o">-</span><span class="n">b</span> <span class="n">fixing_strange_bug</span>
</pre></div>
</div>
<p>It is wise to make separate branches for every fix or series of fixes you want to contribute. You are now in your new <code class="docutils literal notranslate"><span class="pre">fixing_strange_bug</span></code> branch. You can list all branches with <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">branch</span></code> and jump between branches with <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">checkout</span> <span class="pre">&lt;branchname&gt;</span></code>. Code and test things in here, committing as you go:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">commit</span> <span class="o">--</span><span class="nb">all</span> <span class="o">-</span><span class="n">m</span> <span class="s2">&quot;Fix strange bug in look command. Resolves #123.&quot;</span>
</pre></div>
</div>
<p>You can make multiple commits if you want, depending on your work flow and progress. Make sure to always make clear and descriptive commit messages so it’s easy to see what you intended. To refer to, say, issue number 123, write <code class="docutils literal notranslate"><span class="pre">#123</span></code>, it will turn to a link on GitHub. If you include the text “Resolves #123”, that issue will be auto-closed on GitHub if your commit gets merged into main Evennia.</p>
<blockquote>
<div><p>If you refer to in-game commands that start with <code class="docutils literal notranslate"><span class="pre">&#64;</span></code>(such as <code class="docutils literal notranslate"><span class="pre">&#64;examine</span></code>), please put them in backticks `, for example `&#64;examine`. The reason for this is that GitHub uses <code class="docutils literal notranslate"><span class="pre">&#64;username</span></code> to refer to GitHub users, so if you forget the ticks, any user happening to be named <code class="docutils literal notranslate"><span class="pre">examine</span></code> will get a notification ….</p>
</div></blockquote>
<p>If you implement multiple separate features/bug-fixes, split them into different branches if they are very different and should be handled as separate PRs. You can do any number of commits to your branch as you work. Once you are at a stage where you want to show the world what you did you might want to consider making it clean for merging into Evennia’s master branch by using <a class="reference external" href="https://www.git-scm.com/book/en/v2/Git-Branching-Rebasing">git rebase</a> (this is not always necessary, and if it sounds too hard, say so and we’ll handle it on our end).</p>
<p>Once you are ready, push your work to your online Evennia fork on github, in a new remote branch:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">push</span> <span class="o">-</span><span class="n">u</span> <span class="n">origin</span> <span class="n">fixing_strange_bug</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">-u</span></code> flag is only needed the first time - this tells GIT to create a remote branch. If you already created the remote branch earlier, just stand in your <code class="docutils literal notranslate"><span class="pre">fixing_strange_bug</span></code> branch and do <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span></code>.</p>
<p>Now you should tell the Evennia developers that they should consider merging your brilliant changes into Evennia proper. <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">fixing_strange_bug</span></code> branch to be the source of the merge. Evennia developers will then be able to examine your request and merge it if it’s deemed suitable.</p>
<p>Once your changes have been merged into Evennia your local <code class="docutils literal notranslate"><span class="pre">fixing_strange_bug</span></code> can be deleted (since your changes are now available in the “clean” Evennia repository). Do</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">branch</span> <span class="o">-</span><span class="n">D</span> <span class="n">fixing_strange_bug</span>
</pre></div>
</div>
<p>to delete your work branch. Update your master branch (<code class="docutils literal notranslate"><span class="pre">checkout</span> <span class="pre">master</span></code> and then <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">pull</span></code>) and you should get your fix back, now as a part of official Evennia!</p>
</div>
<div class="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="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>
</div>
</div>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2020, The Evennia developer community.
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> and ❤️ using a custom <a href="https://github.com/LinxiFan/Sphinx-theme">theme</a> based on <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'1.0-dev',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/language_data.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
Reference in a new issue View git blame Copy permalink