Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-04-03 06:27:17 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: Adding missing rest pages to mercurial.

Browse source
This commit is contained in:
Griatch 2012-06-26 18:26:59 +02:00
parent f95fac1f51
commit ae65438c9b
16 changed files with 2114 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

257
docs/sphinx/source/wiki/VersionControl.rst Normal file
View file

@ -0,0 +1,257 @@
Setting up a coding environment with version control
====================================================
Version control software allows you to easily backtrack changes to your
code, help with sharing your development efforts and more. Even if you
are not contributing to Evennia itself, but is "just" developing your
own game, having a version control system in place is a good idea. If
you want more info, start with the wikipedia article about it
`here <http://en.wikipedia.org/wiki/Version_control>`_. Note that this
page deals with commands in the Linux operating system. Details may vary
for other systems.
Note: This is only one suggested way to use Mercurial by using separate
local clones. You could set up any number of different workflows if it
suited you better. See `here <http://mercurial.selenic.com/guide/>`_ for
some more examples.
Using Mercurial
===============
`Mercurial <http://mercurial.selenic.com/>`_ (abbreviated as ``hg``
after the chemical symbol for mercury) is a version control system
written mainly in Python. It's available for all major platforms.
First, identify to mercurial by creating a new file ``.hgrc`` in your
home directory and put the following content in it:
::
[ui]
username = MyName <myemail@mail.com>
You can put a nickname here too if you want. This is just so the system
knows how to credit new revisions.
Setting up
----------
We will here assume you are downloading Evennia for the first time. We
will set up a simple environment for hacking your game in. In the end it
will look like this:
::
evennia/
evennia-main
evennia-mygame
Create a new folder ``evennia`` and clone Evennia into it as
``evennia-main``:
::
hg clone https://code.google.com/p/evennia/ evennia-main
A new folder ``evennia-main`` has appeared. In it you will find the
entire Evennia source repository, including all its commit history -
it's really a full copy of what's available on the web.
We'll let ``evennia-main`` only contain the "clean" Evennia install -
it's a good debugging tool to tell you if a bug you find is due to your
changes or also visible in the core server. We'll develop our game in
another repository instead:
::
hg clone evennia-main evennia-mygame
This will create a new repository ``evennia-mygame`` on your machine. In
this directory you now code away, adding and editing things to your
heart's content to make your dream game.
Example work flow
-----------------
First we make sure our copy of Evennia is up-to-date. Go to
``evennia-main``:
::
cd evennia-main
hg pull
Mercurial goes online and gets the latest Evennia revision from the
central repository, merging it automatically into your repository. It
will tell you that you need to ``update`` to incoorporate the latest
changes. Do so.
::
hg update
So ``evennia-main`` is now up-to-date. If you want, you can review the
changes and make sure things work as they should. Finally go to
``evennia-mygame`` and pull the changes into that as well.
::
cd ../evennia-mygame
hg commit # (only if you had any changes)
hg pull ../evennia-main
hg update
You can now continue to hack away in ``evennia-mygame`` to build your
game. Maybe you define new commands, economic systems, create batchfiles
or what have you. If you create any new files, you must tell Mercurial
to track them by using the ``add`` command:
::
hg add <filename(s)>
Check the current status of the version control with
::
hg status
If you don't get any return value, you haven't made any changes since
last commit. Otherwise you will get a list of modified files.
It's usually a good idea to commit your changes often - it's fast and
only local - you will never commit anything online. This gives you a
"save" snapshot of your work that you can get back to.
::
hg commit
This will open a text editor where you can add a message detailing your
changes. These are the messages you see in the Evennia update/log list.
If you don't want to use the editor you can set the message right away
with the ``-m`` flag:
::
hg commit -m "This should fix the bug Sarah talked about."
If you did changes that you wish you hadn't, you can easily get rid of
everything since your latest commit:
::
hg revert --all
Instead of ``--all`` you can also choose to revert individual files.
You can view the full log of committed changes with
::
hg log
See the Mercurial manuals for learning more about useful day-to-day
commands, and special situations such as dealing with text collisions
etc.
Sharing your code with the world
================================
The most common case of this is when you have fixed an Evennia bug and
want to make the fix available to Evennia maintainers. But you can also
share your work with other people on your game-development team if you
don't worry about the changes being publicly visible.
Let's take the example of debugging Evennia. Go online and create an
"online clone" of Evennia as described `here <Contributing.html>`_. Pull
this repo to your local machine -- so if your clone is named
``my-evennia-fixes``, you do something like this:
::
hg clone https://<yourname>@code.google.com/r/my-evennia-fixes evennia-fixes
You will now have a new folder ``evennia-fixes``. Let's assume we want
to use this to push bug fixes to Evennia. It works like any other
mercurial repository except you also have push-rights to your online
clone from it. When working, you'd first update it to the latest
upstream Evennia version:
::
cd evennia-main
hg pull
hg update
cd ../evennia-fixes
hg pull ../evennia-main
hg update
Now you fix things in ``evennia-fixes``. Commit your changes as
described above. Make sure to make clear and descriptive commit messages
so it's easy to see what you intended. You can do any number of commits
as you work. Once you are at a stage where you want to show what you did
to the world, you push all the so-far committed changes to your online
clone:
::
hg push
(You'd next need to tell Evennia devs that they should merge your
brilliant changes into Evennia proper. Create a new
`Issue <https://code.google.com/p/evennia/issues/list>`_ of type *Merge
Request*, informing them of this.)
Apart from supporting Evennia itself you can have any number of online
clones for different purposes, such as sharing game code or collaborate
on solutions. Just pull stuff from whichever relevant local repository
you have (like ``evennia-mygame``) and push to a suitably named online
clone so people can get to it.
Sharing your code only with a small coding team
===============================================
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.
An online hosting provider offering private repositories is probably
your best bet. For example, if all your contributors are registered on
`BitBucket <https://bitbucket.org/>`_, that service offers free
"private" repositories that you could use for this.
An alternative simple way to share your work with a limited number of
people is to use mercurial's own simple webserver and let them connect
directly to your machine:
::
cd evennia-mygame
hg serve -p 8500
(the port was changed because the default port is 8000 and that is
normally used by Evennia's own webserver). Find out the IP address of
your machine visible to the net (make sure you know your firewall setup
etc). Your collaborators will then be able to first review the changes
in their browser:
::
firefox http://192.168.178.100:8500
and pull if they like what they see:
::
hg pull http://192.168.178.100:8500
See `here <http://mercurial.selenic.com/wiki/hgserve>`_ for more
information on using ``hg serve``.
Mercurial's in-built webserver is *very* simplistic and not particularly
robust. It only allows one connection at a time, lacks authorization and
doesn't even allow your collaborators to ``push`` data to you (there is
nothing stopping them to set up a server of their own so you can pull
from them though).