diff --git a/docs/1.0-dev/.buildinfo b/docs/1.0-dev/.buildinfo index 555670851f..7b62cec386 100644 --- a/docs/1.0-dev/.buildinfo +++ b/docs/1.0-dev/.buildinfo @@ -1,4 +1,4 @@ # Sphinx build info version 1 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. -config: 0004a5f6b965a26712178e2e59d11179 +config: 2073b8f3514aba16a52753d4c9e4e820 tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/docs/1.0-dev/Coding/Changelog.html b/docs/1.0-dev/Coding/Changelog.html index 7355206879..b703648a3c 100644 --- a/docs/1.0-dev/Coding/Changelog.html +++ b/docs/1.0-dev/Coding/Changelog.html @@ -17,7 +17,7 @@ - + -

After @reload, make some BlockingRooms (or switch a room to it with @typeclass). Entering one +

After reload, make some BlockingRooms (or switch a room to it with @typeclass). Entering one will now replace the given commands for anyone that does not have the Builders or higher permission. Note that the ‘call’ lock is special in that even the superuser will be affected by it -(otherwise superusers would always see other player’s cmdsets and a game would be unplayable for -superusers).

+(otherwise superusers would always see other player’s cmdsets and a game would be unplayable for superusers).

Select Command based on a condition

Q: I want a command to be available only based on a condition. For example I want the “werewolf” command to only be available on a full moon, from midnight to three in-game time.

-

A: This is easiest accomplished by putting the “werewolf” command on the Character as normal, -but to lock it with the “cmd” type lock. Only if the “cmd” lock type is passed will the +

A: This is easiest accomplished by putting the “werewolf” command on the Character as normal, but to lock it with the “cmd” type lock. Only if the “cmd” lock type is passed will the command be available.

# in mygame/commands/command.py
 
@@ -264,8 +216,7 @@ command be available.

         # ...
-

Add this to the default cmdset as usual. The is_full_moon lock -function does not yet exist. We must create that:

+

Add this to the default cmdset as usual. The is_full_moon lock function does not yet exist. We must create that:

