From 6ddfdd85f0077342d006b385effcebda25901325 Mon Sep 17 00:00:00 2001 From: Griatch Date: Tue, 4 Oct 2011 00:46:50 +0200 Subject: [PATCH] Updating ReST docs. --- docs/sphinx/source/wiki/Attributes.rst | 101 +++++----- docs/sphinx/source/wiki/BazaarDevel.rst | 176 ------------------ .../sphinx/source/wiki/BuildingQuickstart.rst | 59 ++++-- docs/sphinx/source/wiki/Colours.rst | 4 +- docs/sphinx/source/wiki/ConnectionScreen.rst | 2 +- docs/sphinx/source/wiki/GettingStarted.rst | 23 +-- docs/sphinx/source/wiki/Players.rst | 12 +- docs/sphinx/source/wiki/Scripts.rst | 15 +- .../source/wiki/StaffVersionControl.rst | 155 --------------- docs/sphinx/source/wiki/TextEncodings.rst | 7 +- docs/sphinx/source/wiki/UpdatingYourGame.rst | 11 +- 11 files changed, 134 insertions(+), 431 deletions(-) delete mode 100644 docs/sphinx/source/wiki/BazaarDevel.rst delete mode 100644 docs/sphinx/source/wiki/StaffVersionControl.rst diff --git a/docs/sphinx/source/wiki/Attributes.rst b/docs/sphinx/source/wiki/Attributes.rst index ed8d17868a..f7f19b467d 100644 --- a/docs/sphinx/source/wiki/Attributes.rst +++ b/docs/sphinx/source/wiki/Attributes.rst @@ -23,35 +23,24 @@ data to arbitrary names. Saving and Retrieving data -------------------------- -The **default** way of storing data on Typeclassed objects is simply to -assign data to it. Let's try to save some data to a *Rose* (an +To save persistent data on a Typeclassed object you normally use the +``db`` operator. Let's try to save some data to a *Rose* (an `Object `_): -:: - - # saving - rose.has_thorns = True# getting it back - is_ouch = rose.has_thorns - -Whether this data is saved *persistently* to the database or not (i.e. -if it survives a server reboot) depends on the setting of the variable -``FULL_PERSISTENCE`` in the settings (it's described in more detail -later on this page). - -To be **sure** to save your data persistently, regardless of the setting -of ``FULL_PERSISTENCE``, use the ``db`` (!DataBase) interface. - :: # saving rose.db.has_thorns = True # getting it back is_ouch = rose.db.has_thorns -This creates a new ``Attribute`` object and links it uniquely to -``rose``. Using ``db`` ``will`` always save data to the database. +This looks like any normal Python assignment, but that ``db`` makes sure +that an *Attribute* is created behind the scenes and is stored in the +database. Your rose will continue to have thorns throughout the life of +the server now, until you deliberately remove them. -To be sure to save **non-persistently**, you use ``ndb`` (!NonDataBase). -It works in the same way: +To be sure to save **non-persistently**, i.e. to make sure NOT create a +database entry, you use ``ndb`` (!NonDataBase). It works in the same +way: :: @@ -59,8 +48,6 @@ It works in the same way: rose.ndb.has_thorns = True # getting it back is_ouch = rose.ndb.has_thorns -(Using ``ndb`` like this will **NEVER** use the database.) - Strictly speaking, ``ndb`` has nothing to do with ``Attributes``, despite how similar they look. No ``Attribute`` object is created behind the scenes when using ``ndb``. In fact the database is not invoked at @@ -73,6 +60,45 @@ will for example delete an ``Attribute``: del rose.db.has_thorns +Fast assignment +--------------- + +For quick testing you can most often skip the ``db`` operator and assign +Attributes like you would any normal Python property: + +:: + + # saving + rose.has_thorns = True# getting it back + is_ouch = rose.has_thorns + +This looks like any normal Python assignment, but calls ``db`` behind +the scenes for you. + +Assigning attributes this way is intuitive and makes for slightly less +to write. There is a drawback to using this short-form though: Database +objects and typeclasses *already* have a number of Python methods and +properties defined on themselves. If you use one of those already-used +names with this short form you will not be setting a new Attribute but +will infact be editing an existing engine property. + +For example, the property ``self.location`` on yourself is tied directly +to the ``db_location`` database field and will not accept anything but +an ``ObjectDB`` object or it will raise a traceback. ``self.delete`` is +a method handling the deletion of objects, and so on. The reason these +are available is of course that you may *want* to overload these +functions with your own implementations - this is one of the main powers +of Evennia. But if you blindly do e.g. ``self.msg = "Hello"`` you will +happily be overloading the core ``msg()`` method and be in a world of +pain. + +Using ``db`` will always work like you expect. ``self.db.msg = 'Hello'`` +will create a new Attribute ``msg`` without affecting the core method +named ``msg()`` at all. So in principle, whereas you can use the +short-form for simple testing, it's best to use ``db`` when you want +Attributes and skip it only when you explicitly want to edit/overload +something in the base classes. + Persistent vs non-persistent ---------------------------- @@ -98,35 +124,8 @@ situations though. harmful stuff to your character object. With non-persistent storage you can be sure that whatever the script messes up, it's nothing a server reboot can't clear up. -- You want to implement a fully or partly *non-persistent world*. - Whereas this sounds to us like something of an under-use of the - codebase's potential, who are we to argue with your grand vision! - -FULL\_PERSISTENCE ------------------ - -As mentioned above, Evennia allows you to change the default operation -when storing attributes by using ``FULL_PERSISTENCE`` in -``settings.py``. - -With ``FULL_PERSISTENCE`` on, you can completely ignore ``db`` and -assign properties to your object as you would any python object. This is -the 'default' method shown at the top). Behind the scenes an -``Attribute`` will be created and your data will be saved to the -database. Only thing you have to do explicitly is if you *don't* want -persistence, where you have to use ``ndb``. - -With ``FULL_PERSISTENCE`` off, the inverse is true. You then have to -specify ``db`` if you want to save, whereas normal assignment means -non-persistence. - -Regardless of the setting you can always use ``db`` and ``ndb`` -explicitly to get the result you want. This means writing a little bit -more, but has the advantage of clarity and portability: If you plan to -distribute your code to others, it's recommended you use explicit -assignment. This avoids weird errors when your users don't happen to use -the save persistence setting as you. The Evennia server distribution -always use explicit assignment everywhere. +- You want to implement a fully or partly *non-persistent world*. Who + are we to argue with your grand vision! What types of data can I save? ------------------------------ diff --git a/docs/sphinx/source/wiki/BazaarDevel.rst b/docs/sphinx/source/wiki/BazaarDevel.rst deleted file mode 100644 index 6cf63e4232..0000000000 --- a/docs/sphinx/source/wiki/BazaarDevel.rst +++ /dev/null @@ -1,176 +0,0 @@ -Setting up a solo coding environment with version control -========================================================= - -*This page deals with working as a lone coder. See also how to use -version control to collaborate with many people on a game -`here `_.* - -Version control software allows you to easily backtrack changes to your -code, help to share your development efforts and more. Even if you are -not contributing to Evennia itself, but is "just" developing your own -game using Evennia, having a version control system in place is a good -idea. If you want more info, start with the wikipedia article about it -`here `_. Note that this -page deals with commands in the Linux operating system. Details may vary -for other systems. - -Bazaar and SVN --------------- - -Evennia itself uses the *Subversion* (SVN)version control system. This -relatively old version control system lacks some of the more modern -features of later systems, but is universally recognized and easy to -use. Just because we use SVN centrally does not mean that you have to -use it when working with Evennia on your local machine however. - -`Bazaar `_ (bzr) is a version control -system written entirely in Python. It's available for all major -platforms. It's a more modern system than SVN and is generally easy to -use, also for newbies (other commonly seen systems similar to Bazaar are -GIT and Mercurial). We won't go into the details of what makes Bazaar -different from SVN, there are many texts about this on the internet. -What is important though is that Bazaar interfaces very well with SVN, -by use of a plugin called, *bzr-svn*. - -Prerequisites -------------- - -Bazaar and bzr-svn are both available from the normal Linux package -managers (see the homepage for how to download for other systems). -Install those first, then give the command ``bzr`` in a terminal to make -sure it's available. - -First, identify to bazaar by giving the command -``bzr whoami name `` - -``bzr whoami Harry Olsson `` - -You can put a nickname here too if you want. This is just so the system -knows what to put to identify new revisions. - -Setting up for a single developer ---------------------------------- - -We will here assume you are downloading Evennia for the first time. We -will set up a simple environment for hacking your game in. - -Make a new folder on your hard drive, for example named *evennia*. -Outside this folder, give the command - -``bzr init-repo evennia`` - -This sets the ``evennia`` folder up as a Bazaar repository, ready to -use. Enter this folder now. Next we obtain the Evennia server, except we -now use Bazaar to do it and not SVN. - -``bzr checkout http://evennia.googlecode.com/svn/trunk/ evennia-trunk`` - -(Contributors use the contributor URL instead). A new folder -``evennia-trunk`` has appeared in your repository! In it you will find -the entire Evennia source. Working with this folder works almost -identically to how it would work with SVN - you use ``bzr update`` to -get the latest version, contributors use ``bzr commit`` to enter their -changes to the server. Actually coding away in this folder is not ideal -however. As mentioned, doing ``bzr commit`` will (attempt to) push your -changes to the main Evennia repository, which is most often not what you -want when developing your own game. This is where Bazaar kicks in. We -will leave ``evennia-trunk`` be and create a separate *branch* to do our -work in. Change your directory to the root ``evennia`` one, then copy to -a new branch, let's call it ``evennia-mygame``: - -``bzr branch evennia-trunk evennia-mygame`` - -A new folder appeared, containing a copy of the code. ``evennia-mygame`` -is where you do all your work. If you do commits in here, they will be -committed locally, not to Evennia central. You now have full version -control on your machine. Updating your work code becomes a simple -two-step process of updating ``evennia-trunk`` and then *merging* those -changes into ``evennia-mygame``. Read on. - -Example work process for single developer -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -First we make sure our copy of Evennia is up-to-date. Go to -``evennia-trunk`` - -``bzr update`` - -Bazaar goes online and gets the latest Evennia revision from the central -repository, merging it automatically into the branch. - -So ``evennia-trunk`` is now up-to-date. Go to ``evennia-mygame``. -``bzr merge ../evennia-trunk`` - -The changes in ``evennia-trunk`` are pulled in and merged with -``evennia-mygame``. You can now continue to hack away in -``evennia-mygame``. Maybe you define new commands, fix bugs, create -batchfiles or what have you. If you create any new files, you must tell -Bazaar to handle them too, using the ``add`` command: - -``bzr add `` - -Check the current status of the version control with - -``bzr 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. "Unknown" -files need to be added with ``add`` before Bazaar can track them. - -It's usually a good idea to commit your changes often. This gives you a -snapshot of your work that you can get back to. - -``bzr 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 list. If -you don't want to use the editor you can set the message right away with -the ``-m`` flag: - -``bzr 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: - -``bzr revert`` - -You can view the full log of committed changes with - -``bzr log`` - -See the Bazaar manuals for learning more about useful day-to-day -commands, and special situations such as dealing with text collisions -etc. - -Evennia Contributor -~~~~~~~~~~~~~~~~~~~ - -If you are an Evennia contributor, you can also have use of the Bazaar -setup above. The only difference is that you then also have commit -permission to the Evennia main repository. - -You can have any number of work branches in your ``evennia`` folder. -Let's say your work branch for fixing Evennia bugs and features is -``evennia-work``. You update and work with this the same way as -``evennia-mygame`` above. - -After having committed your latest changes, move to the -``evennia-trunk`` folder. - -``bzr update`` - -This makes sure your local trunk is up-to-date. - -``bzr merge ../evennia-work`` - -This merges your updates into the ``evennia-trunk`` branch. - -``bzr commit`` - -Give the commit message and your changes will be pushed to the central -repository. Done! - -.. figure:: http://d.imagehost.org/0452/bazaar_repo1.png - :align: center - :alt: - diff --git a/docs/sphinx/source/wiki/BuildingQuickstart.rst b/docs/sphinx/source/wiki/BuildingQuickstart.rst index 0710ddb69f..e3e50aa6e2 100644 --- a/docs/sphinx/source/wiki/BuildingQuickstart.rst +++ b/docs/sphinx/source/wiki/BuildingQuickstart.rst @@ -27,6 +27,28 @@ assigning something to an object. Below are some examples of commands. Use ``help `` for learning more about each command and their detailed options. +Making a Builder +---------------- + +If you just installed Evennia, your very first player account is called +user #1, also known as the *superuser* or *god user*. This user is very +powerful, so powerful that it will override many game restrictions such +as locks. This can be useful, but it also hides some functionality that +you might want to test. Let's create a more "normal" Builder player +account instead. + +Log off and choose ``create`` from the login screen. Create a new +account (don't log in). Let's say we call the new account "Anna". Next +log in as your superuser account and give the recently created player +build rights: + +:: + + @perm Anna = Builders + +That should do it. Log out again (``@quit``) and finally log back in as +your builder account. + Creating an object ------------------ @@ -95,9 +117,10 @@ box was dropped in the room, then try this: > @lock box = get:false() Locks are a rather `big topic `_, but for now that will do -what we want. This will lock the box so noone can lift it (except -superusers, they override all locks and pick it up anyway). Make sure -you log in as another user than #1 and try to get the box now: +what we want. This will lock the box so noone can lift it. The exception +is superusers, they override all locks and will pick it up anyway. Make +sure you are using your builder account and not the superuser account +and try to get the box now: :: @@ -108,8 +131,7 @@ Think the default error message looks dull? The ``get`` command looks for an `Attribute `_ named ``get_err_msg`` for returning a nicer error message (we just happen to know this, you would currently need to peek into the code for the ``get`` command to find -out. You set attributes using the ``@set`` command (if you logged in as -another user, you need to have build permissions again for this): +out. You set attributes using the ``@set`` command: :: @@ -138,13 +160,15 @@ while and you will notice yourself starting making random observations. :: - > examine self + > @script self -This will show details about yourself. You will also see the script and -how long it is until it "fires" next (a randomizer determines if it will -say something, so you will not see any output every time it fires). +This will show details about scripts on yourself (also ``examine`` +works). You will see how long it is until it "fires" next. Don't be +alarmed if nothing happens when the countdown reaches zero - this +particular script has a randomizer to determine if it will say something +or not. So you will not see output every time it fires. -When you are tired of this, kill the script with +When you are tired of your character's "insights", kill the script with :: @@ -166,8 +190,7 @@ default object typeclass found in ``game/gamesrc/objects/baseobjects.py``. It is called simply *Object*. Let's create an object that is a little more interesting. Under ``game/gamesrc/objects/`` there is a directory ``examples`` with a -module ``red_button.py``. It contains the enigmatic *!RedButton* -typeclass. +module ``red_button.py``. It contains the enigmatic RedButton typeclass. Let's make us one of *those*! @@ -175,14 +198,12 @@ Let's make us one of *those*! > @create/drop button:examples.red_button.RedButton -With the ``/drop`` switch we make sure to drop the button right away -without having to use the ``drop`` command later. We import the -*!RedButton* python class the same way you would import it in Python -except Evennia defaults to looking in ``game/gamesrc/objects/`` so you -don't have to write the full path every time. There you go - one red -button. +We import the RedButton python class the same way you would import it in +Python except Evennia defaults to looking in ``game/gamesrc/objects/`` +so you don't have to write the full path every time. There you go - one +red button. -The *!RedButton* is an example object intended to show off many of +The RedButton is an example object intended to show off many of Evennia's features. You will find that the `Scripts `_ and `Commands `_ controlling it are scattered in ``examples``-folders all across ``game/gamesrc/``. diff --git a/docs/sphinx/source/wiki/Colours.rst b/docs/sphinx/source/wiki/Colours.rst index 34e768daab..1a472d5476 100644 --- a/docs/sphinx/source/wiki/Colours.rst +++ b/docs/sphinx/source/wiki/Colours.rst @@ -1,5 +1,5 @@ -Putting Colour to your game -=========================== +Adding Colour to your game +========================== *Note that the Docs does not display colour the way it would look on the screen.* diff --git a/docs/sphinx/source/wiki/ConnectionScreen.rst b/docs/sphinx/source/wiki/ConnectionScreen.rst index 39e8f9d4e9..21af093626 100644 --- a/docs/sphinx/source/wiki/ConnectionScreen.rst +++ b/docs/sphinx/source/wiki/ConnectionScreen.rst @@ -8,7 +8,7 @@ tells you how to connect. :: ============================================================== - Welcome to Evennia, version SVN-Alpha! If you have an existing account, connect to it by typing: + Welcome to Evennia, version HG-Alpha! If you have an existing account, connect to it by typing: connect If you need to create an account, type (without the <>'s): create "" Enter help for more info. look will re-show this screen. diff --git a/docs/sphinx/source/wiki/GettingStarted.rst b/docs/sphinx/source/wiki/GettingStarted.rst index a27f0a7e61..87e6e06aeb 100644 --- a/docs/sphinx/source/wiki/GettingStarted.rst +++ b/docs/sphinx/source/wiki/GettingStarted.rst @@ -62,7 +62,7 @@ Twisted also requires: **Django** (http://www.djangoproject.com) -- Version 1.2.1+ or latest subversion trunk highly recommended. +- Version 1.2.5+ or latest development versions highly recommended. - PIL library (http://www.pythonware.com/products/pil) To download/update Evennia: @@ -104,12 +104,13 @@ all you need: apt-get install python python-django python-twisted mercurial -If some or all dependencies are not readily available (for example, -running some flavors of !RedHat/CentOS or an older Debian version) you -can still retrieve them easily by installing and using Python's +Few distros actually keep the latest updated security updates (notably +django and twisted) in their repos though. So it might be worth to use +Python's `easyinstall `_ or the alternative -`pip `_: +`pip `_ to get some +or all of these instead: :: @@ -173,8 +174,8 @@ Step 2: Setting up the Server ----------------------------- From within the Evennia ``game`` directory (``evennia/game/``, if you -followed the Subversion instructions above) type the following to -trigger the automatic creation of an empty ``settings.py`` file. +followed the Mercurial instructions above) type the following to trigger +the automatic creation of an empty ``settings.py`` file. :: @@ -202,8 +203,8 @@ that variable (if any), or the dependent variables will remain at the default values.* Finally, enter the following command in a terminal or shell to create -the database file (in the case of SQLite) and populate the database with -the standard tables and values: +the database file (in the case of SQLite3) and populate the database +with the standard tables and values: :: @@ -269,8 +270,8 @@ for more advanced options on controlling Evennia's processes. Step 4: Connecting to the server -------------------------------- -The Evennia server is now up and running. You should now be able to -login with any mud client or telnet client using the email address and +The Evennia server is now up and running. You should be able to login +with any mud client or telnet client using the email address and password you specified when syncing the database. If you are just testing the server out on your local machine, the server name will most likely be ``localhost`` whereas the port used by default is ``4000``. diff --git a/docs/sphinx/source/wiki/Players.rst b/docs/sphinx/source/wiki/Players.rst index 4639e3b5f8..3870184c53 100644 --- a/docs/sphinx/source/wiki/Players.rst +++ b/docs/sphinx/source/wiki/Players.rst @@ -41,15 +41,19 @@ Here's how to define a new Player typeclass in code: :: - from src.players.player import Playerclass ConfigPlayer(Player): + from src.players.player import Player + class ConfigPlayer(Player): """ This creates a Player with some configuration options """ at_player_creation(self): - "this is called only once, when player is first created" self.db.real_name = None # this is set later - self.db.real_address = None # '' self.db.config_1 = True # default config + "this is called only once, when player is first created" + self.db.real_name = None # this is set later + self.db.real_address = None # '' + self.db.config_1 = True # default config self.db.config_2 = False # " - self.db.config_3 = 1 # " # ... whatever our game needs to know + self.db.config_3 = 1 # " + # ... whatever else our game needs to know There is no pre-made folder in ``game/gamesrc`` to store custom player typeclasses. Either make your own folder or store it in diff --git a/docs/sphinx/source/wiki/Scripts.rst b/docs/sphinx/source/wiki/Scripts.rst index 177d0e12f1..d750399119 100644 --- a/docs/sphinx/source/wiki/Scripts.rst +++ b/docs/sphinx/source/wiki/Scripts.rst @@ -71,7 +71,8 @@ care of all initialization and startup of the script for you. :: - # adding a script to an existing object 'myobj'myobj.scripts.add("game.gamesrc.scripts.myscripts.CoolScript") + # adding a script to an existing object 'myobj' + myobj.scripts.add("game.gamesrc.scripts.myscripts.CoolScript") The ``myobj.scripts.add()`` method also takes an argument *key* that allows you to name your script uniquely before adding it. This is not @@ -132,13 +133,16 @@ find longer descriptions of these in ``gamesrc/scripts/basescript.py``. :: import random - from game.gamesrc.scripts.basescript import Scriptclass Weather(Script): - "Displays weather info. Meant to be attached to a room." def at_script_creation(self): + from game.gamesrc.scripts.basescript import Script + class Weather(Script): + "Displays weather info. Meant to be attached to a room." + def at_script_creation(self): "Called once, during initial creation" self.key = "weather_script" self.desc = "Gives random weather messages." self.interval = 60 * 5 # every 5 minutes - self.persistent = True self.at_repeat(self): + self.persistent = True + self.at_repeat(self): "called every self.interval seconds." rand = random.random() if rand < 0.5: @@ -160,7 +164,8 @@ above. Here we put it on a room called ``myroom``: :: - # Assuming Script is found in game/gamesrc/scripts/weather.pymyroom.scripts.add(weather.Weather) + # Assuming Script is found in game/gamesrc/scripts/weather.py + myroom.scripts.add(weather.Weather) Or, from in-game, use the ``@script`` command: diff --git a/docs/sphinx/source/wiki/StaffVersionControl.rst b/docs/sphinx/source/wiki/StaffVersionControl.rst deleted file mode 100644 index 8d0e8874ad..0000000000 --- a/docs/sphinx/source/wiki/StaffVersionControl.rst +++ /dev/null @@ -1,155 +0,0 @@ -Using Version Control to collaboratively manage and develop a game -================================================================== - -*TODO: This page does not yet deal much with the specifics of access -control and protocols used when allowing access to a remove repository. -The example commands also lack proper testing!* - -Using modern `version control -software `_ is a powerful -way for a small development team to collaborate on a MUD project. Not -only will it help you keep track of your changes (and undo bad things -you do), it will also help combine the efforts of many people into one -joint place. - -Evennia uses version control in the form of the program Subversion (SVN) -to manage the entire project. It allows multiple coders to contribute -without getting in each other's way. The same mechanic would work just -as well on the next level - with several people collaborating to build -and code a MUD. - -This page uses the Python-based -`Bazaar `_ version control system as an -example of how to manage your MUD project. There are many other options -though, notably *GIT* or *Mercurial* are worth checking out if Bazaar is -not your thing. We use Bazaar's command-line interface, but Bazaar also -has a full graphical GUI called *Bazaar Explorer* that might make it -easier for newbies to get their head around the concept of version -control. We also cannot go into much detail here, please refer to the -very good Bazaar manuals for more help. - -Premise -------- - -Let's say you are the admin/owner of a new MUD initiative, based on -Evennia. The whole project will primarily be hosted on your computer. -You are doing this with a few good friends that will help you implement -the actual game system. You also have a few Builders/Coders of varying -skill to help with creating the game world. Apart from building through -their MUD clients, you also want them to be able to submit -build-batchfiles, small code snippets, custom typeclasses and scripts -- -without giving them full access to your custom-coded game source. - -First you need to set up a `development environment for a single -developer `_. That link will also teach you the basics -of using Bazaar. Return here when you are done. - -You should by this point have a Bazaar repository *evennia* containing -two branches, ``evennia-trunk`` and ``evennia-mygame``. - -Collaborating with trusted coders ---------------------------------- - -There are many ways to make your code base available to your fellow -administrators/coders. - -Branching remotely -~~~~~~~~~~~~~~~~~~ - -The absolutely easiest way is to have them use Bazaar to simply branch -your ``evennia-mygame`` branch as if it was any other branch. To do this -they need to set up their own repository first with - -``bzr init-repo`` - -Then they branch normally, but over the net: - -``bzr branch sftp://url.to.your.computer/evennia-mygame myworkcopy`` - -(This example uses sftp, but which protocol is used need to be setup and -agreed on. You also need to check so you don't have a firewall blocking -that protocol. The `Bazaar branching -manual `_ -gives a lot more info.) - -This will create their very own copy of the branch named ``myworkcopy``, -which they can work on as if it was their own. They can commit changes -to it etc without affecting you. To keep their branches up-to-date -against your branch they need to do a *pull*: - -``bzr pull sftp://url.to.your.computer/evennia-mygame`` - -When they are ready to merge back their changes into your branch, they -need to do a *push*: - -``bzr push sftp://url.to.your.computer/evennia-mygame`` - -SVN-like checkout -~~~~~~~~~~~~~~~~~ - -Another variant is to make a separate branch for your development -effort, and make this a *checkin branch*. Let's call this branch -*evennia-share*: - -``bzr branch evennia-mygame evennia-share`` - -So far this is the same as ``evennia-mygame``. With the *bind* command -you make this branch act as a centralized, SVN-like repository: - -``bzr bind evennia-share`` - -From now on, people now use ``commit`` and ``update`` from this branch, -and use ``checkout`` to retrieve their personal copy. In fact, users and -contributors can relate to this in the same way you deal with the main -Evennia repository, by setting up equivalents to ``evennia-trunk`` and -``evennia-mygame``. You merge to and from it as usual. - -Collaborating with limited access ---------------------------------- - -Not everyone should (or need) to download your entire customized -codebase (the contents of ``evennia-mygame``) just because they -volunteered to build a region of your game, or is scripting a new -object. And whereas some building can surely happen on-line through MUD -commands, the power of Evennia lies in its Python scripting abilities. -This means them sending you files of code one way or another. Using -e-mail or other communication methods works, but can quickly be a hassle -with many files of different versions. - -There are many ways to resolve this with version control, the easiest -might be to simply set aside an isolated place for them to upload their -data to you. - -You could have one branch for all builders (so they could collaborate -amongst themselves), or create a completely independent branch for each -builder: - -``bzr init anna-builds`` - -``bzr init peter-builds`` - -You could for example copy example files / builder instructions etc in -there as needed (``cp`` is a Linux/Unix command, use whatever method is -suitable in your OS): ``cp instructions.txt anna-builds`` - -``bzr add anna-builds/instructions.txt`` - -``bzr commit`` - -You could also *bind* this branch - -``bzr bind anna-builds`` - -so the builder in the future can simply use ``commit`` and ``update`` to -get things in and out of their respective upload area (they'd probably -not mind that they upload to your machine every time they make a -commit). - -You can in this way manually inspect submitted files before copying them -into the main branch as desired, using ``bzr add`` to have Bazaar track -them. - -.. figure:: http://b.imagehost.org/0824/bazaar_repo2.png - :align: center - :alt: - diff --git a/docs/sphinx/source/wiki/TextEncodings.rst b/docs/sphinx/source/wiki/TextEncodings.rst index d2dadb26c1..fc2dfc2b35 100644 --- a/docs/sphinx/source/wiki/TextEncodings.rst +++ b/docs/sphinx/source/wiki/TextEncodings.rst @@ -1,5 +1,8 @@ -Introduction -============ +Notes on text encodings +======================= + +Evennia is a text-based game server. This makes it important to +understand how it actually deals with data in the form of text. Text *byte encodings* describe how a string of text is actually stored in the computer - that is, the particular sequence of bytes used to diff --git a/docs/sphinx/source/wiki/UpdatingYourGame.rst b/docs/sphinx/source/wiki/UpdatingYourGame.rst index 14a32030cf..76d5d34d72 100644 --- a/docs/sphinx/source/wiki/UpdatingYourGame.rst +++ b/docs/sphinx/source/wiki/UpdatingYourGame.rst @@ -98,12 +98,13 @@ contain anything critical yet iẗ́'s probably easiest to simply reset it and start over rather than to bother converting. Enter `South `_. South keeps track of -changes in the database schema an applies them automatically for you. -Basically, whenever the schema changes we tell South exactly how to -repeat that change so you don't have to. +changes in the database schema and applies them automatically for you. +Basically, whenever the schema changes we also distribute small files +called "migrations" with the source. Those tell South exactly how to +repeat that change so you don't have to do so manually. -Using South is optional, but if you install it, Evennia *will* use South -automatically. See the correct section of +Using South is optional, but if you do install it, Evennia *will* use +South automatically. See the correct section of `GettingStarted `_ on how to install South and the slightly different way to start a clean database server when South is used (you have to give the ``mange.py migrate`` command as well as