mirror of
https://github.com/evennia/evennia.git
synced 2026-03-18 13:56:30 +01:00
570 lines
No EOL
45 KiB
HTML
570 lines
No EOL
45 KiB
HTML
|
||
<!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>Version Control — 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" />
|
||
</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="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href="">Version Control</a></li>
|
||
</ul>
|
||
<div class="develop">develop branch</div>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<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="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 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>
|
||
<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="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-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="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>
|
||
</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></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">"Your Name Here"</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">"your_email@example.com"</span>
|
||
</pre></div>
|
||
</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></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">"Initial commit"</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Read on for help on what these commands do.</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-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">add</span> <span class="o"><</span><span class="n">filename</span><span class="o">></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>
|
||
</section>
|
||
<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>
|
||
</section>
|
||
<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">"This fixes a bug in the combat code."</span>
|
||
</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 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"><</span><span class="n">file</span> <span class="n">to</span> <span class="n">revert</span><span class="o">></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>
|
||
</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>
|
||
<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"><github</span> <span class="pre">URL></span></code> where <code class="docutils literal notranslate"><span class="pre"><github</span> <span class="pre">URL></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">"Make</span> <span class="pre">a</span> <span class="pre">change</span> <span class="pre">that</span> <span class="pre">..."</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"><url_to_online_repo></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 Evennia so you can easily commit fixes and help with
|
||
upstream development.</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="https://github-images.s3.amazonaws.com/help/bootcamp/Bootcamp-Fork.png" src="https://github-images.s3.amazonaws.com/help/bootcamp/Bootcamp-Fork.png" /></p>
|
||
</section>
|
||
<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>
|
||
</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>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>
|
||
</section>
|
||
</section>
|
||
<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>
|
||
<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"><branchname></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>
|
||
</section>
|
||
<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="https://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>
|
||
</section>
|
||
</section>
|
||
<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><span class="normal">1</span>
|
||
<span class="normal">2</span>
|
||
<span class="normal">3</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span>machine github.com
|
||
login <my_github_username>
|
||
password <my_github_password>
|
||
</pre></div>
|
||
</td></tr></table></div>
|
||
</section>
|
||
<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="Coding/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"><branchname></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">"Fix strange bug in look command. Resolves #123."</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">@</span></code>(such as <code class="docutils literal notranslate"><span class="pre">@examine</span></code>), please put them in
|
||
backticks `, for example `@examine`. The reason for this is that GitHub uses <code class="docutils literal notranslate"><span class="pre">@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>
|
||
</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">'status -s'</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 "commit message" </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">'commit -a -m'</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">'commit --amend'</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">'log -u'</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 <branchname></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">'log --pretty=format:"%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]" --decorate --date=relative --graph'</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">'diff --word-diff'</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git grep <query></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">'grep -Ii'</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>
|
||
|
||
|
||
<div class="clearer"></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<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>
|
||
<p><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>
|
||
</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 role="note" aria-label="source link">
|
||
<!--h3>This Page</h3-->
|
||
<ul class="this-page-menu">
|
||
<li><a href="../_sources/Coding/Version-Control.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/">Dev blog</a>
|
||
</li>
|
||
</ul>
|
||
<h3>Versions</h3>
|
||
<ul>
|
||
<li><a href="Version-Control.html">1.0-dev (develop branch)</a></li>
|
||
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
|
||
</ul>
|
||
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></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="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href="">Version Control</a></li>
|
||
</ul>
|
||
<div class="develop">develop branch</div>
|
||
</div>
|
||
<div class="footer" role="contentinfo">
|
||
© Copyright 2020, The Evennia developer community.
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
|
||
</div>
|
||
</body>
|
||
</html> |