# in mygame/server/conf/lockfuncs.py
 
 def is_full_moon(accessing_obj, accessed_obj,
@@ -276,7 +227,7 @@ function does not yet exist. We must create that:
-

After a @reload, the werewolf command will be available only at the right time, that is when the +

After a reload, the werewolf command will be available only at the right time, that is when the is_full_moon lock function returns True.

@@ -299,43 +250,28 @@ you have your project in a configured Git environment, it’s a matter of automa process = subprocess.call(["git", "pull"], shell=False) -

That’s all. We call subprocess to execute a shell command (that code works on Windows and Linux, -assuming the current directory is your game directory, which is probably the case when you run -Evennia). call waits for the process to complete, because otherwise, Evennia would reload on -partially-modified code, which would be problematic.

-

Now, when you enter @reload on your development server, the game repository is updated from the -configured remote repository (Github, for instance). Your development cycle could resemble -something like:

+

That’s all. We call subprocess to execute a shell command (that code works on Windows and Linux, assuming the current directory is your game directory, which is probably the case when you run Evennia). call waits for the process to complete, because otherwise, Evennia would reload on partially-modified code, which would be problematic.

+

Now, when you enter reload on your development server, the game repository is updated from the configured remote repository (Github, for instance). Your development cycle could resemble something like:

  1. Coding on the local machine.

  2. Testing modifications.

    3. -

  3. Committing once, twice or more (being sure the code is still working, unittests are pretty useful -here).

    4. +

  4. Committing once, twice or more (being sure the code is still working, unittests are pretty useful here).

  5. When the time comes, login to the development server and run @reload.

-

The reloading might take one or two additional seconds, since Evennia will pull from your remote Git -repository. But it will reload on it and you will have your modifications ready, without needing +

The reloading might take one or two additional seconds, since Evennia will pull from your remote Git repository. But it will reload on it and you will have your modifications ready, without needing connecting to your server using SSH or something similar.

Changing all exit messages

Q: How can I change the default exit messages to something like “XXX leaves east” or “XXX arrives from the west”?

-

A: the default exit messages are stored in two hooks, namely announce_move_from and -announce_move_to, on the Character typeclass (if what you want to change is the message other -characters will see when a character exits).

-

These two hooks provide some useful features to easily update the message to be displayed. They -take both the default message and mapping as argument. You can easily call the parent hook with -these information:

+

A: the default exit messages are stored in two hooks, namely announce_move_from and announce_move_to, on the Character typeclass (if what you want to change is the message other characters will see when a character exits).

+

These two hooks provide some useful features to easily update the message to be displayed. They take both the default message and mapping as argument. You can easily call the parent hook with these information:

-

It is advisable to look in the code of both -hooks, and read the -hooks’ documentation. The explanations on how to quickly update the message are shown below:

+

It is advisable to look in the code of both hooks, and read the hooks’ documentation. The explanations on how to quickly update the message are shown below:

# In typeclasses/characters.py
 """
 Characters
@@ -394,16 +330,12 @@ hooks’ documentation.  The explanations on how to quickly update the message a
         super().announce_move_to(source_location, msg="{object} arrives from the {exit}.")
-

We override both hooks, but call the parent hook to display a different message. If you read the -provided docstrings, you will better understand why and how we use mappings (information between -braces). You can provide additional mappings as well, if you want to set a verb to move, for -instance, or other, extra information.

+

We override both hooks, but call the parent hook to display a different message. If you read the provided docstrings, you will better understand why and how we use mappings (information between braces). You can provide additional mappings as well, if you want to set a verb to move, for instance, or other, extra information.

Add parsing with the “to” delimiter

Q: How do I change commands to undestand say give obj to target as well as the default give obj = target?

-

A: You can make change the default MuxCommand parent with your own class making a small change -in its parse method:

+

A: You can make change the default MuxCommand parent with your own class making a small change in its parse method:

    # in mygame/commands/command.py
     from evennia import default_cmds
     class MuxCommand(default_cmds.MuxCommand):
@@ -418,39 +350,9 @@ in its parse
 
    COMMAND_DEFAULT_CLASS = "commands.command.MuxCommand"
 

 

-
Do a @reload and all default commands will now use your new tweaked parent class. A copy of the
+
Do a reload and all default commands will now use your new tweaked parent class. A copy of the
 MuxCommand class is also found commented-out in the mygame/commands/command.py file.
-
-

Store last used session IP address

-

Q: If a user has already logged out of an Evennia account, their IP is no longer visible to -staff that wants to ban-by-ip (instead of the user) with @ban/ip?

-

A: One approach is to write the IP from the last session onto the “account” account object.

-

typeclasses/accounts.py

-
    def at_post_login(self, session=None, **kwargs):
-        super().at_post_login(session=session, **kwargs)
-        self.db.lastsite = self.sessions.all()[-1].address
-
-
-

Adding timestamp for login time and appending to a list to keep the last N login IP addresses and -timestamps is possible, also. Additionally, if you don’t want the list to grow beyond a -do_not_exceed length, conditionally pop a value after you’ve added it, if the length has grown too -long.

-

NOTE: You’ll need to add import time to generate the login timestamp.

-
    def at_post_login(self, session=None, **kwargs):
-        super().at_post_login(session=session, **kwargs)
-        do_not_exceed = 24  # Keep the last two dozen entries
-        session = self.sessions.all()[-1]  # Most recent session
-        if not self.db.lastsite:
-           self.db.lastsite = []
-        self.db.lastsite.insert(0, (session.address, int(time.time())))
-        if len(self.db.lastsite) > do_not_exceed:
-            self.db.lastsite.pop()
-
-
-

This only stores the data. You may want to interface the @ban command or make a menu-driven viewer -for staff to browse the list and display how long ago the login occurred.

-

Non-latin characters in EvTable

Q: When using e.g. Chinese characters in EvTable, some lines appear to be too wide, for example

@@ -461,11 +363,7 @@ for staff to browse the list and display how long ago the login occurred.

+~~~~~~+~~~~~~+ -

A: The reason for this is because certain non-latin characters are visually much wider than -their len() suggests. There is little Evennia can (reliably) do about this. If you are using such -characters, you need to make sure to use a suitable mono-spaced font where are width are equal. You -can set this in your web client and need to recommend it for telnet-client users. See this -discussion where some suitable fonts are suggested.

+

A: The reason for this is because certain non-latin characters are visually much wider than their len() suggests. There is little Evennia can (reliably) do about this. If you are using such characters, you need to make sure to use a suitable mono-spaced font where are width are equal. You can set this in your web client and need to recommend it for telnet-client users. See this discussion where some suitable fonts are suggested.

@@ -485,10 +383,10 @@ discussion where some suitable fonts are suggested.

modules |
  • - next |
  • - previous |
  • Evennia 1.0-dev »
  • Coding and development help »
    • diff --git a/docs/1.0-dev/Coding/Coding-Introduction.html b/docs/1.0-dev/Coding/Coding-Introduction.html deleted file mode 100644 index a548bf13fd..0000000000 --- a/docs/1.0-dev/Coding/Coding-Introduction.html +++ /dev/null @@ -1,268 +0,0 @@ - - - - - - - - - Coding Introduction — Evennia 1.0-dev documentation - - - - - - - - - - - - - - - -
    - -
    - -
    -
    - -
    -

    Coding Introduction

    -

    Evennia allows for a lot of freedom when designing your game - but to code efficiently you still -need to adopt some best practices as well as find a good place to start to learn.

    -

    Here are some pointers to get you going.

    -
    -

    Start with the tutorial

    -

    It’s highly recommended that you jump in on the Starting Tutorial. Even if -you only the beginning or some part of it, it covers much of the things needed to get started, including giving you are first introduction to Python.

    -
    -
    -

    Explore Evennia interactively

    -

    As mentioned in the Starting tutorial, it’s a good idea to use ipython to explore things using a python shell:

    -
    # [open a new console/terminal]
-cd mygame
-evennia shell
-
    -
    -

    This will open an Evennia-aware python shell (using ipython). From within this shell, try

    -
    import evennia
-evennia.<TAB>
-
    -
    -
    -

    Jupyter Notebook Support

    -

    You can also explore evennia interactively in a Jupyter notebook. This offers -an in-browser view of your code similar to Matlab or similar programs. There are -a few extra steps that must be taken in order for this to work:

    -
    # [open a new console/terminal]
-# [activate your evennia virtualenv in this console/terminal]
-cd evennia
-pip install -r requirements_extra.txt  # if not done already above
-
    -
    -

    Next, cd to your game folder. It’s important that you are in the root of this folder for the next command:

    -
    evennia shell_plus --notebook &
-
    -
    -

    The & at the end starts the process as a background process on Linux/Unix. -Skip it if your OS doesn’t support this syntax. Your browser should now open -with the Jupyter interface. If not, open a browser to the link given on the -command line.

    -

    In the window, open the new menu in the top right and start a Django Shell-Plus notebook (or -open an existing one if you had one from before). In the first cell you must initialize -Evennia like so:

    -
    import evennia
-evennia._init()
-
    -
    -

    Note that the above initialization must be run every time a new new notebook/kernel is started or restarted.

    -

    After this you can import and access all of the Evennia system, same as with evennia shell.

    -
    -
    -

    More exploration

    -

    You can complement your exploration by peeking at the sections of the much more detailed -Evennia Component overview. The Tutorials section also contains a growing collection -of system- or implementation-specific help.

    -
    -
    -
    -

    Use a python syntax checker

    -

    Evennia works by importing your own modules and running them as part of the server. Whereas Evennia -should just gracefully tell you what errors it finds, it can nevertheless be a good idea for you to -check your code for simple syntax errors before you load it into the running server. There are -many python syntax checkers out there. A fast and easy one is -pyflakes, a more verbose one is -pylint. You can also check so that your code looks up to snuff using -pep8. Even with a syntax checker you will not be able to catch -every possible problem - some bugs or problems will only appear when you actually run the code. But -using such a checker can be a good start to weed out the simple problems.

    -
    -
    -

    Plan before you code

    -

    Before you start coding away at your dream game, take a look at our Game Planning -page. It might hopefully help you avoid some common pitfalls and time sinks.

    -
    -
    -

    Code in your game folder, not in the evennia/ repository

    -

    As part of the Evennia setup you will create a game folder to host your game code. This is your -home. You should never need to modify anything in the evennia library (anything you download -from us, really). You import useful functionality from here and if you see code you like, copy&paste -it out into your game folder and edit it there.

    -

    If you find that Evennia doesn’t support some functionality you need, make a Feature Request about it. Same goes for bugs. If you add features or fix bugs yourself, please consider Contributing your changes upstream!

    -
    -
    -

    Learn to read tracebacks

    -

    Python is very good at reporting when and where things go wrong. A traceback shows everything you -need to know about crashing code. The text can be pretty long, but you usually are only interested -in the last bit, where it says what the error is and at which module and line number it happened - -armed with this info you can resolve most problems.

    -

    Evennia will usually not show the full traceback in-game though. Instead the server outputs errors -to the terminal/console from which you started Evennia in the first place. If you want more to show -in-game you can add IN_GAME_ERRORS = True to your settings file. This will echo most (but not all) -tracebacks both in-game as well as to the terminal/console. This is a potential security problem -though, so don’t keep this active when your game goes into production.

    -
    -

    A common confusing error is finding that objects in-game are suddenly of the type DefaultObject -rather than your custom typeclass. This happens when you introduce a critical Syntax error to the -module holding your custom class. Since such a module is not valid Python, Evennia can’t load it at -all. Instead of crashing, Evennia will then print the full traceback to the terminal/console and -temporarily fall back to the safe DefaultObject until you fix the problem and reload.

    -
    -
    -
    -

    Docs are here to help you

    -

    Some people find reading documentation extremely dull and shun it out of principle. That’s your -call, but reading docs really does help you, promise! Evennia’s documentation is pretty thorough -and knowing what is possible can often give you a lot of new cool game ideas. That said, if you -can’t find the answer in the docs, don’t be shy to ask questions! The discussion -group and the irc -chat are also there for you.

    -
    -
    -

    The most important point

    -

    And finally, of course, have fun!

    -
    -
    - - -
    -
    -
    - -
    - - - - \ No newline at end of file diff --git a/docs/1.0-dev/Coding/Coding-Overview.html b/docs/1.0-dev/Coding/Coding-Overview.html index 12f19f64a3..da5a5c21b9 100644 --- a/docs/1.0-dev/Coding/Coding-Overview.html +++ b/docs/1.0-dev/Coding/Coding-Overview.html @@ -17,7 +17,7 @@ - + @@ -62,9 +62,8 @@

    Table of Contents

    develop branch
    diff --git a/docs/1.0-dev/Coding/Debugging.html b/docs/1.0-dev/Coding/Debugging.html index 0b6422aaab..0e6033c9d0 100644 --- a/docs/1.0-dev/Coding/Debugging.html +++ b/docs/1.0-dev/Coding/Debugging.html @@ -18,7 +18,7 @@ - + -

  • (Re-)start Evennia in interactive (foreground) mode with evennia istart. This is important - -without this step the debugger will not start correctly - it will start in this interactive -terminal.

    • -

  • Perform the steps that will trigger the line where you added the set_trace() call. The debugger -will start in the terminal from which Evennia was interactively started.

    • +

  • (Re-)start Evennia in interactive (foreground) mode with evennia istart. This is important - without this step the debugger will not start correctly - it will start in this interactive terminal.

    • +

  • Perform the steps that will trigger the line where you added the set_trace() call. The debugger will start in the terminal from which Evennia was interactively started.

    • The evennia.set_trace function takes the following arguments:

        evennia.set_trace(debugger='auto', term_size=(140, 40))
    -

    Here, debugger is one of pdb, pudb or auto. If auto, use pudb if available, otherwise -use pdb. The term_size tuple sets the viewport size for pudb only (it’s ignored by pdb).

    +

    Here, debugger is one of pdb, pudb or auto. If auto, use pudb if available, otherwise use pdb. The term_size tuple sets the viewport size for pudb only (it’s ignored by pdb).

    A simple example using pdb

    @@ -178,9 +169,7 @@ default cmdset. Then restart Evennia in interactive mode with test in your game, everything will freeze. You won’t get any feedback from the game, -and you won’t be able to enter any command (nor anyone else). It’s because the debugger has started -in your console, and you will find it here. Below is an example with pdb.

    +

    If you type test in your game, everything will freeze. You won’t get any feedback from the game, and you won’t be able to enter any command (nor anyone else). It’s because the debugger has started in your console, and you will find it here. Below is an example with pdb.

    ...
 > .../mygame/commands/command.py(79)func()
 -> obj = self.search(self.args)
@@ -191,8 +180,7 @@ in your console, and you will find it here. Below is an example with pdb notes where it has stopped execution and, what line is about to be executed (in our case, obj = self.search(self.args)), and ask what you would like to do.
    
 
    
 
    Listing surrounding lines of code
    
-
    When you have the pdb prompt (Pdb), you can type in different commands to explore the code.  The
-first one you should know is list (you can type l for short):
    
+
    When you have the pdb prompt (Pdb), you can type in different commands to explore the code.  The first one you should know is list (you can type l for short):
    
 
    (Pdb) l
  43
  44         key = "test"
@@ -208,17 +196,12 @@ first one you should know is (Pdb)
 
    
 
    
-
    Okay, this didn’t do anything spectacular, but when you become more confident with pdb and find
-yourself in lots of different files, you sometimes need to see what’s around in code.  Notice that
-there is a little arrow (->) before the line that is about to be executed.
    
-
    This is important: about to be, not has just been.  You need to tell pdb to go on (we’ll
-soon see how).
    
+
    Okay, this didn’t do anything spectacular, but when you become more confident with pdb and find yourself in lots of different files, you sometimes need to see what’s around in code.  Notice that there is a little arrow (->) before the line that is about to be executed.
    
+
    This is important: about to be, not has just been.  You need to tell pdb to go on (we’ll soon see how).
    
 
    
 
    
 
    Examining variables
    
-
    pdb allows you to examine variables (or really, to run any Python instruction).  It is very useful
-to know the values of variables at a specific line.  To see a variable, just type its name (as if
-you were in the Python interpreter:
    
+
    pdb allows you to examine variables (or really, to run any Python instruction).  It is very useful to know the values of variables at a specific line.  To see a variable, just type its name (as if you were in the Python interpreter:
    
 
    (Pdb) self
 <commands.command.CmdTest object at 0x045A0990>
 (Pdb) self.args
@@ -253,26 +236,19 @@ shorten it by just typing (Pdb)
 
    
 
    
-
    Pdb is complaining that you try to call the search method on a command… whereas there’s no
-search method on commands.  The character executing the command is in self.caller, so we might
-change our line:
    
+
    Pdb is complaining that you try to call the search method on a command… whereas there’s no search method on commands.  The character executing the command is in self.caller, so we might change our line:
    
 
    obj = self.caller.search(self.args)
 
    
 
    
 
    
 
    
 
    Letting the program run
    
-
    pdb is waiting to execute the same instruction… it provoked an error but it’s ready to try
-again, just in case.  We have fixed it in theory, but we need to reload, so we need to enter a
-command.  To tell pdb to terminate and keep on running the program, use the continue (or c)
-command:
    
+
    pdb is waiting to execute the same instruction… it provoked an error but it’s ready to try again, just in case.  We have fixed it in theory, but we need to reload, so we need to enter a command.  To tell pdb to terminate and keep on running the program, use the continue (or c) command:
    
 
    (Pdb) c
 ...
 
    
 
    
-
    You see an error being caught, that’s the error we have fixed… or hope to have.  Let’s reload the
-game and try again. You need to run evennia istart again and then run test to get into the
-command again.
    
+
    You see an error being caught, that’s the error we have fixed… or hope to have.  Let’s reload the game and try again. You need to run evennia istart again and then run test to get into the command again.
    
 
    > .../mygame/commands/command.py(79)func()
 -> obj = self.caller.search(self.args)
 (Pdb)
@@ -301,8 +277,7 @@ fix that bug too, it would be better):
    
 ...
 
    
 
    
-
    Notice that you’ll have an error in the game this time.  Let’s try with a valid parameter.  I have
-another character, barkeep, in this room:
    
+
    Notice that you’ll have an error in the game this time.  Let’s try with a valid parameter.  I have another character, barkeep, in this room:
    
 
    test barkeep
    
 
    And again, the command freezes, and we have the debugger opened in the console.
    
 
    Let’s execute this line right away:
    
@@ -324,32 +299,17 @@ another character, 
 (Pdb)
    -

    As an exercise, fix this error, reload and run the debugger again. Nothing better than some -experimenting!

    +

    As an exercise, fix this error, reload and run the debugger again. Nothing better than some experimenting!

    Your debugging will often follow the same strategy:

    1. Receive an error you don’t understand.

    2. Put a breaking point BEFORE the error occurs.

      3. +

    3. Run evennia istart

    4. Run the code again and see the debugger open.

      5. -

    5. Run the program line by line,examining variables, checking the logic of instructions.

      6. +

    6. Run the program line by line, examining variables, checking the logic of instructions.

    7. Continue and try again, each step a bit further toward the truth and the working feature.

    -
    -

    Stepping through a function

    -

    n is useful, but it will avoid stepping inside of functions if it can. But most of the time, when -we have an error we don’t understand, it’s because we use functions or methods in a way that wasn’t -intended by the developer of the API. Perhaps using wrong arguments, or calling the function in a -situation that would cause a bug. When we have a line in the debugger that calls a function or -method, we can “step” to examine it further. For instance, in the previous example, when pdb was -about to execute obj = self.caller.search(self.args), we may want to see what happens inside of -the search method.

    -

    To do so, use the step (or s) command. This command will show you the definition of the -function/method and you can then use n as before to see it line-by-line. In our little example, -stepping through a function or method isn’t that useful, but when you have an impressive set of -commands, functions and so on, it might really be handy to examine some feature and make sure they -operate as planned.

    -

    Cheat-sheet of pdb/pudb commands

    @@ -391,8 +351,7 @@ command is not needed much in -

    If you want to learn more about debugging with Pdb, you will find an interesting tutorial on that -topic here.

    +

    If you want to learn more about debugging with Pdb, you will find an interesting tutorial on that topic here.

    @@ -415,7 +374,7 @@ topic here.

    next |
  • - previous |
  • Evennia 1.0-dev »
  • Coding and development help »
    • diff --git a/docs/1.0-dev/Coding/Evennia-Code-Style.html b/docs/1.0-dev/Coding/Evennia-Code-Style.html new file mode 100644 index 0000000000..8c1b318977 --- /dev/null +++ b/docs/1.0-dev/Coding/Evennia-Code-Style.html @@ -0,0 +1,403 @@ + + + + + + + + + Evennia Code Style — Evennia 1.0-dev documentation + + + + + + + + + + + + + + + +
    + +
    + +
    +
    + +
    +

    Evennia Code Style

    +

    All code submitted or committed to the Evennia project should aim to follow the +guidelines outlined in Python PEP 8. Keeping the code style uniform +makes it much easier for people to collaborate and read the code.

    +

    A good way to check if your code follows PEP8 is to use the PEP8 tool +on your sources.

    +
    +

    Main code style specification

    +
      +

    • 4-space indentation, NO TABS!

      • +

    • Unix line endings.

      • +

    • 100 character line widths

      • +

    • CamelCase is only used for classes, nothing else.

      • +

    • All non-global variable names and all function names are to be +lowercase, words separated by underscores. Variable names should +always be more than two letters long.

      • +

    • Module-level global variables (only) are to be in CAPITAL letters.

      • +

    • Imports should be done in this order:

      +
        +

      • Python modules (builtins and standard library)

        • +

      • Twisted modules

        • +

      • Django modules

        • +

      • Evennia library modules (evennia)

        • +

      • Evennia contrib modules (evennia.contrib)

        • +
      +
      • +

    • All modules, classes, functions and methods should have doc strings formatted +as outlined below.

      • +

    • All default commands should have a consistent docstring formatted as +outlined below.

      • +
    +
    +
    +

    Code Docstrings

    +

    All modules, classes, functions and methods should have docstrings +formatted with Google style -inspired indents, using +Markdown formatting where needed. Evennia’s api2md +parser will use this to create pretty API documentation.

    +
    +

    Module docstrings

    +

    Modules should all start with at least a few lines of docstring at +their top describing the contents and purpose of the module.

    +

    Example of module docstring (top of file):

    +
    """
+This module handles the creation of `Objects` that
+are useful in the game ...
+
+"""
+
    +
    +

    Sectioning (# title, ## subtile etc) should not be used in +freeform docstrings - this will confuse the sectioning of the auto +documentation page and the auto-api will create this automatically. +Write just the section name bolded on its own line to mark a section. +Beyond sections markdown should be used as needed to format +the text.

    +

    Code examples should use multi-line syntax highlighting +to mark multi-line code blocks, using the “python” identifier. Just +indenting code blocks (common in markdown) will not produce the +desired look.

    +

    When using any code tags (inline or blocks) it’s recommended that you +don’t let the code extend wider than about 70 characters or it will +need to be scrolled horizontally in the wiki (this does not affect any +other text, only code).

    +
    +
    +

    Class docstrings

    +

    The root class docstring should describe the over-arching use of the +class. It should usually not describe the exact call sequence nor list +important methods, this tends to be hard to keep updated as the API +develops. Don’t use section markers (#, ## etc).

    +

    Example of class docstring:

    +
    class MyClass(object):
+    """
+    This class describes the creation of `Objects`. It is useful
+    in many situations, such as ...
+
+    """
+
    +
    +
    +
    +

    Function / method docstrings

    +

    Example of function or method docstring:

    +
    
+def funcname(a, b, c, d=False, **kwargs):
+    """
+    This is a brief introduction to the function/class/method
+
+    Args:
+        a (str): This is a string argument that we can talk about
+            over multiple lines.
+        b (int or str): Another argument.
+        c (list): A list argument.
+        d (bool, optional): An optional keyword argument.
+
+    Keyword Args:
+        test (list): A test keyword.
+
+    Returns:
+        str: The result of the function.
+
+    Raises:
+        RuntimeException: If there is a critical error,
+            this is raised.
+        IOError: This is only raised if there is a
+            problem with the database.
+
+    Notes:
+        This is an example function. If `d=True`, something
+        amazing will happen.
+
+    """
+
    +
    +

    The syntax is very “loose” but the indentation matters. That is, you +should end the block headers (like Args:) with a line break followed by +an indent. When you need to break a line you should start the next line +with another indent. For consistency with the code we recommend all +indents to be 4 spaces wide (no tabs!).

    +

    Here are all the supported block headers:

    +
        """
+    Args
+        argname (freeform type): Description endind with period.
+    Keyword Args:
+        argname (freeform type): Description.
+    Returns/Yields:
+        type: Description.
+    Raises:
+        Exceptiontype: Description.
+    Notes/Note/Examples/Example:
+        Freeform text.
+    """
+
    +
    +

    Parts marked with “freeform” means that you can in principle put any +text there using any formatting except for sections markers (#, ## +etc). You must also keep indentation to mark which block you are part +of. You should normally use the specified format rather than the +freeform counterpart (this will produce nicer output) but in some +cases the freeform may produce a more compact and readable result +(such as when describing an *args or **kwargs statement in general +terms). The first self argument of class methods should never be +documented.

    +

    Note that

    +
    """
+Args:
+    argname (type, optional): Description.
+"""
+
    +
    +

    and

    +
    """
+Keyword Args:
+   sargname (type): Description.
+"""
+
    +
    +

    mean the same thing! Which one is used depends on the function or +method documented, but there are no hard rules; If there is a large +**kwargs block in the function, using the Keyword Args: block may be a +good idea, for a small number of arguments though, just using Args: +and marking keywords as optional will shorten the docstring and make +it easier to read.

    +
    +
    +
    +

    Default Command Docstrings

    +

    These represent a special case since Commands in Evennia use their class +docstrings to represent the in-game help entry for that command.

    +

    All the commands in the default command sets should have their doc-strings +formatted on a similar form. For contribs, this is loosened, but if there is +no particular reason to use a different form, one should aim to use the same +style for contrib-command docstrings as well.

    +
          """
+      Short header
+
+      Usage:
+        key[/switches, if any] <mandatory args> [optional] choice1||choice2||choice3
+
+      Switches:
+        switch1    - description
+        switch2    - description
+
+      Examples:
+        Usage example and output
+
+      Longer documentation detailing the command.
+
+      """
+
    +
    +
      +

    • Two spaces are used for indentation in all default commands.

      • +

    • Square brackets [ ] surround optional, skippable arguments.

      • +

    • Angled brackets < > surround a description of what to write rather than the exact syntax.

      • +

    • Explicit choices are separated by |. To avoid this being parsed as a color code, use || (this +will come out as a single |) or put spaces around the character (“|”) if there’s plenty of room.

      • +

    • The Switches and Examples blocks are optional and based on the Command.

      • +
    +

    Here is the nick command as an example:

    +
          """
+      Define a personal alias/nick
+
+      Usage:
+        nick[/switches] <nickname> = [<string>]
+        alias             ''
+
+      Switches:
+        object   - alias an object
+        account   - alias an account
+        clearall - clear all your aliases
+        list     - show all defined aliases (also "nicks" works)
+
+      Examples:
+        nick hi = say Hello, I'm Sarah!
+        nick/object tom = the tall man
+
+      A 'nick' is a personal shortcut you create for your own use [...]
+
+        """
+
    +
    +

    For commands that require arguments, the policy is for it to return a Usage: +string if the command is entered without any arguments. So for such commands, +the Command body should contain something to the effect of

    +
          if not self.args:
+          self.caller.msg("Usage: nick[/switches] <nickname> = [<string>]")
+          return
+
    +
    +
    +
    +

    Tools for auto-linting

    +
    +

    black

    +

    Automatic pep8 compliant formatting and linting can be performed using the +black formatter:

    +
    black --line-length 100
+
    +
    +
    +
    +

    PyCharm

    +

    The Python IDE Pycharm can auto-generate empty doc-string stubs. The +default is to use reStructuredText form, however. To change to Evennia’s +Google-style docstrings, follow this guide.

    +
    +
    +
    + + +
    +
    +
    + +
    + + + + \ No newline at end of file diff --git a/docs/1.0-dev/Coding/Profiling.html b/docs/1.0-dev/Coding/Profiling.html index b307195544..6c2de18f68 100644 --- a/docs/1.0-dev/Coding/Profiling.html +++ b/docs/1.0-dev/Coding/Profiling.html @@ -17,7 +17,7 @@ - + -

    The setup keyword is used to set up things that should not be included in the -time measurement, like a = [] in the first call.

    -

    By default the timeit function will re-run the given test 1000000 times and -returns the total time to do so (so not the average per test). A hint is to -not use this default for testing something that includes database writes - for -that you may want to use a lower number of repeats (say 100 or 1000) using the -number=100 keyword.

    +

    The setup keyword is used to set up things that should not be included in the time measurement, like a = [] in the first call.

    +

    By default the timeit function will re-run the given test 1000000 times and returns the total time to do so (so not the average per test). A hint is to not use this default for testing something that includes database writes - for that you may want to use a lower number of repeats (say 100 or 1000) using the number=100 keyword.

    +

    In the example above, we see that this number of calls, using a list comprehension is about twice as fast as building a list using .append().

    Using cProfile

    -

    Python comes with its own profiler, named cProfile (this is for cPython, no -tests have been done with pypy at this point). Due to the way Evennia’s -processes are handled, there is no point in using the normal way to start the -profiler (python -m cProfile evennia.py). Instead you start the profiler -through the launcher:

    +

    Python comes with its own profiler, named cProfile (this is for cPython, no tests have been done with pypy at this point). Due to the way Evennia’s processes are handled, there is no point in using the normal way to start the profiler (python -m cProfile evennia.py). Instead you start the profiler through the launcher:

    evennia --profiler start
    -

    This will start Evennia with the Server component running (in daemon mode) under -cProfile. You could instead try --profile with the portal argument to -profile the Portal (you would then need to -start the Server separately).

    -

    Please note that while the profiler is running, your process will use a lot more -memory than usual. Memory usage is even likely to climb over time. So don’t -leave it running perpetually but monitor it carefully (for example using the -top command on Linux or the Task Manager’s memory display on Windows).

    -

    Once you have run the server for a while, you need to stop it so the profiler -can give its report. Do not kill the program from your task manager or by -sending it a kill signal - this will most likely also mess with the profiler. -Instead either use evennia.py stop or (which may be even better), use -@shutdown from inside the game.

    -

    Once the server has fully shut down (this may be a lot slower than usual) you -will find that profiler has created a new file mygame/server/logs/server.prof.

    +

    This will start Evennia with the Server component running (in daemon mode) under cProfile. You could instead try --profile with the portal argument to profile the Portal (you would then need to start the Server separately).

    +

    Please note that while the profiler is running, your process will use a lot more memory than usual. Memory usage is even likely to climb over time. So don’t leave it running perpetually but monitor it carefully (for example using the top command on Linux or the Task Manager’s memory display on Windows).

    +

    Once you have run the server for a while, you need to stop it so the profiler can give its report. Do not kill the program from your task manager or by sending it a kill signal - this will most likely also mess with the profiler. Instead either use evennia.py stop or (which may be even better), use @shutdown from inside the game.

    +

    Once the server has fully shut down (this may be a lot slower than usual) you will find that profiler has created a new file mygame/server/logs/server.prof.

    Analyzing the profile

    -

    The server.prof file is a binary file. There are many ways to analyze and -display its contents, all of which has only been tested in Linux (If you are a -Windows/Mac user, let us know what works).

    -

    You can look at the contents of the profile file with Python’s in-built pstats -module in the evennia shell (it’s recommended you install ipython with pip install ipython in your virtualenv first, for prettier output):

    +

    The server.prof file is a binary file. There are many ways to analyze and display its contents, all of which has only been tested in Linux (If you are a Windows/Mac user, let us know what works).

    +

    You can look at the contents of the profile file with Python’s in-built pstats module in the evennia shell (it’s recommended you install ipython with pip install ipython in your virtualenv first, for prettier output):

    evennia shell
    @@ -199,9 +168,7 @@ module in the evennia shell (it’s recommended you install Python profiling documentation -for more information.

    +

    See the Python profiling documentation for more information.

    You can also visualize the data in various ways.

    • Runsnake visualizes the profile to @@ -214,21 +181,12 @@ KCachegrind work with Python profiles you also need the wrapper script pyprof2calltree via pip whereas KCacheGrind is something you need to get via your package manager or their homepage.

    -

    How to analyze and interpret profiling data is not a trivial issue and depends -on what you are profiling for. Evennia being an asynchronous server can also -confuse profiling. Ask on the mailing list if you need help and be ready to be -able to supply your server.prof file for comparison, along with the exact -conditions under which it was obtained.

    +

    How to analyze and interpret profiling data is not a trivial issue and depends on what you are profiling for. Evennia being an asynchronous server can also confuse profiling. Ask on the mailing list if you need help and be ready to be able to supply your server.prof file for comparison, along with the exact conditions under which it was obtained.

    The Dummyrunner

    -

    It is difficult to test “actual” game performance without having players in your -game. For this reason Evennia comes with the Dummyrunner system. The -Dummyrunner is a stress-testing system: a separate program that logs into your -game with simulated players (aka “bots” or “dummies”). Once connected, these -dummies will semi-randomly perform various tasks from a list of possible -actions. Use Ctrl-C to stop the Dummyrunner.

    +

    It is difficult to test “actual” game performance without having players in your game. For this reason Evennia comes with the Dummyrunner system. The Dummyrunner is a stress-testing system: a separate program that logs into your game with simulated players (aka “bots” or “dummies”). Once connected, these dummies will semi-randomly perform various tasks from a list of possible actions. Use Ctrl-C to stop the Dummyrunner.

    Warning

    You should not run the Dummyrunner on a production database. It
@@ -243,9 +201,7 @@ will spawn many objects and also needs to run with general permissions.
 
     from evennia.server.profiling.settings_mixin import *
 
    
 
    
-
    This will override your settings and disable Evennia’s rate limiters and
-DoS-protections, which would otherwise block mass-connecting clients from
-one IP. Notably, it will also change to a different (faster) password hasher.
    
+
    This will override your settings and disable Evennia’s rate limiters and DoS-protections, which would otherwise block mass-connecting clients from one IP. Notably, it will also change to a different (faster) password hasher.
    
 
 
  • (recommended): Build a new database. If you use default Sqlite3 and want to
 keep your existing database, just rename mygame/server/evennia.db3 to
@@ -260,28 +216,16 @@ be able to connect with an existing user since the password hasher chan
 
    Use Ctrl-C (or Cmd-C) to stop it.
    
 
    • 
 
-
    If you want to see what the dummies are actually doing you can run with a single
-dummy:
    
+
    If you want to see what the dummies are actually doing you can run with a single dummy:
    
 
    evennia --dummyrunner 1
 
    
 
    
-
    The inputs/outputs from the dummy will then be printed. By default the runner
-uses the ‘looker’ profile, which just logs in and sends the ‘look’ command
-over and over. To change the settings, copy the file
-evennia/server/profiling/dummyrunner_settings.py to your mygame/server/conf/
-directory, then add this line to your settings file to use it in the new
-location:
    
+
    The inputs/outputs from the dummy will then be printed. By default the runner uses the ‘looker’ profile, which just logs in and sends the ‘look’ command over and over. To change the settings, copy the file evennia/server/profiling/dummyrunner_settings.py to your mygame/server/conf/ directory, then add this line to your settings file to use it in the new location:
    
 
    DUMMYRUNNER_SETTINGS_MODULE = "server/conf/dummyrunner_settings.py"
 
    
 
    
-
    The dummyrunner settings file is a python code module in its own right - it
-defines the actions available to the dummies. These are just tuples of command
-strings (like “look here”) for the dummy to send to the server along with a
-probability of them happening. The dummyrunner looks for a global variable
-ACTIONS, a list of tuples, where the first two elements define the
-commands for logging in/out of the server.
    
-
    Below is a simplified minimal setup (the default settings file adds a lot more
-functionality and info):
    
+
    The dummyrunner settings file is a python code module in its own right - it defines the actions available to the dummies. These are just tuples of command strings (like “look here”) for the dummy to send to the server along with a probability of them happening. The dummyrunner looks for a global variable ACTIONS, a list of tuples, where the first two elements define the commands for logging in/out of the server.
    
+
    Below is a simplified minimal setup (the default settings file adds a lot more functionality and info):
    
 
    # minimal dummyrunner setup file
 
 # Time between each dummyrunner "tick", in seconds. Each dummy will be called
@@ -325,8 +269,7 @@ functionality and info):
    
 
 
    
 
    
-
    At the bottom of the default file are a few default profiles you can test out
-by just setting the PROFILE variable to one of the options.
    
+
    At the bottom of the default file are a few default profiles you can test out by just setting the PROFILE variable to one of the options.
    
 
    
 
    Dummyrunner hints
    
 
 
   
    Previous topic
    
-  
    Profiling
    
+  
    Coding FAQ
    
   
    Next topic
    
   
    Changelog
    
@@ -258,7 +258,7 @@ package imports from.
    
           next |
         
  • 
-          previous |
    • 
         
  • Evennia 1.0-dev »
    • 
           
  • Coding and development help »
    • 
diff --git a/docs/1.0-dev/Coding/Setting-up-PyCharm.html b/docs/1.0-dev/Coding/Setting-up-PyCharm.html
index 265bfe0103..d12acee2b8 100644
--- a/docs/1.0-dev/Coding/Setting-up-PyCharm.html
+++ b/docs/1.0-dev/Coding/Setting-up-PyCharm.html
@@ -66,7 +66,7 @@
 
  • Setting up the project interpreter
    • 
 
  • Attaching PyCharm debugger to Evennia
    • 
 
  • Setting up an Evennia run configuration
    • 
-
  • Alternative run configuration - utilizing logfiles as source of data
    • 
+
  • Alternative config - utilizing logfiles as source of data
    • 
 
 
 
@@ -109,16 +109,11 @@
             
   
    
 
    Setting up PyCharm with Evennia
    
-
    PyCharm is a Python developer’s IDE from Jetbrains available
-for Windows, Mac and Linux. It is a commercial product but offer free trials, a scaled-down
-community edition and also generous licenses for OSS projects like Evennia.
    
+
    PyCharm is a Python developer’s IDE from Jetbrains available for Windows, Mac and Linux. It is a commercial product but offer free trials, a scaled-down community edition and also generous licenses for OSS projects like Evennia.
    
 
    
-
    This page was originally tested on Windows (so use Windows-style path examples), but should work
-the same for all platforms.
    
+
    This page was originally tested on Windows (so use Windows-style path examples), but should work the same for all platforms.
    
 
    
-
    First, install Evennia on your local machine with [[Getting Started]]. If you’re new to PyCharm,
-loading your project is as easy as selecting the Open option when PyCharm starts, and browsing to
-your game folder (the one created with evennia --init). We refer to it as mygame here.
    
+
    First, install Evennia on your local machine with [[Getting Started]]. If you’re new to PyCharm, loading your project is as easy as selecting the Open option when PyCharm starts, and browsing to your game folder (the one created with evennia --init). We refer to it as mygame here.
    
 
    If you want to be able to examine evennia’s core code or the scripts inside your virtualenv, you’ll
 need to add them to your project too:
    
 
      
@@ -148,63 +143,42 @@ project is already configured in PyCharm.
      
 
      Of course you can attach to the portal process as well.  If you want to debug the Evennia launcher
 or runner for some reason (or just learn how they work!), see Run Configuration below.
      
 
      
-
      NOTE: Whenever you reload Evennia, the old Server process will die and a new one start. So when
-you restart you have to detach from the old and then reattach to the new process that was created.
      
+
      NOTE: Whenever you reload Evennia, the old Server process will die and a new one start. So when you restart you have to detach from the old and then reattach to the new process that was created.
      
 
      
 
      
-
      To make the process less tedious you can apply a filter in settings to show only the server.py
-process in the list. To do that navigate to: Settings/Preferences | Build, Execution, Deployment | Python Debugger and then in Attach to process field put in: twistd.exe" --nodaemon. This is an
-example for windows, I don’t have a working mac/linux box.
-Example process filter configuration
      
+
      To make the process less tedious you can apply a filter in settings to show only the server.py process in the list. To do that navigate to: Settings/Preferences | Build, Execution, Deployment | Python Debugger and then in Attach to process field put in: twistd.exe" --nodaemon. This is an example for windows, I don’t have a working mac/linux box.
      
 
      
+
      Example process filter configuration
      
 
    
 
    
 
    Setting up an Evennia run configuration
    
-
    This configuration allows you to launch Evennia from inside PyCharm. Besides convenience, it also
-allows suspending and debugging the evennia_launcher or evennia_runner at points earlier than you
-could by running them externally and attaching. In fact by the time the server and/or portal are
-running the launcher will have exited already.
    
+
    This configuration allows you to launch Evennia from inside PyCharm. Besides convenience, it also allows suspending and debugging the evennia_launcher or evennia_runner at points earlier than you could by running them externally and attaching. In fact by the time the server and/or portal are running the launcher will have exited already.
    
 
      
 
    1. Go to Run > Edit Configutations...
      2. 
 
    2. Click the plus-symbol to add a new configuration and choose Python
      3. 
-
    3. Add the script: \<yourrepo\>\evenv\Scripts\evennia_launcher.py (substitute your virtualenv if
-it’s not named evenv)
      4. 
+
    4. Add the script: \<yourrepo\>\evenv\Scripts\evennia_launcher.py (substitute your virtualenv if it’s not named evenv)
      5. 
 
    5. Set script parameters to: start -l (-l enables console logging)
      6. 
 
    6. Ensure the chosen interpreter is from your virtualenv
      7. 
 
    7. Set Working directory to your mygame folder (not evenv nor evennia)
      8. 
-
    8. You can refer to the PyCharm documentation for general info, but you’ll want to set at least a
-config name (like “MyMUD start” or similar).
      9. 
+
    9. You can refer to the PyCharm documentation for general info, but you’ll want to set at least a config name (like “MyMUD start” or similar).
      10. 
 
    
-
    Now set up a “stop” configuration by following the same steps as above, but set your Script
-parameters to: stop (and name the configuration appropriately).
    
-
    A dropdown box holding your new configurations should appear next to your PyCharm run button.
-Select MyMUD start and press the debug icon to begin debugging.  Depending on how far you let the
-program run, you may need to run your “MyMUD stop” config to actually stop the server, before you’ll
-be able start it again.
    
+
    Now set up a “stop” configuration by following the same steps as above, but set your Script parameters to: stop (and name the configuration appropriately).
    
+
    A dropdown box holding your new configurations should appear next to your PyCharm run button. Select MyMUD start and press the debug icon to begin debugging.  Depending on how far you let the program run, you may need to run your “MyMUD stop” config to actually stop the server, before you’ll be able start it again.
    
 
    
-
    
-
    Alternative run configuration - utilizing logfiles as source of data
    
-
    This configuration takes a bit different approach as instead of focusing on getting the data back
-through logfiles. Reason for that is this way you can easily separate data streams, for example you
-rarely want to follow both server and portal at the same time, and this will allow it. This will
-also make sure to stop the evennia before starting it, essentially working as reload command (it
-will also include instructions how to disable that part of functionality). We will start by defining
-a configuration that will stop evennia. This assumes that upfire is your pycharm project name, and
-also the game name, hence the upfire/upfire path.
    
+
    
+
    Alternative config - utilizing logfiles as source of data
    
+
    This configuration takes a bit different approach as instead of focusing on getting the data back through logfiles. Reason for that is this way you can easily separate data streams, for example you rarely want to follow both server and portal at the same time, and this will allow it. This will also make sure to stop the evennia before starting it, essentially working as reload command (it will also include instructions how to disable that part of functionality). We will start by defining a configuration that will stop evennia. This assumes that upfire is your pycharm project name, and also the game name, hence the upfire/upfire path.
    
 
      
 
    1. Go to Run > Edit Configutations...\
      2. 
-
    2. Click the plus-symbol to add a new configuration and choose the python interpreter to use (should
-be project default)
      3. 
+
    3. Click the plus-symbol to add a new configuration and choose the python interpreter to use (should be project default)
      4. 
 
    4. Name the configuration as “stop evennia” and fill rest of the fields accordingly to the image:
 Stop run configuration
      5. 
 
    5. Press Apply
      6. 
 
    
-
    Now we will define the start/reload command that will make sure that evennia is not running already,
-and then start the server in one go.
    
+
    Now we will define the start/reload command that will make sure that evennia is not running already, and then start the server in one go.
    
 
      
 
    1. Go to Run > Edit Configutations...\
      2. 
-
    2. Click the plus-symbol to add a new configuration and choose the python interpreter to use (should
-be project default)
      3. 
+
    3. Click the plus-symbol to add a new configuration and choose the python interpreter to use (should be project default)
      4. 
 
    4. Name the configuration as “start evennia” and fill rest of the fields accordingly to the image:
 Start run configuration
      5. 
 
    5. Navigate to the Logs tab and add the log files you would like to follow. The picture shows
diff --git a/docs/1.0-dev/Coding/Unit-Testing.html b/docs/1.0-dev/Coding/Unit-Testing.html
index c35a77d7d2..cb5502af60 100644
--- a/docs/1.0-dev/Coding/Unit-Testing.html
+++ b/docs/1.0-dev/Coding/Unit-Testing.html
@@ -115,17 +115,9 @@
             
   
      
 
      Unit Testing
      
-
      Unit testing means testing components of a program in isolation from each other to make sure every
-part works on its own before using it with others. Extensive testing helps avoid new updates causing
-unexpected side effects as well as alleviates general code rot (a more comprehensive wikipedia
-article on unit testing can be found here).
      
-
      A typical unit test set calls some function or method with a given input, looks at the result and
-makes sure that this result looks as expected. Rather than having lots of stand-alone test programs,
-Evennia makes use of a central test runner. This is a program that gathers all available tests all
-over the Evennia source code (called test suites) and runs them all in one go. Errors and
-tracebacks are reported.
      
-
      By default Evennia only tests itself. But you can also add your own tests to your game code and have
-Evennia run those for you.
      
+
      Unit testing means testing components of a program in isolation from each other to make sure every part works on its own before using it with others. Extensive testing helps avoid new updates causing unexpected side effects as well as alleviates general code rot (a more comprehensive wikipedia article on unit testing can be found here).
      
+
      A typical unit test set calls some function or method with a given input, looks at the result and makes sure that this result looks as expected. Rather than having lots of stand-alone test programs, Evennia makes use of a central test runner. This is a program that gathers all available tests all over the Evennia source code (called test suites) and runs them all in one go. Errors and tracebacks are reported.
      
+
      By default Evennia only tests itself. But you can also add your own tests to your game code and have Evennia run those for you.
      
 
      
 
      Running the Evennia test suite
      
 
      To run the full Evennia test suite, go to your game folder and issue the command
      
diff --git a/docs/1.0-dev/Coding/Updating-Your-Game.html b/docs/1.0-dev/Coding/Updating-Your-Game.html
deleted file mode 100644
index 8a386d23ef..0000000000
--- a/docs/1.0-dev/Coding/Updating-Your-Game.html
+++ /dev/null
@@ -1,273 +0,0 @@
-
-
-
-
-  
-    
-    
-
-    Updating Your Game — Evennia 1.0-dev documentation
-    
-    
-    
-    
-    
-    
-    
-    
-    
-    
-    
-     
-  
-      
-
-    
      
-
-      
      
-      
-        
      
-          
      
-            
-  
      
-
      Updating Your Game
      
-
      Fortunately, it’s extremely easy to keep your Evennia server up-to-date. If you haven’t already, see
-the Getting Started guide and get everything running.
      
-
      
-
      Updating with the latest Evennia code changes
      
-
      Very commonly we make changes to the Evennia code to improve things. There are many ways to get told
-when to update: You can subscribe to the RSS feed or manually check up on the feeds from
-https://www.evennia.com. You can also simply fetch the latest regularly.
      
-
      When you’re wanting to apply updates, simply cd to your cloned evennia root directory and type:
      
-
       git pull
-
      
-
      
-
      assuming you’ve got the command line client. If you’re using a graphical client, you will probably
-want to navigate to the evennia directory and either right click and find your client’s pull
-function, or use one of the menus (if applicable).
      
-
      You can review the latest changes with
      
-
       git log
-
      
-
      
-
      or the equivalent in the graphical client. You can also see the latest changes online
-here.
      
-
      You will always need to do evennia reload (or reload from -in-game) from your game-dir to have
-the new code affect your game. If you want to be really sure you should run a full evennia reboot
-so that both Server and Portal can restart (this will disconnect everyone though, so if you know the
-Portal has had no updates you don’t have to do that).
      
-
      
-
      
-
      Upgrading Evennia dependencies
      
-
      On occasion we update the versions of third-party libraries Evennia depend on (or we may add a new
-dependency). This will be announced on the mailing list/forum. If you run into errors when starting
-Evennia, always make sure you have the latest versions of everything. In some cases, like for
-Django, starting the server may also give warning saying that you are using a working, but too-old
-version that should not be used in production.
      
-
      Upgrading evennia will automatically fetch all the latest packages that it now need. First cd to
-your cloned evennia folder. Make sure your virtualenv is active and use
      
-
      pip install --upgrade -e .
-
      
-
      
-
      Remember the period (.) at the end - that applies the upgrade to the current location (your
-evennia dir).
      
-
      
-
      The -e means that we are linking the evennia sources rather than copying them into the
-environment. This means we can most of the time just update the sources (with git pull) and see
-those changes directly applied to our installed evennia package. Without installing/upgrading the
-package with -e, we would have to remember to upgrade the package every time we downloaded any new
-source-code changes.
      
-
      
-
      Follow the upgrade output to make sure it finishes without errors. To check what packages are
-currently available in your python environment after the upgrade, use
      
-
      pip list
-
      
-
      
-
      This will show you the version of all installed packages. The evennia package will also show the
-location of its source code.
      
-
      
-
      
-
      Migrating the Database Schema
      
-
      Whenever we change the database layout of Evennia upstream (such as when we add new features) you
-will need to migrate your existing database. When this happens it will be clearly noted in the
-git log (it will say something to the effect of “Run migrations”). Database changes will also be
-announced on the Evennia mailing list.
      
-
      When the database schema changes, you just go to your game folder and run
      
-
       evennia migrate
-
      
-
      
-
      
-
      Hint: If the evennia command is not found, you most likely need to activate your
-virtualenv.
      
-
      
-
      
-
      
-
      Resetting your database
      
-
      Should you ever want to start over completely from scratch, there is no need to re-download Evennia
-or anything like that. You just need to clear your database. Once you are done, you just rebuild it
-from scratch by running
      
-
      evennia migrate
-
      
-
      
-
      The first step in wiping your database is to stop Evennia completely with
      
-
      evennia stop
-
      
-
      
-
      If you run the default SQlite3 database (to change this you need to edit your settings.py file),
-the database is actually just a normal file in mygame/server/ called evennia.db3. Simply delete
-that file - that’s it. Now run evennia migrate to recreate a new, fresh one.
      
-
      If you run some other database system you can instead flush the database:
      
-
      evennia flush
-
      
-
      
-
      This will empty the database. However, it will not reset the internal counters of the database, so
-you will start with higher dbref values. If this is okay, this is all you need.
      
-
      Django also offers an easy way to start the database’s own management should we want more direct
-control:
      
-
       evennia dbshell
-
      
-
      
-
      In e.g. MySQL you can then do something like this (assuming your MySQL database is named “Evennia”:
      
-
      mysql> DROP DATABASE Evennia;
-mysql> exit
-
      
-
      
-
      
-
      NOTE: Under Windows OS, in order to access SQLite dbshell you need to download the SQLite
-command-line shell program. It’s a single executable file
-(sqlite3.exe) that you should place in the root of either your MUD folder or Evennia’s (it’s the
-same, in both cases Django will find it).
      
-
      
-
      
-
      
-
      More about schema migrations
      
-
      If and when an Evennia update modifies the database schema (that is, the under-the-hood details as
-to how data is stored in the database), you must update your existing database correspondingly to
-match the change. If you don’t, the updated Evennia will complain that it cannot read the database
-properly. Whereas schema changes should become more and more rare as Evennia matures, it may still
-happen from time to time.
      
-
      One way one could handle this is to apply the changes manually to your database using the database’s
-command line. This often means adding/removing new tables or fields as well as possibly convert
-existing data to match what the new Evennia version expects. It should be quite obvious that this
-quickly becomes cumbersome and error-prone.  If your database doesn’t contain anything critical yet
-it’s probably easiest to simply reset it and start over rather than to bother converting.
      
-
      Enter migrations. Migrations keeps track of changes in the database schema and applies them
-automatically for you. Basically, whenever the schema changes we distribute small files called
-“migrations” with the source. Those tell the system exactly how to implement the change so you don’t
-have to do so manually. When a migration has been added we will tell you so on Evennia’s mailing
-lists and in commit messages -
-you then just run evennia migrate to be up-to-date again.
      
-
      
-
      
-
-
-          
      
-        
      
-      
      
-
-    
      
-    
-    
-  
-
\ No newline at end of file
diff --git a/docs/1.0-dev/Coding/Version-Control.html b/docs/1.0-dev/Coding/Version-Control.html
index cea255a0dd..c51b4ccf5f 100644
--- a/docs/1.0-dev/Coding/Version-Control.html
+++ b/docs/1.0-dev/Coding/Version-Control.html
@@ -6,7 +6,7 @@
     
     
 
-    Version Control — Evennia 1.0-dev documentation
+    Coding using Version Control — Evennia 1.0-dev documentation
     
     
     
@@ -17,7 +17,7 @@
     
     
     
-    
+    
      
   
     
      6. 
         
    6. 
-          next |
      7. 
         
    7. 
           previous |
      8. 
         
    8. Evennia 1.0-dev »
      9. 
           
    9. Coding and development help »
      10. 
-        
    10. Version Control
      11.  
+        
    11. Coding using Version Control
      12.  
       
         
      develop branch
    @@ -62,36 +62,30 @@

    Table of Contents

      -
    • Version Control
        -
      • Setting up Git
          -
        • Step 1: Install Git
          • -
        • Step 2: Define user/e-mail Settings for Git
          • +
        • Coding using Version Control
            +
          • Setting up Git
            • +
          • Common Git commands
            • -
          • Putting your game folder under version control
              -
            • Tracking files
              • -
            • Committing your Code
              • -
            • Changing your mind
              • +
            • Putting your game dir under version control
              • -
            • Forking Evennia @@ -100,8 +94,8 @@

              Coding and development help

              Next topic

              -

              Updating Your Game

              +

              Debugging

                @@ -132,25 +126,16 @@
                -
                -

                Version Control

                -

                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.

                -

                It’s strongly recommended that you put your game code under version control. Version -control is also the way to contribue to Evennia itself.

                -

                For an introduction to the concept, start with the Wikipedia article -here. Evennia uses the version -control system Git and this is what will be covered -henceforth. Note that this page primarily shows commands for Linux, but the -syntax should be the same for Windows and Mac.

                -

                For more help on using Git, please refer to the Official GitHub -documentation.

                +
                +

                Coding using Version Control

                +

                Version control allows you to track changes to your code. You can save ‘snapshots’ of your progress which means you can roll back undo things easily. Version control also allows you to easily back up your code to an online repository such as Github. It also allows you to collaborate with others on the same code without clashing or worry about who changed what.

                + +

                Evennia uses the most commonly used version control system, Git . For additional help on using Git, please refer to the Official GitHub documentation.

                Setting up Git

                -

                You can find expanded instructions for -installation here.

                -
                -

                Step 1: Install Git

                • Fedora Linux

                    yum install git-core
@@ -163,21 +148,16 @@ installation Git for Windows.
                  • -

                • Mac: Mac platforms offer two methods for installation, one via MacPorts, which you can find -out about here, or -you can use the Git OSX Installer.

                  • +

                • Mac: Mac platforms offer two methods for installation, one via MacPorts, which you can find out about here, or you can use the Git OSX Installer.

                -
                -
                -

                Step 2: Define user/e-mail Settings for Git

                -

                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.

                -

                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.

                +

                You can find expanded instructions for installation here.

                + +

                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.

                1. Set the default name for git to use when you commit:

                   git config --global user.name "Your Name Here"
@@ -190,298 +170,290 @@ real, full name online, put a nickname here.
                -
                -
                -
                -

                Putting your game folder under version control

                -

                Note: The game folder’s version control is completely separate from Evennia’s repository.

                +

                To get a running start with Git, here’s a good YouTube talk about it. 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).

                -

                After you have set up your game you will have created a new folder to host your particular game -(let’s call this folder mygame for now).

                -

                This folder is not under version control at this point.

                -
                git init mygame
+
                +
                +

                Common Git commands

                + +

                Git can be controlled via a GUI. But it’s often easier to use the base terminal/console commands, since it makes it clear if something goes wrong.

                +

                All these actions need to be done from inside the git repository .

                +

                Git may seem daunting at first. But when working with git, you’ll be using the same 2-3 commands 99% of the time. And you can make git aliases to have them be even easier to remember.

                +
                +

                git init

                +

                This initializes a folder/directory on your drive as a ‘git repository’

                +
                git init .
                -

                Your mygame folder is now ready for version control! Add all the content and make a first -commit:

                -
                cd mygame
+
                The . means to apply to the current directory. If you are inside mygame, this makes your game dir into a git repository. That’s all there is to it, really. You only need to do this once.
                
+
                +
                +

                git add

                +
                git add <file> 
+
                +
                +

                This tells Git to start to track the file under version control. You need to do this when you create a new file. You can also add all files in your current directory:

                +
                git add . 
+
                +
                +

                Or

                +
                git add *
+
                +
                +

                All files in the current directory are now tracked by Git. You only need to do this once for every file you want to track.

                +
                +
                +

                git commit

                +
                git commit -a -m "This is the initial commit"
+
                +
                +

                This commits your changes. It stores a snapshot of all (-a) your code at the current time, adding a message -m so you know what you did. Later you can check out your code the way it was at a given time. The message is mandatory and you will thank yourself later if write clear and descriptive log messages. If you don’t add -m, a text editor opens for you to write the message instead.

                +

                The git commit is something you’ll be using all the time, so it can be useful to make a git alias for it:

                +
                git config --global alias.cma 'commit -a -m'
+
                +
                +

                After you’ve run this, you can commit much simpler, like this:

                +
                git cma "This is the initial commit"
+
                +
                +

                Much easier to remember!

                +
                +
                +

                git status, git diff and git log

                +
                git status -s 
+
                +
                +

                This gives a short (-s) of the files that changes since your last git commit.

                +
                git diff --word-diff`
+
                +
                +

                This shows exactly what changed in each file since you last made a git commit. The --word-diff option means it will mark if a single word changed on a line.

                +
                git log
+
                +
                +

                This shows the log of all commits done. Each log will show you who made the change, the commit-message and a unique hash (like ba214f12ab12e123...) that uniquely describes that commit.

                +

                You can make the log command more succinct with some more options:

                +
                ls=log --pretty=format:%C(green)%h\ %C(yellow)[%ad]%Cred%d\ %Creset%s%Cblue\ [%an] --decorate --date=relative
+
                +
                +

                This adds coloration and another fancy effects (use git help log to see what they mean).

                +

                Let’s add aliases:

                +
                git config --global alias.st 'status -s'
+git config --global alias.df 'diff --word-diff'
+git config --global alias.ls 'log --pretty=format:%C(green)%h\ %C(yellow)[%ad]%Cred%d\ %Creset%s%Cblue\ [%an] --decorate --date=relative'
+
                +
                +

                You can now use the much shorter

                +
                git st    # short status
+git dif   # diff with word-marking
+git ls    # log with pretty formatting
+
                +
                +

                for these useful functions.

                +
                +
                +

                git branch, checkout and merge

                +

                Git allows you to work with branches. These are separate development paths your code may take, completely separate from each other. You can later merge the code from a branch back into another branch. Evennia’s master and develop branches are examples of this.

                +
                git branch -b branchaname 
+
                +
                +

                This creates a new branch, exactly identical to the branch you were on. It also moves you to that branch.

                +
                git branch -D branchname 
+
                +
                +

                Deletes a branch.

                +
                git branch 
+
                +
                +

                Shows all your branches, marking which one you are currently on.

                +
                git checkout branchname 
+
                +
                +

                This checks out another branch. As long as you are in a branch all git commits will commit the code to that branch only.

                +
                git checkout .
+
                +
                +

                This checks out your current branch and has the effect of throwing away all your changes since your last commit. This is like undoing what you did since the last save point.

                +
                git checkout b2342bc21c124
+
                +
                +

                This checks out a particular commit, identified by the hash you find with git log. This open a ‘temporary branch’ where the code is as it was when you made this commit. As an example, you can use this to check where a bug was introduced. Check out an existing branch to go back to your normal timeline, or use git branch -b newbranch to break this code off into a new branch you can continue working from.

                +
                git merge branchname
+
                +
                +

                This merges the code from branchname into the branch you are currently in. Doing so may lead to merge conflicts if the same code changed in different ways in the two branches. See how to resolve merge conflicts in git for more help.

                +
                +
                +

                git glone, git push and git pull

                +

                All of these other commands have dealt with code only sitting in your local repository-folder. These commands instead allows you to exchange code with a remote repository - usually one that is online (like on github).

                +
                +

                How you actually set up a remote repository is described in the next section.

                +
                +
                git clone repository/path
+
                +
                +

                This copies the remote repository to your current location. If you used the Git installation instructions to install Evennia, this is what you used to get your local copy of the Evennia repository.

                +
                git pull
+
                +
                +

                Once you cloned or otherwise set up a remote repository, using git pull will re-sync the remote with what you have locally. If what you download clashes with local changes, git will force you to git commit your changes before you can continue with git pull.

                +
                git push 
+
                +
                +

                This uploads your local changes of your current branch to the same-named branch on the remote repository. To be able to do this you must have write-permissions to the remote repository.

                +
                +
                +

                Other git commands

                +

                There are many other git commands. Read up on them online:

                +
                git reflog 
+
                +
                +

                Shows hashes of individual git actions. This allows you to go back in the git event history itself.

                +
                git reset 
+
                +
                +

                Force reset a branch to an earlier commit. This could throw away some history, so be careful.

                +
                git grep -n -I -i <query>
+
                +
                +

                Quickly search for a phrase/text in all files tracked by git. Very useful to quickly find where things are. Set up an alias git gr with

                +
                git config --global alias.gr 'grep -n -I -i'
+
                +
                +
                +
                +
                +

                Putting your game dir under version control

                +

                This makes use of the git commands listed in the previous section.

                + +
                cd mygame 
+git init . 
 git add *
 git commit -a -m "Initial commit"
                -

                In turn these commands:

                -
                  -

                • Move us into the mygame folder

                  • -

                • Tell git that everything * means everything) in this folder should be put -under version control.

                  • -

                • Commit all (-a) those newly added files to git and add a message -m so you remember -what you did at this point. Doing a commit is like saving a snapshot of the -current state of everything.

                  • -
                -

                Read on for details!

                -
                -

                Tracking files

                -

                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.

                -
                git add <filename>
-
                -
                -

                You only need to do this once per file.

                -
                git status
-
                -
                -

                will show if you have any modified, added or otherwise changed files. Some -files, like database files, logs and temporary PID files are usually not -tracked in version control. These should either not show up or have a question -mark in front of them.

                -
                -

                Note

                -

                You will notice that some files are not covered by your git version control, -notably your settings file (mygame/server/conf/settings.py) and your sqlite3 -database file mygame/server/evennia.db3. What is auto-ignored by is controlled -by the hidden file mygame/.gitignore. 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 .gitignore.

                -
                +

                Your game-dir is now tracked by git.

                +

                You will notice that some files are not covered by your git version control, notably your secret-settings file (mygame/server/conf/secret_settings.py) and your sqlite3 database file mygame/server/evennia.db3. This is intentional and controlled from the file mygame/.gitignore.

                Warning

                You should never put your sqlite3 database file into git by removing its entry in .gitignore. 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.

                +lies madness and a good chance you’ll confuse yourself. Make one mistake or local change and after a few commits and reverts you will have lost track of what is in your database or not. If you want to backup your SQlite3 database, do so by simply copying the database file to a safe location.

                -
                -
                -

                Committing your Code

                -

                Committing your code 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. Or just wiping everything since the last commit, if you did something -stupid.

                -

                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

                -
                git commit --all
-
                -
                -

                Also -a works. This will open a text editor for you to describe your change. -Be brief but informative in your message - you’ll appreciate it later. When you -save and close the editor, the commit will be saved. You can create the message -directly with

                -
                git commit -a -m "This fixes a bug in the combat code."
-
                -
                -
                -
                -

                Changing your mind

                -

                If you have non-committed changes that you realize you want to throw away, you -‘check out’ the file you want - this will re-load it from the last committed -state:

                -
                git checkout <file_to_revert>
-git checkout foo/bar/dummy.py
-
                -
                -

                If you want to revert all changes you did since last commit, do

                -
                git checkout .
-
                -
                -

                (that is, add a single . at the end).

                -

                Pushing your code online

                -

                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.

                -
                -

                Important

                -

                Just to avoid confusion, be aware that Github’s documentation has changed to -calling the primary branch ‘main’ rather than ‘master’. While Evennia still -uses ‘master’ branch (and this is what we refer to below), you can use either -name for your personal primary branch - they are equivalent.

                +

                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 git push it to your own remote repository on GitHub. So for this you need a (free) Github account.

                +

                If you don’t want your code to be publicly visible, Github also allows you set up a private repository, only visible to you.

                +
                +

                Note

                +

                Github’s defaults have changed to calling the primary branch ‘main’ rather than ‘master’. While Evennia still uses ‘master’ branch (and this is what we refer to below), you can use either name for your personal primary branch - they are equivalent.

                -
                  -

                1. Make sure you have your game directory setup under git version control as -described in the previous section. Make sure to commit any changes you did.

                  2. -

                2. Create a new, empty repository on Github. Github explains how -here (do not “Initialize -the repository with a README” or else you’ll create unrelated histories).

                  3. -

                3. From your local game dir, do git remote add origin <github URL> where -<github URL> is the URL to your online repo. This tells your game dir that -it should be pushing to the remote online dir.

                  4. -

                4. git remote -v to verify the online dir.

                  5. -

                5. git push origin master (or git push origin main) now pushes your game dir -online so you can see it on github.com.

                  6. -
                -

                You can commit your work locally (git commit --all -m "Make a change that ...") as many times as you want. When you want to push those changes to your -online repo, you do git push. You can also git clone <url_to_online_repo> -from your online repo to somewhere else (like your production server) and -henceforth do git pull to update that to the latest thing you pushed.

                -

                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.

                -
                -
                -
                -

                Forking Evennia

                -

                This helps you set up an online fork of the main Evennia repository so you can -easily commit fixes and help with upstream development. You can do this step -also if you didn’t put your game dir under version control like in the -previous section - the evennia repo and your game dir repo are completely -separate.

                -
                -

                Step 1: Fork the evennia/master repository

                -
                -

                Before proceeding with the following step, make sure you have registered and -created an account on GitHub.com. 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.

                -
                -

                A fork is a clone of the master repository that you can make your own commits -and changes to. At the top of this page, -click the “Fork” button, as it appears below. -

                -
                -
                -

                Step 2: Clone your online fork of Evennia

                -

                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:

                -
                git clone https://github.com/yourusername/evennia.git
+
                Create a new, empty repository on Github. Github explains how here . Don’t allow it to add a README, license etc, that will just clash with what we upload later.
                
+
+
                Make sure you are in your local game dir (previously initialized as a git repo).
                
+
                git remote add origin <github URL>
 
                
 
                
-
                This will download your fork to your computer. It creates a new folder
-evennia/ at your current location.
                
+
                This tells Git that there is a remote repository at <github URL>. See the  github docs as to which URL to use. Verify that the remote works with git remote -v
                
+
                Now we push to the remote (labeled ‘origin’ which is the default):
                
+
                git push
+
                
+
                
+
                Depending on how you set up your authentication with github, you may be asked to enter your github username and password. If you set up SSH authentication, this command will just work.
                
+
                You use git push to upload your local changes so the remote repository is in sync with your local one. If you edited a file online using the Github editor (or a collaborator pushed code), you use git pull to sync in the other direction.
                -
                -

                Step 3: Configure remotes

                -

                Your Evennia-fork is now separate from upstream, ‘official’ Evennia. You will -want to set it up so that you can easily sync our updates and changes to your -fork.

                -

                We do this by setting up a new remote. We actually already have one remote, -that is our own github form of Evennia. This got created when you cloned the -repo and defaults to being called origin.

                -

                We will now create a new remote called upstream.

                +
                +
                +

                Contributing to Evennia

                +

                If you want to help contributing to Evennia you must do so by forking - making your own remote copy of the Evennia repository on Github. So for this, you need a (free) Github account. Doing so is a completely separate process from putting your game dir under version control (which you should also do!).

                +

                At the top right of the evennia github page, click the “Fork” button:

                +

                fork button

                +

                This will create a new online fork Evennia under your github account.

                +

                The fork only exists online as of yet. In a terminal, cd to the folder you wish to develop in. This folder should not be your game dir, nor the place you cloned Evennia into if you used the Git installation.

                +

                From this directory run the following command:

                +
                git clone https://github.com/yourusername/evennia.git evennia
+
                +
                +

                This will download your fork to your computer. It creates a new folder evennia/ at your current location. If you installed Evennia using the Git installation, this folder will be identical in content to the evennia folder you cloned during that installation. The difference is that this repo is connected to your remote fork and not to the ‘original’ upstream Evennia.

                +

                When we cloned our fork, git automatically set up a ‘remote repository’ labeled origin pointing to it. So if we do git pull and git push, we’ll push to our fork.

                +

                We now want to add a second remote repository linked to the original Evennia repo. We will label this remote repository upstream:

                cd evennia
 git remote add upstream https://github.com/evennia/evennia.git
                -

                This adds a remote to the main evennia repo.

                -

                If you also want to access Evennia’s develop branch (the bleeding edge -development) do the following:

                +

                If you also want to access Evennia’s develop branch (the bleeding edge development) do the following:

                git fetch upstream develop
 git checkout develop
                -

                Use -git checkout master -git checkout develop

                -

                to switch between the branches. If you want to contribute a fix, ask first which -branch to use. Normally master is for bug fixes and develop is for new -features, but late in the development of a new Evennia version, all changes -often go into develop.

                -
                -
                -
                -

                Working with your Evennia fork

                -

                Branches are stand-alone editions of the same code. You make a commit to a -branch. Switching to a branch will change the code on-disk. You can easily -make a new branch off a parent branch, and then merge it back into the same -branch later (or throw it away). This is a very common way to work on new -features in safety and isolation.

                -
                -

                Updating to latest Evennia

                -

                When Evennia’s official repository updates, first make sure to commit all your -changes to your branch and then checkout the “clean” master branch:

                +

                Use

                git checkout master
-git pull upstream master
+git checkout develop
                -

                Or, if you are working against Evennia’s development branch:

                -
                git checkout develop
-git pull upstream develop
+
                to switch between the branches.
                
+
                To pull the latest from upstream Evennia, just checkout the branch you want and do
                
+
                git pull upstream
 
                
 
                
-
                The pull command will fetch all the changes from the “upstream” remote and
-merge it into your local master/develop branch. It should now be a perfect copy
-of the latest Evennia changes.
                
-
                -
                -

                Making changes

                -

                As a rule of thumb you should never work directly in Evennia’s master or -develop branches. Instead you make a new branch off the branch you want -and change that.

                + +
                +

                Fixing an Evennia bug or feature

                +

                This should be done in your fork of Evennia. You should always do this in a separate git branch based off the Evennia branch you want to improve.

                git checkout master (or develop)
-check checkout -b strange_bug
+git branch - b myfixbranch
                -

                You now have a new branch strange_bug that is an exact replica of the branch you -had checked out when you created it. Here you can now make your own -modifications.

                -
                git branches
-
                -
                -

                will show you which branches are available and which one you are currently -using. Use git checkout <branch> to move between them, but remember to commit -your changes before you do.

                -

                You often want to make sure also your work-branch has the latest upstream -changes. To do this, you need to first update your copy of the -master/develop branch and then merge those changes into your work branch. -Make sure you have committed everything first!

                -
                git commit -a -m "My latest changes ..."   # on your strange_bug branch
-git checkout master (or develop)
-git pull upstream develop
-git checkout strange_bug
+
                Now fix whatever needs fixing. Abide by the Evennia code style. You can git commit commit your changes along the way as normal.
                
+
                Upstream Evennia is not standing still, so you want to make sure that your work is up-to-date with upstream changes. Make sure to first commit your myfixbranch changes, then
                
+
                git checkout master (or develop)
+git pull upstream 
+git checkout myfixbranch
 git merge master (or develop)
 
                
 
                
-
                If everything went well, your strange_bug branch will now have the latest version
-of Evennia merged with whatever changes you have done.
                
-
                Now work away on your code and commit with reasonable commit messages
                
-
                git commit -a -m "Fixed the issue in ..."
-git commit -a -m "Adding unit tests. This resolves #123."
-
                
-
                
-
                Use
                
-
                git diff
-
                
-
                
-
                to see what you changed since last commit, and
                
-
                git log
-
                
-
                
-
                to see past commits (including those made by Evennia upstream, remember that
-your branch is a copy of the upstream one, including its history!)
                
-
                -
                -
                -

                Sharing your Evennia fixes on Github

                -

                Up to this point your strange_bug 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:

                -
                git push -u origin strange_bug
-
                -
                -

                You only need to do this once, the -u makes this the default push-location. In -the future, you can just push things online like this:

                +

                Up to this point your myfixbranch branch only exists on your local computer. No +one else can see it.

                git push
                +

                This will automatically create a matching myfixbranch in your forked version of Evennia and push to it. On github you will be able to see appear it in the branches dropdown. You can keep pushing to your remote myfixbranch as much as you like.

                +

                Once you feel you have something to share, you need to create a pull request (PR): +This is a formal request for upstream Evennia to adopt and pull your code into the main repository.

                +
                  +

                1. Click New pull request

                  2. +

                2. Choose compare across forks

                  3. +

                3. Select your fork from dropdown list of head repository repos. Pick the right branch to compare.

                  4. +

                4. On the Evennia side (to the left) make sure to pick the right base branch: If you want to contribute a change to the develop branch, you must pick develop as the base.

                  5. +

                5. Then click Create pull request and fill in as much information as you can in the form.

                  6. +

                6. Optional: Once you saved your PR, you can go into your code (on github) and add some per-line comments; this can help reviewers by explaining complex code or decisions you made.

                  7. +
                +

                Now you just need to wait for your code to be reviewed. Expect to get feedback and be asked to make changes, add more documentation etc. Getting as PR merged can take a few iterations.

                + +
                +
                -

                Troubleshooting

                -

                If you hadn’t setup a public key on GitHub or aren’t asked for a -username/password, you might get an error 403: Forbidden Access at this stage. -In that case, some users have reported that the workaround is to create a file -.netrc under your home directory and add your github credentials there:

                +

                Troubleshooting

                +
                +

                Getting 403: Forbidden access

                +

                Some users have experienced this on git push to their remote repository. They are not asked for username/password (and don’t have a ssh key set up).

                +

                Some users have reported that the workaround is to create a file .netrc under your home directory and add your github credentials there:

                machine github.com
 login <my_github_username>
 password <my_github_password>
@@ -489,98 +461,6 @@ password <my_github_password>
                -
                -

                Making an Evennia Pull Request

                -

                If you think that the fixes you did in your strange_bug branch should be a -part of the regular Evennia, you should create a Pull Request (PR). This is a -call for the Evennia maintainer to pull your change into an upstream branch.

                -
                -

                It is wise to make separate branches for every fix or series of fixes you want -to contribute.

                -
                -

                Assuming you have followed the instructions above and have pushed your changes -online, create a pull request and -follow the instructions. Make sure to specifically select your strange_bug -branch to be the source of the merge and use the branch you based that branch -off (master or develop) as the target.

                -

                Evennia developers will then be able to examine your request and merge it if -it’s deemed suitable. They may also come back with feedback and request you do -some changes.

                -

                Once approved and merged, your change will now be available in the upstream -branch:

                -
                git checkout master (or develope)
-git pull upstream master (or develop)
-
                -
                -

                Since your changes are now in upstream, your local strange_bug branch is now -superfluous and should be deleted:

                -
                git branch -D strange_bug
-
                -
                -

                You can also safely delete your online strange_bug branch in your fork -(you can do this from the PR page on github).

                -
                -
                -

                GIT tips and tricks

                -

                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:

                -
                # git st
-# - view brief status info
-git config --global alias.st 'status -s'
-
                -
                -

                Above, you only need to ever enter the git config ... command once - you have then added the new -alias. Afterwards, just do git st to get status info. All the examples below follow the same -template.

                -
                # git cl
-# - clone a repository
-git config --global alias.cl clone
-
                -
                -
                # git cma "commit message"
-# - commit all changes without opening editor for message
-git config --global alias.cma 'commit -a -m'
-
                -
                -
                # git ca
-# - amend text to your latest commit message
-git config --global alias.ca 'commit --amend'
-
                -
                -
                # git fl
-# - file log; shows diffs of files in latest commits
-git config --global alias.fl 'log -u'
-
                -
                -
                # git co [branchname]
-# - checkout
-git config --global alias.co checkout
-
                -
                -
                # git br <branchname>
-# - create branch
-git config --global alias.br branch
-
                -
                -
                # git ls
-# - view log tree
-git config --global alias.ls 'log --pretty=format:"%C(green)%h\ %C(yellow)[%ad]%Cred%d\
-%Creset%s%Cblue\ [%cn]" --decorate --date=relative --graph'
-
                -
                -
                # git diff
-# - show current uncommitted changes
-git config --global alias.diff 'diff --word-diff'
-
                -
                -
                # git grep <query>
-# - search (grep) codebase for a search criterion
-git config --global alias.grep 'grep -Ii'
-
                -
                -

                To get a further feel for GIT there is also a good YouTube talk about it - 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).

                -
                @@ -599,14 +479,14 @@ template.

                modules |
              • - next |
              • previous |
              • Evennia 1.0-dev »
              • Coding and development help »
                • -
              • Version Control
                • +
              • Coding using Version Control
              develop branch
              diff --git a/docs/1.0-dev/Components/Connection-Screen.html b/docs/1.0-dev/Components/Connection-Screen.html index d58c6d8202..f4e13702ad 100644 --- a/docs/1.0-dev/Components/Connection-Screen.html +++ b/docs/1.0-dev/Components/Connection-Screen.html @@ -124,7 +124,7 @@ your game. This is simple:

              1. Edit mygame/server/conf/connection_screens.py.

                2. -

              2. Reload Evennia.

                3. +

              3. Reload Evennia.

              Evennia will look into this module and locate all globally defined strings in it. These strings are used as the text in your connection screen and are shown to the user at startup. If more than diff --git a/docs/1.0-dev/Components/Portal-And-Server.html b/docs/1.0-dev/Components/Portal-And-Server.html index f3729acb7b..7108075523 100644 --- a/docs/1.0-dev/Components/Portal-And-Server.html +++ b/docs/1.0-dev/Components/Portal-And-Server.html @@ -99,7 +99,7 @@

              Portal And Server

              Evennia consists of two processes, known as Portal and Server. They can be controlled from -inside the game or from the command line as described here.

              +inside the game or from the command line as described here.

              If you are new to the concept, the main purpose of separating the two is to have accounts connect to the Portal but keep the MUD running on the Server. This way one can restart/reload the game (the Server part) without Accounts getting disconnected.

              ![portal and server layout](https://474a3b9f-a-62cb3a1a-s- sites.googlegroups.com/site/evenniaserver/file-cabinet/evennia_server_portal.png)

              The Server and Portal are glued together via an AMP (Asynchronous Messaging Protocol) connection. This allows the two programs to communicate seamlessly.

              diff --git a/docs/1.0-dev/Concepts/Concepts-Overview.html b/docs/1.0-dev/Concepts/Concepts-Overview.html index 92a28ede21..5e1d32e8a7 100644 --- a/docs/1.0-dev/Concepts/Concepts-Overview.html +++ b/docs/1.0-dev/Concepts/Concepts-Overview.html @@ -131,10 +131,7 @@
            • Your Solution
            • -
          • Using MUX as a Standard -
            • +
          • Using MUX as a Standard
          • Messagepath
            • The ingoing message path
            • The outgoing message path
              • diff --git a/docs/1.0-dev/Concepts/Using-MUX-as-a-Standard.html b/docs/1.0-dev/Concepts/Using-MUX-as-a-Standard.html index 5332443b85..4b1c7a5904 100644 --- a/docs/1.0-dev/Concepts/Using-MUX-as-a-Standard.html +++ b/docs/1.0-dev/Concepts/Using-MUX-as-a-Standard.html @@ -60,14 +60,6 @@
    -

    Table of Contents

    - -

    Previous topic

    Soft Code

    @@ -113,69 +105,6 @@ deliberately lacks an online softcode language (a policy explained on our ). Evennia also does not shy from using its own syntax when deemed appropriate: the MUX syntax has grown organically over a long time and is, frankly, rather arcane in places. All in all the default command syntax should at most be referred to as “MUX-like” or “MUX-inspired”.

    -
    -

    Documentation policy

    -

    All the commands in the default command sets should have their doc-strings formatted on a similar -form:

    -
          """
-      Short header
-    
-      Usage:
-        key[/switches, if any] <mandatory args> [optional] choice1||choice2||choice3
-    
-      Switches:
-        switch1    - description
-        switch2    - description
-    
-      Examples:
-        usage example and output
-    
-      Longer documentation detailing the command.
-    
-      """
-
    -
    -
      -

    • Two spaces are used for indentation in all default commands.

      • -

    • Square brackets [ ] surround optional, skippable arguments.

      • -

    • Angled brackets < > surround a description of what to write rather than the exact syntax.

      • -

    • *Explicit choices are separated by |. To avoid this being parsed as a color code, use || (this -will come out as a single |) or put spaces around the character (“|”) if there’s plenty of -room.

      • -

    • The Switches and Examples blocks are optional based on the Command.

      • -
    -

    Here is the nick command as an example:

    -
          """
-      Define a personal alias/nick
-    
-      Usage:
-        nick[/switches] <nickname> = [<string>]
-        alias             ''
-    
-      Switches:
-        object   - alias an object
-        account   - alias an account
-        clearall - clear all your aliases
-        list     - show all defined aliases (also "nicks" works)
-    
-      Examples:
-        nick hi = say Hello, I'm Sarah!
-        nick/object tom = the tall man
-    
-      A 'nick' is a personal shortcut you create for your own use [...]
-    
-        """
-
    -
    -

    For commands that require arguments, the policy is for it to return a Usage: string if the -command is entered without any arguments. So for such commands, the Command body should contain -something to the effect of

    -
          if not self.args:
-          self.caller.msg("Usage: nick[/switches] <nickname> = [<string>]")
-          return
-
    -
    -
    diff --git a/docs/1.0-dev/Contribs/Contrib-AWSStorage.html b/docs/1.0-dev/Contribs/Contrib-AWSStorage.html index 9428c97b26..d1bdcd9ec9 100644 --- a/docs/1.0-dev/Contribs/Contrib-AWSStorage.html +++ b/docs/1.0-dev/Contribs/Contrib-AWSStorage.html @@ -18,7 +18,7 @@ - +