diff --git a/.github/ISSUE_TEMPLATE/bug-report-develop.md b/.github/ISSUE_TEMPLATE/bug-report-develop.md deleted file mode 100644 index 2bcdda7d65..0000000000 --- a/.github/ISSUE_TEMPLATE/bug-report-develop.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -name: Bug report (branch-develop) -about: Use this to report errors in the Evennia `develop` branch -title: "[BUG - Develop] (Enter a brief description here)" -labels: bug, branch-develop -assignees: '' - ---- - -#### Describe the bug - - -#### To Reproduce -Steps to reproduce the behavior: -1. -2. -3. -4. See error - -#### Expected behavior - - -#### Develop-branch commit - - -#### Additional context - diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md index 472cf50abb..43101a5823 100644 --- a/.github/ISSUE_TEMPLATE/bug-report.md +++ b/.github/ISSUE_TEMPLATE/bug-report.md @@ -2,26 +2,26 @@ name: Bug report about: Create a report to help us improve title: "[BUG] (Enter a brief description here)" -labels: bug +labels: bug, needs-triage assignees: '' --- #### Describe the bug - + #### To Reproduce Steps to reproduce the behavior: -1. +1. 2. 3. 4. See error #### Expected behavior - + #### Environment, Evennia version, OS etc - + #### Additional context - + diff --git a/.github/ISSUE_TEMPLATE/documentation-issue.md b/.github/ISSUE_TEMPLATE/documentation-issue.md index d03d696e9e..753da92f2e 100644 --- a/.github/ISSUE_TEMPLATE/documentation-issue.md +++ b/.github/ISSUE_TEMPLATE/documentation-issue.md @@ -7,11 +7,11 @@ assignees: '' --- -#### Documentation page name and link - +#### Existing page / new + -#### Reason for issue - +#### Documentation issue + #### Suggested change diff --git a/.github/ISSUE_TEMPLATE/feature-request.md b/.github/ISSUE_TEMPLATE/feature-request.md index fe1022e728..06bbebc0a3 100644 --- a/.github/ISSUE_TEMPLATE/feature-request.md +++ b/.github/ISSUE_TEMPLATE/feature-request.md @@ -2,19 +2,19 @@ name: Feature request about: Suggest an idea for this project title: "[Feature Request] Enter a brief description here" -labels: feature-request +labels: feature-request, needs-triage assignees: '' --- #### Is your feature request related to a problem? Please describe. - + #### Describe the solution you'd like - + -#### Alternatives you've considered - +#### Describe alternatives you've considered + #### Additional context - + diff --git a/.github/actions/setup-database/action.yml b/.github/actions/setup-database/action.yml new file mode 100644 index 0000000000..2950019a78 --- /dev/null +++ b/.github/actions/setup-database/action.yml @@ -0,0 +1,86 @@ +# evennia/setup-database + +# Use this action in a workflow for when you need to do initialization of database services +# (such as with PostgreSQL and MySQL) before you initiate unit tests that will employ that +# database service. + +# NOTE: This action was intended for use with the core Evennia workflows ONLY. + +name: Set up Evennia database service +author: dvoraen +description: "Activates the database server for the passed in service and ensures it's ready for use." + +inputs: + database: + description: "Database service being initialized." + required: true + +runs: + using: "composite" + + steps: + - name: Set up PostgreSQL server + if: ${{ inputs.database == 'postgresql' }} + uses: harmon758/postgresql-action@v1 + with: + postgresql version: "11" + postgresql db: "evennia" + postgresql user: "evennia" + postgresql password: "password" + + - name: Wait for PostgreSQL to activate + if: ${{ inputs.database == 'postgresql' }} + run: | + while ! pg_isready -h 127.0.0.1 -q >/dev/null 2>&1 + do + sleep 1 + echo -n . + done + echo + shell: bash + + - name: Set up MySQL server + if: ${{ inputs.database == 'mysql' }} + uses: mirromutth/mysql-action@v1.1 + with: + host port: 3306 + # character set server: "utf8mb4" + # collation server: "utf8mb4_unicode_ci" + character set server: "utf8" + collation server: "utf8_general_ci" + mysql database: "evennia" + mysql user: "evennia" + mysql password: "password" + mysql root password: root_password + + - name: Wait for MySQL to activate + if: ${{ inputs.database == 'mysql' }} + run: | + while ! mysqladmin ping -h 127.0.0.1 -u root -proot_password -s >/dev/null 2>&1 + do + sleep 1 + echo -n . + done + echo + shell: bash + + - name: Set up MySQL Privileges + if: ${{ inputs.database == 'mysql' }} + run: | + cat < " yn + +case $yn in + [nN] ) echo "Aborting."; + exit;; + * ) echo "Starting release ...";; +esac + +# clean and build the pypi distribution +echo "Preparing and Building PyPi package ..." +rm -Rf dist/ +git clean -xdf +pip install --upgrade pip +pip install build twine +python -m build --sdist --wheel --outdir dist/ . + +echo "Uploading PyPi package (requires credentials) ..." + +python -m twine upload dist/* + +# tag the latest git commit +echo "Creating and pushing release tag tag v$VERSION ..." +git tag -a v$VERSION -m "Evennia release v$VERSION" +git push --tags + +echo "... Release complete." +echo "" +echo "Post-release actions:" +echo " 1. Make sure to push all commits." +echo " 2. Update github discussions to report on release." +echo " 2. Make post in discord #announcements channel pointing to discussion post." +echo " 3. Any other announcements as needed." diff --git a/CHANGELOG.md b/CHANGELOG.md index 5aff3dc50c..ade0a481ea 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,9 +1,32 @@ # Changelog -## Evennia 1.0-dev (2019-) (WIP) +### Evennia 1.0 + +2019-2022 + +_Changed to using `main` branch to follow github standard. Old `master` branch remains +for now but will not be used anymore, so as to not break installs during transition._ + +Increase requirements: Django 4.1+, Twisted 22.10+ Python 3.10, 3.11. PostgreSQL 11+. - New `drop:holds()` lock default to limit dropping nonsensical things. Access check defaults to True for backwards-compatibility in 0.9, will be False in 1.0 +- REST API allows you external access to db objects through HTTP requests (Tehom) +- `Object.normalize_name` and `.validate_name` added to (by default) enforce latinify + on character name and avoid potential exploits using clever Unicode chars (trhr) +- New `utils.format_grid` for easily displaying long lists of items in a block. +- Using `lunr` search indexing for better `help` matching and suggestions. Also improve + the main help command's default listing output. +- Added `content_types` indexing to DefaultObject's ContentsHandler. (volund) +- Made most of the networking classes such as Protocols and the SessionHandlers + replaceable via `settings.py` for modding enthusiasts. (volund) +- The `initial_setup.py` file can now be substituted in `settings.py` to customize + initial game database state. (volund) +- Added new Traits contrib, converted and expanded from Ainneve project. +- Added new `requirements_extra.txt` file for easily getting all optional dependencies. +- Change default multi-match syntax from 1-obj, 2-obj to obj-1, obj-2. +- Make `object.search` support 'stacks=0' keyword - if ``>0``, the method will return + N identical matches instead of triggering a multi-match error. - Add `tags.has()` method for checking if an object has a tag or tags (PR by ChrisLR) - Make IP throttle use Django-based cache system for optional persistence (PR by strikaco) - Renamed Tutorial classes "Weapon" and "WeaponRack" to "TutorialWeapon" and @@ -15,16 +38,201 @@ - Fix typo in UnixCommand contrib, where `help` was given as `--hel`. - Latin (la) i18n translation (jamalainm) - Made the `evennia` dir possible to use without gamedir for purpose of doc generation. +- Make Scripts' timer component independent from script object deletion; can now start/stop + timer without deleting Script. The `.persistent` flag now only controls if timer survives + reload - Script has to be removed with `.delete()` like other typeclassed entities. +- Add `utils.repeat` and `utils.unrepeat` as shortcuts to TickerHandler add/remove, similar + to how `utils.delay` is a shortcut for TaskHandler add. +- Refactor the classic `red_button` example to use `utils.delay/repeat` and modern recommended + code style and paradigms instead of relying on `Scripts` for everything. +- Expand `CommandTest` with ability to check multiple message-receivers; inspired by PR by + user davewiththenicehat. Also add new doc string. +- Add central `FuncParser` as a much more powerful replacement for the old `parse_inlinefunc` + function. +- Attribute/NAttribute got a homogenous representation, using intefaces, both + `AttributeHandler` and `NAttributeHandler` has same api now. +- Add `evennia/utils/verb_conjugation` for automatic verb conjugation (English only). This + is useful for implementing actor-stance emoting for sending a string to different targets. +- New version of Italian translation (rpolve) +- `utils.evmenu.ask_yes_no` is a helper function that makes it easy to ask a yes/no question + to the user and respond to their input. This complements the existing `get_input` helper. +- Allow sending messages with `page/tell` without a `=` if target name contains no spaces. +- New FileHelpStorage system allows adding help entries via external files. +- `sethelp` command now warns if shadowing other help-types when creating a new + entry. +- Help command now uses `view` lock to determine if cmd/entry shows in index and + `read` lock to determine if it can be read. It used to be `view` in the role + of the latter. Migration swaps these around. +- In modules given by `settings.PROTOTYPE_MODULES`, spawner will now first look for a global + list `PROTOTYPE_LIST` of dicts before loading all dicts in the module as prototypes. +- New Channel-System using the `channel` command and nicks. Removed the `ChannelHandler` and the + concept of a dynamically created `ChannelCmdSet`. +- Add `Msg.db_receiver_external` field to allowe external, string-id message-receivers. +- Renamed `app.css` to `website.css` for consistency. Removed old prosimii-css files. +- Remove `mygame/web/static_overrides` and -`template_overrides`, reorganize website/admin/client/api + into a more consistent structure for overriding. Expanded webpage documentation considerably. +- REST API list-view was shortened (#2401). New CSS/HTML. Add ReDoc for API autodoc page. +- Update and fix dummyrunner with cleaner code and setup. +- Made `iter_to_str` format prettier strings, using Oxford comma. +- Added an MXP anchor tag to also support clickable web links. +- New `tasks` command for managing tasks started with `utils.delay` (PR by davewiththenicehat) +- Make `help` index output clickable for webclient/clients with MXP (PR by davewiththenicehat) +- Custom `evennia` launcher commands (e.g. `evennia mycmd foo bar`). Add new commands as callables + accepting `*args`, as `settings.EXTRA_LAUNCHER_COMMANDS = {'mycmd': 'path.to.callable', ...}`. +- New `XYZGrid` contrib, adding x,y,z grid coordinates with in-game map and + pathfinding. Controlled outside of the game via custom evennia launcher command. +- `Script.delete` has new kwarg `stop_task=True`, that can be used to avoid + infinite recursion when wanting to set up Script to delete-on-stop. +- Command executions now done on copies to make sure `yield` don't cause crossovers. Add + `Command.retain_instance` flag for reusing the same command instance. +- The `typeclass` command will now correctly search the correct database-table for the target + obj (avoids mistakenly assigning an AccountDB-typeclass to a Character etc). +- Merged `script` and `scripts` commands into one, for both managing global- and + on-object Scripts. Moved `CmdScripts` and `CmdObjects` to `commands/default/building.py`. +- Keep GMCP function case if outputfunc starts with capital letter (so `cmd_name` -> `Cmd.Name` + but `Cmd_nAmE` -> `Cmd.nAmE`). This helps e.g Mudlet's legacy `Client_GUI` implementation) +- Prototypes now allow setting `prototype_parent` directly to a prototype-dict. + This makes it easier when dynamically building in-module prototypes. +- `RPSystem contrib` was expanded to support case, so /tall becomes 'tall man' + while /Tall becomes 'Tall man'. One can turn this off if wanting the old style. +- Change `EvTable` fixed-height rebalance algorithm to fill with empty lines at end of + column instead of inserting rows based on cell-size (could be mistaken for a bug). +- Split `return_appearance` hook with helper methods and have it use a template + string in order to make it easier to override. +- Add validation question to default account creation. +- Add `LOCALECHO` client option to add server-side echo for clients that does + not support this (useful for getting a complete log). +- Make `@lazy_property` decorator create read/delete-protected properties. This is + because it's used for handlers, and e.g. self.locks=[] is a common beginner mistake. +- Add `$pron()` inlinefunc for pronoun parsing in actor-stance strings using + `msg_contents`. +- Update defauklt website to show Telnet/SSL/SSH connect info. Added new + `SERVER_HOSTNAME` setting for use in the server:port stanza. +- Changed all `at_before/after_*` hooks to `at_pre/post_*` for consistency + across Evennia (the old names still work but are deprecated) +- Change `settings.COMMAND_DEFAULT_ARG_REGEX` default from `None` to a regex meaning that + a space or `/` must separate the cmdname and args. This better fits common expectations. +- Add confirmation question to `ban`/`unban` commands. +- Check new `teleport` and `teleport_here` lock-types in `teleport` command to optionally + allow to limit teleportation of an object or to a specific destination. +- Add `settings.MXP_ENABLED=True` and `settings.MXP_OUTGOING_ONLY=True` as sane defaults, + to avoid known security issues with players entering MXP links. +- Add browser name to webclient `CLIENT_NAME` in `session.protocol_flags`, e.g. + `"Evennia webclient (websocket:firefox)"` or `"evennia webclient (ajax:chrome)"`. +- `TagHandler.add/has(tag=...)` kwarg changed to `add/has(key=...)` for consistency + with other handlers. +- Make `DefaultScript.delete`, `DefaultChannel.delete` and `DefaultAccount.delete` return + bool True/False if deletion was successful (like `DefaultObject.delete` before them) +- `contrib.custom_gametime` days/weeks/months now always starts from 1 (to match + the standard calendar form ... there is no month 0 every year after all). +- `AttributeProperty`/`NAttributeProperty` to allow managing Attributes/NAttributes + on typeclasses in the same way as Django fields. +- Give build/system commands a `@name` to fall back to if the non-@ name is used + by another command (like `open` and `@open`. If no duplicate, @ is optional. +- Move legacy channel-management commands (`ccreate`, `addcom` etc) to a contrib + since their work is now fully handled by the single `channel` command. +- Expand `examine` command's code to much more extensible and modular. Show + attribute categories and value types (when not strings). +- `AttributeHandler.remove(key, return_exception=False, category=None, ...)` changed + to `.remove(key, category=None, return_exception=False, ...)` for consistency. +- New `command cooldown` contrib for making it easier to manage commands using + dynamic cooldowns between uses (owllex) +- Restructured `contrib/` folder, placing all contribs as separate packages under + subfolders. All imports will need to be updated. +- Made `MonitorHandler.add/remove` support `category` for monitoring Attributes + with a category (before only key was used, ignoring category entirely). +- Move `create_*` functions into db managers, leaving `utils.create` only being + wrapper functions (consistent with `utils.search`). No change of api otherwise. +- Add support for `$dbref()` and `$search` when assigning an Attribute value + with the `set` command. This allows assigning real objects from in-game. +- Add ability to examine `/script` and `/channel` entities with `examine` command. +- Homogenize manager search methods to return querysets and not lists. +- Restructure unit tests to always honor default settings; make new parents in + on location for easy use in game dir. +- The `Lunr` search engine used by help excludes common words; the settings-list + `LUNR_STOP_WORD_FILTER_EXCEPTIONS` can be extended to make sure common names are included. +- Add `.deserialize()` method to `_Saver*` structures to help completely + decouple structures from database without needing separate import. +- Add `run_in_main_thread` as a helper for those wanting to code server code + from a web view. +- Update `evennia.utils.logger` to use Twisted's new logging API. No change in Evennia API + except more standard aliases logger.error/info/exception/debug etc can now be used. +- Have `type/force` default to `update`-mode rather than `reset`mode and add more verbose + warning when using reset mode. +- Attribute storage support defaultdics (Hendher) +- Add ObjectParent mixin to default game folder template as an easy, ready-made + way to override features on all ObjectDB-inheriting objects easily. + source location, mimicking behavior of `at_pre_move` hook - returning False will abort move. +- Add `TagProperty`, `AliasProperty` and `PermissionProperty` to assign these + data in a similar way to django fields. +- New `at_pre_object_receive(obj, source_location)` method on Objects. Called on + destination, mimicking behavior of `at_pre_move` hook - returning False will abort move. +- New `at_pre_object_leave(obj, destination)` method on Objects. Called on +- The db pickle-serializer now checks for methods `__serialize_dbobjs__` and `__deserialize_dbobjs__` + to allow custom packing/unpacking of nested dbobjs, to allow storing in Attribute. +- Optimizations to rpsystem contrib performance. Breaking change: `.get_sdesc()` will + now return `None` instead of `.db.desc` if no sdesc is set; fallback in hook (inspectorCaracal) +- Reworked text2html parser to avoid problems with stateful color tags (inspectorCaracal) +- Simplified `EvMenu.options_formatter` hook to use `EvColumn` and f-strings (inspectorcaracal) +- Allow `# CODE`, `# HEADER` etc as well as `#CODE`/`#HEADER` in batchcode + files - this works better with black linting. +- Added `move_type` str kwarg to `move_to()` calls, optionally identifying the type of + move being done ('teleport', 'disembark', 'give' etc). (volund) +- Made RPSystem contrib msg calls pass `pose` or `say` as msg-`type` for use in + e.g. webclient pane filtering where desired. (volund) +- Added `Account.uses_screenreader(session=None)` as a quick shortcut for + finding if a user uses a screenreader (and adjust display accordingly). +- Fixed bug in `cmdset.remove()` where a command could not be deleted by `key`, + even though doc suggested one could (ChrisLR) +- New contrib `name_generator` for building random real-world based or fantasy-names + based on phonetic rules. +- Enable proper serialization of dict subclasses in Attributes (aogier) +- `object.search` fuzzy-matching now uses `icontains` instead of `istartswith` + to better match how search works elsewhere (volund) +- The `.at_traverse` hook now receives a `exit_obj` kwarg, linking back to the + exit triggering the hook (volund) +- Contrib `buffs` for managing temporary and permanent RPG status buffs effects (tegiminis) +- New `at_server_init()` hook called before all other startup hooks for all + startup modes. Used for more generic overriding (volund) +- New `search` lock type used to completely hide an object from being found by + the `DefaultObject.search` (`caller.search`) method. (CloudKeeper) +- Change setting `MULTISESSION_MODE` to now only control sessions, not how many + characters can be puppeted simultaneously. New settings now control that. +- Add new setting `AUTO_CREATE_CHARACTER_WITH_ACCOUNT`, a boolean deciding if + the new account should also get a matching character (legacy MUD style). +- Add new setting `AUTO_PUPPET_ON_LOGIN`, boolean deciding if one should + automatically puppet the last/available character on connection (legacy MUD style) +- Add new setting `MAX_NR_SIMULTANEUS_PUPPETS` - how many puppets the account + can run at the same time. Used to limit multi-playing. +- Make setting `MAX_NR_CHARACTERS` interact better with the new settings above. +- Allow `$search` funcparser func to search tags and to accept kwargs for more + powerful searches passed into the regular search functions. +- `spawner.spawn` and linked methods now has a kwarg `protfunc_raise_errors` + (default True) to disable strict errors on malformed/not-found protfuncs +- Improve search performance when having many DB-based prototypes via caching. +- Remove the `return_parents` kwarg of `evennia.prototypes.spawner.spawn` since it + was inefficient and unused. +- Made all id fields BigAutoField for all databases. (owllex) +- `EvForm` refactored. New `literals` mapping, for literal mappings into the + main template (e.g. for single-character replacements). +- `EvForm` `cells` kwarg now accepts `EvCells` with custom formatting options + (mainly for custom align/valign). `EvCells` now makes use of `utils.justify`. +- `utils.justify` now supports `align="a"` (absolute alignments. This keeps + the given left indent but crops/fills to the width. Used in EvCells. +- `EvTable` now supports passing `EvColumn`s as a list directly, (`EvTable(table=[colA,colB])`) +- Add `tags=` search criterion to `DefaultObject.search`. +- Add `AT_EXIT_TRAVERSE` signal, firing when an exit is traversed. +- Add integration between Evennia and Discord channels (PR by Inspector Cararacal) +- Support for using a Godot-powered client with Evennia (PR by ChrisLR) +- Added German translation (patch by Zhuraj) -### Backports from 1.0 to 0.9.5 since 0.9.5 release +## Evennia 0.9.5 -- Fix to TaskHandler to complate api and allow manipulation of `utils.delay` - return as originall intended. -- Support for Python 3.9. +> 2019-2020 +> Released 2020-11-14. +> Transitional release, including new doc system. -### Evennia 0.9.5 (Nov 2020) - -A transitional release, including new doc system. +Backported from develop: Python 3.8, 3.9 support. Django 3.2+ support, Twisted 21+ support. - `is_typeclass(obj (Object), exact (bool))` now defaults to exact=False - `py` command now reroutes stdout to output results in-game client. `py` @@ -91,8 +299,7 @@ without arguments starts a full interactive Python console. - Make `cmd.at_post_cmd()` always run after `cmd.func()`, even when the latter uses delays with yield. - `EvMore` support for db queries and django paginators as well as easier to override for custom - pagination (e.g. to create EvTables for every page instead of splitting one table). -- New `EvMore` methods `.init_pages`, `paginator` and `page_formatter` for easily customize pagination. + pagination (e.g. to create EvTables for every page instead of splittine one table) - Using `EvMore pagination`, dramatically improves performance of `spawn/list` and `scripts` listings (100x speed increase for displaying 1000+ prototypes/scripts). - `EvMenu` now uses the more logically named `.ndb._evmenu` instead of `.ndb._menutree` to store itself. @@ -104,10 +311,16 @@ without arguments starts a full interactive Python console. - Include more Web-client info in `session.protocol_flags`. - Fixes in multi-match situations - don't allow finding/listing multimatches for 3-box when only two boxes in location. -- Made the `evennia` dir possible to use without gamedir for purpose of doc generation. +- Fix for TaskHandler with proper deferred returns/ability to cancel etc (PR by davewiththenicehat) +- Add `PermissionHandler.check` method for straight string perm-checks without needing lockstrings. +- Add `evennia.utils.utils.strip_unsafe_input` for removing html/newlines/tags from user input. The + `INPUT_CLEANUP_BYPASS_PERMISSIONS` is a list of perms that bypass this safety stripping. +- Make default `set` and `examine` commands aware of Attribute categories. +## Evennia 0.9 -## Evennia 0.9 (2018-2019) +> 2018-2019 +> Released Oct 2019 ### Distribution @@ -305,7 +518,10 @@ without arguments starts a full interactive Python console. - Simplified chinese, courtesy of user MaxAlex. -## Evennia 0.8 (2018) +## Evennia 0.8 + +> 2017-2018 +> Released Nov 2018 ### Requirements @@ -432,7 +648,9 @@ without arguments starts a full interactive Python console. - Polish translation by user ogotai -# Overviews +# Overview-Changelogs + +> These are changelogs from a time before we used formal version numbers. ## Sept 2017: Release of Evennia 0.7; upgrade to Django 1.11, change 'Player' to @@ -554,24 +772,9 @@ to Events, Commands and Permissions. Griatch takes over Maintainership of the Evennia project from the original creator Greg Taylor. -(Earlier revisions, with previous maintainer, go back to 2005) +# Older +Earlier revisions, with previous maintainer, used SVN on Google Code +and have no changelogs. -# Contact, Support and Development - -Make a post to the mailing list or chat us up on IRC. We also have a -bug tracker if you want to report bugs. Finally, if you are willing to -help with the code work, we much appreciate all help! Visit either of -the following resources: - -* Evennia Webpage - http://evennia.com -* Evennia manual (wiki) - https://github.com/evennia/evennia/wiki -* Evennia Code Page (See INSTALL text for installation) - https://github.com/evennia/evennia -* Bug tracker - https://github.com/evennia/evennia/issues -* IRC channel - visit channel #evennia on irc.freenode.com - or the webclient: http://tinyurl.com/evchat +First commit (Evennia's birthday) was November 20, 2006. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 299ad5d241..ef731d5e22 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -2,11 +2,17 @@ ## Our Pledge -In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of +experience, nationality, personal appearance, race, religion, or sexual identity +and orientation. ## Our Standards -Examples of behavior that contributes to creating a positive environment include: +Examples of behavior that contributes to creating a positive environment +include: * Using welcoming and inclusive language * Being respectful of differing viewpoints and experiences @@ -16,31 +22,54 @@ Examples of behavior that contributes to creating a positive environment include Examples of unacceptable behavior by participants include: -* The use of sexualized language or imagery and unwelcome sexual attention or advances +* The use of sexualized language or imagery and unwelcome sexual attention or + advances * Trolling, insulting/derogatory comments, and personal or political attacks * Public or private harassment -* Publishing others' private information, such as a physical or electronic address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a professional setting +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting ## Our Responsibilities -Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. -Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. +Project maintainers have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, or to ban temporarily or permanently any +contributor for other behaviors that they deem inappropriate, threatening, +offensive, or harmful. ## Scope -This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. ## Enforcement -Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting griatch AT gmail DOT com or Griatch in the #evennia channel on irc.freenode.net. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting griatch AT gmail DOT com or Griatch in the #evennia +channel on irc.freenode.net. The project team will review and investigate all +complaints, and will respond in a way that it deems appropriate to the +circumstances. The project team is obligated to maintain confidentiality with +regard to the reporter of an incident. Further details of specific enforcement +policies may be posted separately. -Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. ## Attribution -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version] +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 1.4, available at [http://contributor-covenant.org/version/1/4][version] [homepage]: http://contributor-covenant.org [version]: http://contributor-covenant.org/version/1/4/ diff --git a/CODING_STYLE.md b/CODING_STYLE.md index 80e8ac595c..52b6bcfb6a 100644 --- a/CODING_STYLE.md +++ b/CODING_STYLE.md @@ -1,32 +1,34 @@ # Evennia Code Style -All code submitted or committed to the Evennia project should aim to -follow the guidelines outlined in [Python PEP 8][pep8]. Keeping the code style -uniform makes it much easier for people to collaborate and read the -code. +All code submitted or committed to the Evennia project should aim to follow the +guidelines outlined in [Python PEP 8][pep8]. 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][pep8tool] on your sources. -## A quick list of code style points +## 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. - * (Evennia-specific): Imports should normally be done in this order: + * 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 modules should have doc - strings formatted as described below + * 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. -## Doc strings +## Code Docstrings All modules, classes, functions and methods should have docstrings formatted with [Google style][googlestyle] -inspired indents, using @@ -52,7 +54,7 @@ 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. +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. @@ -68,7 +70,7 @@ other text, only code). ### Class docstrings -The root class docstring should describe the over-arcing use of the +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). @@ -105,7 +107,7 @@ def funcname(a, b, c, d=False, **kwargs): test (list): A test keyword. Returns: - e (str): The result of the function. + str: The result of the function. Raises: RuntimeException: If there is a critical error, @@ -129,20 +131,18 @@ indents to be 4 spaces wide (no tabs!). Here are all the supported block headers: ``` - Args/Arg/Kwargs/Kwarg: - argname (freeform type): text - or - freeform text + """ + Args + argname (freeform type): Description endind with period. + Keyword Args: + argname (freeform type): Description. Returns/Yields: - kwargname (freeform type): text - or - freeform text + type: Description. Raises: - Exceptiontype: text - or - freeform text + Exceptiontype: Description. Notes/Note/Examples/Example: - freeform text + Freeform text. + """ ``` Parts marked with "freeform" means that you can in principle put any @@ -153,20 +153,24 @@ 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. +documented. Note that ``` +""" Args: - argname (type, optional): text + argname (type, optional): Description. +""" ``` and ``` +""" Keyword Args: - argname (type): text + sargname (type): Description. +""" ``` mean the same thing! Which one is used depends on the function or @@ -176,25 +180,92 @@ 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 Commands +## Default Command Docstrings -These represent a special case since Commands in Evennia are using their -class docstrings to represent the in-game help entry for that command. -So for the default look of Command class docstrings see instead -[the default command documentation policy][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. -### Automatic docstring templating +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. -The Python IDE [Pycharm][pycharm] will generate Evennia-friendly -docstring stubs automatically for you, but the default format is -reStructuredText. To change it to Evennia's Google-style, follow -[this guide][pycharm-guide]. +```python + """ + Short header -## Ask Questions! + Usage: + key[/switches, if any] [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: + +```python + """ + Define a personal alias/nick + + Usage: + nick[/switches] = [] + 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 + +```python + if not self.args: + self.caller.msg("Usage: nick[/switches] = []") + 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][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][pycharm-guide]. -If any of the rules outlined in PEP 8 or in the sections above doesn't -make sense, please don't hesitate to ask on the Evennia mailing list -or in the chat. [pep8]: http://www.python.org/dev/peps/pep-0008 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0d1917c4e4..5f0d5bfdb7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,17 @@ # Contributing to Evennia -Evennia utilizes GitHub for issue tracking and contributions: +There are many ways you can contribute to Evennia development: - - Reporting Issues issues/bugs and making feature requests can be done [in the issue tracker](https://github.com/evennia/evennia/issues). - - Evennia's documentation is a [wiki](https://github.com/evennia/evennia/wiki) that everyone can contribute to. Further - instructions and details about contributing is found [here](https://github.com/evennia/evennia/wiki/Contributing). + - You can help a lot by being active in the community. You can spread + the word - by writing, talking, blogging etc about Evennia. Let + others know text-based gaming is still a thing! + - You can help by reporting any issues/bugs you find, and tell us of your + feature requests [as an issue on github][issues]. This is also where you + report typos or errors in the [the Evennia documentation][docs]. + - To help fixing (or expand) our docs, check out [how to contribute to docs][contribute-docs]. + - To contribute to Evennia itself, check out how to [help with code][helping-code]. + +[issues]: https://github.com/evennia/evennia/issues/new/choose +[docs]: https://www.evennia.com/docs/1.0-dev/index.html +[contribute-docs]: https://www.evennia.com/docs/1.0-dev/Contributing-Docs.html +[helping-code]: https://www.evennia.com/docs/1.0-dev/Contributing.html#helping-with-code diff --git a/Dockerfile b/Dockerfile index b45bae03ad..cac23de589 100644 --- a/Dockerfile +++ b/Dockerfile @@ -2,7 +2,7 @@ # Base docker image for running Evennia-based games in a container. # # Install: -# install `docker` (http://docker.com) +# install `docker` (https://docker.com) # # Usage: # cd to a folder where you want your game data to be (or where it already is). @@ -26,25 +26,27 @@ # # The evennia/evennia base image is found on DockerHub and can also be used # as a base for creating your own custom containerized Evennia game. For more -# info, see https://github.com/evennia/evennia/wiki/Running%20Evennia%20in%20Docker . +# info, see https://evennia.com/docs/latest/Setup/Installation-Docker # -FROM python:3.7-alpine +FROM python:3.11-alpine -LABEL maintainer="www.evennia.com" +LABEL maintainer="https://www.evennia.com" # install compilation environment RUN apk update && apk add bash gcc jpeg-dev musl-dev procps \ -libffi-dev openssl-dev zlib-dev gettext +libffi-dev openssl-dev zlib-dev gettext \ +g++ gfortran python3-dev cmake openblas-dev # add the files required for pip installation +COPY ./pyproject.toml /usr/src/evennia/ COPY ./setup.py /usr/src/evennia/ -COPY ./requirements.txt /usr/src/evennia/ -COPY ./evennia/VERSION.txt /usr/src/evennia/evennia/ COPY ./bin /usr/src/evennia/bin/ # install dependencies -RUN pip install --upgrade pip && pip install -e /usr/src/evennia --trusted-host pypi.python.org -RUN pip install cryptography pyasn1 service_identity +RUN pip install --upgrade pip && \ + pip install cryptography pyasn1 service_identity && \ + pip install -e /usr/src/evennia --trusted-host pypi.python.org && \ + pip install evennia[extra] # add the project source; this should always be done after all # expensive operations have completed to avoid prematurely @@ -53,7 +55,7 @@ COPY . /usr/src/evennia # add the game source when rebuilding a new docker image from inside # a game dir -ONBUILD COPY . /usr/src/game +ONBUILD COPY --chown=evennia . /usr/src/game # make the game source hierarchy persistent with a named volume. # mount on-disk game location here when using the container @@ -63,15 +65,16 @@ VOLUME /usr/src/game # set the working directory WORKDIR /usr/src/game -# set bash prompt -ENV PS1 "evennia|docker \w $ " +# set bash prompt and pythonpath to evennia lib +ENV PS1 "evennia|docker \w $ " +ENV PYTHONPATH /usr/src/evennia # create and switch to a non-root user for runtime security # -D - do not set a password # -H - do not create a home directory # -s /bin/false - set login shell to /bin/false -RUN adduser -D -H -s /bin/false evennia -USER evennia +# RUN adduser -D -H -s /bin/false evennia +# USER evennia # startup a shell when we start the container ENTRYPOINT ["/usr/src/evennia/bin/unix/evennia-docker-start.sh"] diff --git a/INSTALL.md b/INSTALL.md index 926785ee5f..2516eaae96 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,5 +1,6 @@ # Evennia installation -You can find the latest updated installation instructions and -requirements [here](https://github.com/evennia/evennia/wiki/Getting-Started). +You can find the latest updated installation instructions and +requirements +[here](https://www.evennia.com/docs/1.0-dev/Setup/Installation.html) diff --git a/LICENSE.txt b/LICENSE.txt index 30c47bbed0..0daabf80bb 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,35 +1,19 @@ -BSD license -=========== +BSD 3-Clause License -Evennia MU* creation system -Copyright (c) 2012-, Griatch (griatch gmail com), Gregory Taylor -All rights reserved. +Copyright 2012- Griatch (griatch gmail com), Gregory Taylor -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: +Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: -- Redistributions of source code must retain the above copyright -notice, this list of conditions and the following disclaimer. -- Redistributions in binary form must reproduce the above copyright -notice, this list of conditions and the following disclaimer in the -documentation and/or other materials provided with the distribution. -- Neither the name of the Copyright Holders nor the names of its -contributors may be used to endorse or promote products derived from -this software without specific prior written permission. +1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND -CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED -WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, -INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE -GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR -BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF -LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT -OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE -POSSIBILITY OF SUCH DAMAGE. +2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer + in the documentation and/or other materials provided with the distribution. +3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived + from this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR +TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/Makefile b/Makefile index b8b4857155..8ccf3f355d 100644 --- a/Makefile +++ b/Makefile @@ -1,24 +1,31 @@ # This is used with `make