diff --git a/docs/source/Contributing.md b/docs/source/Contributing.md index 3172682971..b9489cd8b3 100644 --- a/docs/source/Contributing.md +++ b/docs/source/Contributing.md @@ -1,118 +1,192 @@ -# Contributing +# How To Contribute And Get Help +If you cannot find what you are looking for in the documentation, here's what to do: -Wanna help out? Great! Here's how. +- If you need help, want to start a discussion or get some input on something + you are working on, make a post to the [discussions forum][forum]. +- If you want more direct discussions with developers and other users, drop + into our very friendly [Discord channel][chat]. +- If you think the documentation is not clear enough, create a [documentation issue][issues] +- If you have trouble with a missing feature or a problem you think is a bug, + [request or report it][issues]. -## Spreading the word +## Community and Spreading the word -Even if you are not keen on working on the server code yourself, just spreading the word is a big -help - it will help attract more people which leads to more feedback, motivation and interest. -Consider writing about Evennia on your blog or in your favorite (relevant) forum. Write a review -somewhere (good or bad, we like feedback either way). Rate it on places like [ohloh][ohloh]. Talk -about it to your friends ... that kind of thing. +Being active and helpful in the [forums][forum] or [chat][chat] is already a big +help. -## Donations - -The best way to support Evennia is to become an [Evennia patron][patron]. Evennia is a free, -open-source project and any monetary donations you want to offer are completely voluntary. See it as -a way of announcing that you appreciate the work done - a tip of the hat! A patron donates a -(usually small) sum every month to show continued support. If this is not your thing you can also -show your appreciation via a [one-time donation][donate] (this is a PayPal link but you don't need -PayPal yourself). +Consider writing about Evennia on your blog or in your favorite (relevant) +forum. Write a review somewhere (good or bad, we like feedback either way). Rate +it on listings. Talk about it to your friends ... that kind of thing. ## Help with Documentation -Evennia depends heavily on good documentation and we are always looking for extra eyes and hands to -improve it. Even small things such as fixing typos are a great help! +Evennia depends heavily on good documentation and we are always looking for +extra eyes and hands to improve it. Even small things such as fixing typos are a +great help! -The documentation is a wiki and as long as you have a GitHub account you can edit it. It can be a -good idea to discuss in the chat or forums if you want to add new pages/tutorials. Otherwise, it -goes a long way just pointing out wiki errors so we can fix them (in an Issue or just over -chat/forum). +- Easiest is to just [report dicumentation issues][issues] as you find them. If + we don't know about them, we can't fix them! +- If you want to help edit the docs directly, [check here](./Contributing-Docs.md) + on how to do it. +- If you have knowledge to share, how about writing a new [Tutorial](Howto/Howto-Overview.md)? -## Contributing through a forked repository +## Helping with code -We always need more eyes and hands on the code. Even if you don't feel confident with tackling a -[bug or feature][issues], just correcting typos, adjusting formatting or simply *using* the thing -and reporting when stuff doesn't make sense helps us a lot. +If you find bugs, or have a feature-request, [make an issue][issues] for it. If +it's not in an issue, the issue will most likely be forgotten. -The most elegant way to contribute code to Evennia is to use GitHub to create a *fork* of the -Evennia repository and make your changes to that. Refer to the [Forking Evennia](Version- -Control#forking-evennia) version -control instructions for detailed instructions. +Even if you don't feel confident with tackling a [bug or feature][issues], just +correcting typos, adjusting formatting or simply *using* the thing and reporting +when stuff doesn't make sense helps us a lot. -Once you have a fork set up, you can not only work on your own game in a separate branch, you can -also commit your fixes to Evennia itself. Make separate branches for all Evennia additions you do - -don't edit your local `master` or `develop` branches directly. It will make your life a lot easier. -If you have a change that you think is suitable for the main Evennia repository, you issue a [Pull -Request][pullrequest]. This will let Evennia devs know you have stuff to share. Bug fixes should -generally be done against the `master` branch of Evennia, while new features/contribs should go into -the `develop` branch. If you are unsure, just pick one and we'll figure it out. - -## Contributing with Patches +- The code itself should follow Evennia's [Code style guidelines][codestyle] both + for code and documentation. You should write code for that others can read an understand. +- Before merging, your code will be reviewed. Merging of your code into Evennia + is not guaranteed. Be ready to receive feedback and to be asked to make + corrections or fix bugs or any documentation issues and possibly tests (this + is normal and nothing to worry about). -To help with Evennia development it's recommended to do so using a fork repository as described -above. But for small, well isolated fixes you are also welcome to submit your suggested Evennia -fixes/addendums as a [patch][patch]. +### Using a Forked reposity -You can include your patch in an Issue or a Mailing list post. Please avoid pasting the full patch -text directly in your post though, best is to use a site like [Pastebin](https://pastebin.com/) and -just supply the link. +The most elegant way to contribute code to Evennia is to use GitHub to create a +*fork* of the Evennia repository and make your changes to that. Refer to the +[Forking Evennia](Coding/Version-Control.md#forking-evennia) version control instructions +for detailed instructions. -## Contributing with Contribs +Once you have a fork set up, you can not only work on your own game in a +separate branch, you can also commit your fixes to Evennia itself. -While Evennia's core is pretty much game-agnostic, it also has a `contrib/` directory. The `contrib` -directory contains game systems that are specialized or useful only to certain types of games. Users -are welcome to contribute to the `contrib/` directory. Such contributions should always happen via a -Forked repository as described above. +- Make separate branches for all Evennia additions you do - don't edit your + local `master` or `develop` branches directly. It will make your life a lot + easier. +- If you have a change that you think is suitable for the main Evennia + repository, issue a [Pull Request][pullrequest]. This will let Evennia + devs know you have stuff to share. +- Bug fixes should generally be done against the `master` branch of Evennia, + while new features/contribs should go into the `develop` branch. If you are + unsure, just pick one and we'll figure it out. -* If you are unsure if your idea/code is suitable as a contrib, *ask the devs before putting any -work into it*. This can also be a good idea in order to not duplicate efforts. This can also act as -a check that your implementation idea is sound. We are, for example, unlikely to accept contribs -that require large modifications of the game directory structure. -* If your code is intended *primarily* as an example or shows a concept/principle rather than a -working system, it is probably not suitable for `contrib/`. You are instead welcome to use it as -part of a [new tutorial][tutorials]! -* The code should ideally be contained within a single Python module. But if the contribution is -large this may not be practical and it should instead be grouped in its own subdirectory (not as -loose modules). -* The contribution should preferably be isolated (only make use of core Evennia) so it can easily be -dropped into use. If it does depend on other contribs or third-party modules, these must be clearly -documented and part of the installation instructions. -* The code itself should follow Evennia's [Code style guidelines][codestyle]. -* The code must be well documented as described in our [documentation style -guide](https://github.com/evennia/evennia/blob/master/CODING_STYLE.md#doc-strings). Expect that your -code will be read and should be possible to understand by others. Include comments as well as a -header in all modules. If a single file, the header should include info about how to include the -contrib in a game (installation instructions). If stored in a subdirectory, this info should go into -a new `README.md` file within that directory. -* Within reason, your contribution should be designed as genre-agnostic as possible. Limit the -amount of game-style-specific code. Assume your code will be applied to a very different game than -you had in mind when creating it. -* To make the licensing situation clear we assume all contributions are released with the same -[license as Evennia](./Licensing.md). If this is not possible for some reason, talk to us and we'll -handle it on a case-by-case basis. -* Your contribution must be covered by [unit tests](Coding/Unit-Testing.md). Having unit tests will both help -make your code more stable and make sure small changes does not break it without it being noticed, -it will also help us test its functionality and merge it quicker. If your contribution is a single -module, you can add your unit tests to `evennia/contribs/tests.py`. If your contribution is bigger -and in its own sub-directory you could just put the tests in your own `tests.py` file (Evennia will -find it automatically). -* Merging of your code into Evennia is not guaranteed. Be ready to receive feedback and to be asked -to make corrections or fix bugs. Furthermore, merging a contrib means the Evennia project takes on -the responsibility of maintaining and supporting it. For various reasons this may be deemed to be -beyond our manpower. However, if your code were to *not* be accepted for merger for some reason, we -will instead add a link to your online repository so people can still find and use your work if they -want. +### Contributing with Patches -[ohloh](http://www.ohloh.net/p/evennia) -[patron](https://www.patreon.com/griatch) -[donate](https://www.paypal.com/en/cgi-bin/webscr?cmd=_flow&SESSION=TWy_epDPSWqNr4UJCOtVWxl-) -pO1X1jbKiv_- -UBBFWIuVDEZxC0M_2pM6ywO&dispatch=5885d80a13c0db1f8e263663d3faee8d66f31424b43e9a70645c907a6cbd8fb4 -[forking](https://github.com/evennia/evennia/wiki/Version-Control#wiki-forking-from-evennia) -[pullrequest](https://github.com/evennia/evennia/pulls) -[issues](https://github.com/evennia/evennia/issues) -[patch](https://secure.wikimedia.org/wikipedia/en/wiki/Patch_%28computing%29 ) -[codestyle](https://github.com/evennia/evennia/blob/master/CODING_STYLE.md) -[tutorials](https://github.com/evennia/evennia/wiki/Tutorials) +To help with Evennia development it's strongly recommended to do so using a +forked repository as described above. But for small, well isolated fixes you are +also welcome to submit your suggested Evennia fixes/addendums as a +[patch][patch]. + +You can include your patch in an Issue or a Mailing list post. Please avoid +pasting the full patch text directly in your post though, best is to use a site +like [Pastebin](https://pastebin.com/) and just supply the link. + +### Making an Evennia contrib + +Evennia has a [contrib](Contribs/Contrib-Overview.md) directory which contains +user-shared code organized by category. You can contribute anything that you +think may be useful to another dev, also highly game-specific code. A contrib +must always be added via a forked respository. + +#### Guidelines for making a contrib + +- If you are unsure about if your contrib idea is suitable or sound, *ask in + discussions or chat before putting any work into it*. We are, for example, + unlikely to accept contribs that require large modifications of the game + directory structure. +- If your code is intended *primarily* as an example or to show a + concept/principle rather than a working system, you _can_ add to the + `contribs/tutorials/` subfolder, but consider if it may be better to instead + write a new tutorial doc page. +- The contribution should preferably work in isolation from other contribs (only + make use of core Evennia) so it can easily be dropped into use. If it does + depend on other contribs or third-party modules, these must be clearly + documented and part of the installation instructions. +- The contrib must be contained within a separate folder under one of the + contrib categories (`game_systems`, `rpg`, `utils` etc). Ask if you are + unsuare which category to put your contrib under. +- The folder (package) should be on the following form: + + ``` + mycontribname/ + __init__.py + README.md + module1.py + module2.py + ... + tests.py + ``` + + It's often a good idea to import useful resources in `__init__.py` to make + it easier to access them (this may vary though). + + The `README.md` will be parsed and converted into a document linked from + [the contrib overview page](Contribs/Contrib-Overview.md). It should follow + the following structure: + + ```markdown + # MyContribName + + Contribution by , + + A paragraph (can be multi-line) + summarizing the contrib (required) + + Optional other text + + ## Installation + + Detailed installation instructions for using the contrib (required) + + ## Usage + + ## Examples + + etc. + + ``` + + The credit and first paragraph-summary will be used on the index page. Every + contrib's readme must contain an installation instruction. See existing contribs + for help. + +- If possible, try to make contribution as genre-agnostic as possible and assume + your code will be applied to a very different game than you had in mind when creating it. +- To make the licensing situation clear we assume all contributions are released + with the same [license as Evennia](./Licensing.md). If this is not possible +for some reason, talk to us and we'll handle it on a case-by-case basis. +- Your contribution must be covered by [unit tests](Coding/Unit-Testing.md). Put + your tests in a module `tests.py` under your contrib folder - Evennia will + find them automatically. +- In addition to the normal review process, it's worth noting that merging a + contrib means the Evennia project takes on the responsibility of maintaining + and supporting it. For various reasons this may be deemed beyond our manpower. +- If your code were to *not* be accepted for some reason, you can ask us to + instead link to your repo from our link page so people can find your code that + way. + +## Donations + +Evennia is a free, open-source project and any monetary donations you want to +offer are _completely voluntary_. See it as a way of showing appreciation by +dropping a few coins in the cup. + +- You can support Evennia as an [Evennia patreon][patron]. A patreon donates a + (usually small) sum every month to show continued support. +- If a monthly donation is not your thing, you can also show your appreciation + by doing a [one-time donation][donate] (this is a PayPal link but you don't need + PayPal yourself to use it). + + +[patron]: https://www.patreon.com/griatch +[donate]: https://www.paypal.com/donate?token=zbU72YdRqPgsbpTw3M_4vR-5QJ7XvUhL9W6JlnPJw70M9LOqY1xD7xKGx0V1jLFSthY3xAztQpSsqW9n +[forking]: https://github.com/evennia/evennia/wiki/Version-Control#wiki-forking-from-evennia +[pullrequest]: https://github.com/evennia/evennia/pulls +[issues]: https://github.com/evennia/evennia/issues +[patch]: https://secure.wikimedia.org/wikipedia/en/wiki/Patch_%28computing%29 +[codestyle]: https://github.com/evennia/evennia/blob/master/CODING_STYLE.md + +[forum]:https://github.com/evennia/evennia/discussions +[issues]:https://github.com/evennia/evennia/issues/choose +[chat]: https://discord.com/invite/AJJpcRUhtF +[paypal]: https://www.paypal.com/se/cgi-bin/webscr?cmd=_flow&SESSION=Z-VlOvfGjYq2qvCDOUGpb6C8Due7skT0qOklQEy5EbaD1f0eyEQaYlmCc8O&dispatch=5885d80a13c0db1f8e263663d3faee8d64ad11bbf4d2a5a1a0d303a50933f9b2 +[patreon]: https://www.patreon.com/griatch +[issues-bounties]:https://github.com/evennia/evennia/labels/bounty +[bountysource]: https://www.bountysource.com/teams/evennia diff --git a/docs/source/How-To-Get-And-Give-Help.md b/docs/source/How-To-Get-And-Give-Help.md deleted file mode 100644 index 2bb50dc832..0000000000 --- a/docs/source/How-To-Get-And-Give-Help.md +++ /dev/null @@ -1,66 +0,0 @@ -# How To Get And Give Help - - -## How to *get* Help - -If you cannot find what you are looking for in the documentation, here's what to do: - -- If you think the documentation is not clear enough, create a [documentation ticket](github:issue). -- If you have trouble with a missing feature or a problem you think is a bug, look through the - the list of known [issue][issues] if you can't find your issue in the list, make a - new one [here](github:issue). -- If you need help, want to start a discussion or get some input on something you are working on, -make a post to the [discussions group][group] This is technically a 'mailing list', but you don't -need to use e-mail; you can post and read all messages just as easily from your browser via the -online interface. -- If you want more direct discussions with developers and other users, consider dropping into our -IRC chat channel [#evennia][chat] on the *Freenode* network. There is also a Discord channel -bridged into the IRC if you prefer that. Please that you have to be -patient if you don't get any response immediately; we are all in very different time zones and many -have busy personal lives. So you might have to hang around for a while - you'll get noticed -eventually! - - -## How to *give* Help - -Evennia is open-source and non-commercial. It relies on the time donated by its users and developers in order to progress. - -- Spread the word! If you like Evennia, consider writing a blog post about it. -- Take part in the Evennia community! Join the [chat][chat] or [forum][group]. -- Report problems you find or features you'd like to our [issue tracker](github:issue). - -```{important} - Just the simple act of us know you are out there using Evennia helps a lot! -``` - -If you'd like to help develop Evennia more hands-on, here are some ways to get going: - -- Look through this [online documentation](./index.md#evennia-documentation) and see if you can help improve or expand the -documentation (even small things like fixing typos!). [See here](./Contributing-Docs.md) on how you -contribute to the docs. -- Send a message to our [discussion group][group] and/or our [IRC chat][chat] asking about what -needs doing, along with what your interests and skills are. -- Take a look at our [issue tracker][issues] and see if there's something you feel like taking on. -[here are bugs][issues-master] that need fixes. At any given time there may also be some -[bounties][issues-bounties] open. -- Check out the [Contributing](./Contributing.md) page on how to practically contribute with code using -github. - -... And finally, if you want to help motivate and support development you can also drop some coins -in the developer's cup. You can [make a donation via PayPal][paypal] or, even better, -[become an Evennia patron on Patreon][patreon]! This is a great way to tip your hat and show that you -appreciate the work done with the server! You can also encourage the community to take on particular -issues by putting up a monetary [bounty][bountysource] on it. - - -[form]: https://docs.google.com/spreadsheet/viewform?hl=en_US&formkey=dGN0VlJXMWpCT3VHaHpscDEzY1RoZGc6MQ#gid=0 -[group]:https://groups.google.com/group/evennia/ -[issues]:https://github.com/evennia/evennia/issues -[issues-master]:https://github.com/evennia/evennia/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3Abug%20label%3Amaster-branch -[chat]: https://webchat.freenode.net/?channels=evennia -[paypal]: https://www.paypal.com/se/cgi-bin/webscr?cmd=_flow&SESSION=Z-VlOvfGjYq2qvCDOUGpb6C8Due7skT0qOklQEy5EbaD1f0eyEQaYlmCc8O&dispatch=5885d80a13c0db1f8e263663d3faee8d64ad11bbf4d2a5a1a0d303a50933f9b2 -[donate-img]: https://images-focus-opensocial.googleusercontent.com/gadgets/proxy?url=https://www.paypalobjects.com/en%255fUS/SE/i/btn/btn%255fdonateCC%255fLG.gif&container=focus&gadget=a&rewriteMime=image/* -[patreon]: https://www.patreon.com/griatch -[patreon-img]: https://www.evennia.com/_/rsrc/1424724909023/home/evennia_patreon_100x100.png -[issues-bounties]:https://github.com/evennia/evennia/labels/bounty -[bountysource]: https://www.bountysource.com/teams/evennia diff --git a/docs/source/Setup/Extended-Installation.md b/docs/source/Setup/Extended-Installation.md index c7fabca9b4..9b7bcbe566 100644 --- a/docs/source/Setup/Extended-Installation.md +++ b/docs/source/Setup/Extended-Installation.md @@ -478,7 +478,7 @@ forums](https://groups.google.com/forum/#%21forum/evennia). You can also join th Server](https://discord.gg/NecFePw). Finally, if you are itching to help out or support Evennia (awesome!) have an -issue to report or a feature to request, [see here](../How-To-Get-And-Give-Help.md). +issue to report or a feature to request, [see here](../Contributing.md). Enjoy your stay! diff --git a/docs/source/index.md b/docs/source/index.md index 0b176d3a39..5de4ce904f 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -19,7 +19,7 @@ This is the manual of [Evennia](https://www.evennia.com), the open source Python - [Evennia Introduction](./Evennia-Introduction.md) - [Install & Setup Quickstart](Setup/Setup-Quickstart.md) - [Starting tutorial](Howto/Starting/Part1/Starting-Part1.md) -- [How to get (and give) help](./How-To-Get-And-Give-Help.md) +- [How to contribute and get help](./Contributing.md) ## Main sections @@ -46,7 +46,7 @@ Want to help improve the docs? See the page on [Contributing to the docs](./Cont Evennia-Introduction Setup/Setup-Quickstart.md Howto/Starting/Part1/Starting-Part1.md -How-To-Get-And-Give-Help.md +Contributing.md Setup/Setup-Overview.md Howto/Howto-Overview.md Components/Components-Overview.md diff --git a/docs/source/toc.md b/docs/source/toc.md index 5684da163d..61581c5989 100644 --- a/docs/source/toc.md +++ b/docs/source/toc.md @@ -124,7 +124,6 @@ Contributing-Docs Evennia-API Evennia-Introduction Glossary -How-To-Get-And-Give-Help Howto/Add-a-wiki-on-your-website Howto/Building-a-mech-tutorial Howto/Coding-FAQ