From d4f32b398182d6ba318d60b41853ef4ee6decace Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Maquin?= Date: Mon, 20 Dec 2021 18:52:04 +0100 Subject: [PATCH] Tweak documentation --- CONTRIBUTING.md | 63 +++++++++++++------ .../advanced/migrating_to_godot_ink.rst | 4 ++ docs/source/index.rst | 1 + 3 files changed, 50 insertions(+), 18 deletions(-) create mode 100644 docs/source/advanced/migrating_to_godot_ink.rst diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5a413c60..ca4c3e58 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,18 +2,22 @@ We're very happy to hear that you wish to contribute! 🎊 -_inkgd__ is a fairly small project, so the rules aren't particularly tight. There are a few things to know, however. -For one, the current project maintainer is usually not very responsive and wishes to extend their apologies in that regard. +_inkgd__ is a fairly small project, so the rules aren't particularly tight. +There are a few things to know, however. For one, the current project maintainer +is usually not very responsive and wishes to extend their apologies in that +regard. ## Asking question / Reporting issues / Getting in touch ### I have a question -1. Check whether it has been asked before or not. You can either search through [issues]. +1. Check whether it has been asked before or not. You can either search through + [issues]. 2. If it hasn't been asked before, open an issue. -If it's about getting help, please avoid sending e-mails directly to the project maintainer. -It's better to ask out in the open, the community greatly benefits when questions and answers are readily available. +If it's about getting help, please avoid sending e-mails directly to the project +maintainer. It's better to ask out in the open, the community greatly benefits +when questions and answers are readily available. Don't forget, asking questions is nothing to be ashamed of. @@ -25,52 +29,75 @@ Open an issue or fix the bug yourself and submit a pull request! ### I think _inkgd_ would be better with feature X -If you want to improve the editor plugin, it's better to notify the project maintainer beforehand. You don't want to put in a significant amount of work and see your pull request refused because it doesn't fit the project's vision. To get in touch with the project manager, you can either open a issue, poke them on Gitter or send them an email, they will try to respond as quickly as possible! +If you want to improve the editor plugin, it's better to notify the project +maintainer beforehand. You don't want to put in a significant amount of work and +see your pull request refused because it doesn't fit the project's vision. To +get in touch with the project manager, you can either open a issue, poke them on +Gitter or send them an email, they will try to respond as quickly as possible! -On the other hand, if you want to improve the runtime, remember that _inkgd_ follows the features provided by the original C# version. Thus, it's unlikely your feature idea will be accepted if it's present in the original version. +On the other hand, if you want to improve the runtime, remember that _inkgd_ +follows the features provided by the original C# version. Thus, it's unlikely +your feature idea will be accepted if it's present in the original version. ## Adding code to _inkgd_ If you're working on a pull request, here are a few things to remember. -**Don't be afraid to ask questions!** If anything seems unclear, ask away! We need to make sure that everyone is on the same page. +**Don't be afraid to ask questions!** If anything seems unclear, ask away! We +need to make sure that everyone is on the same page. ### Style guide, testing & debugging #### Style guide -_inkgd_ tries to follow the [official style guide], though it's not there yet due to its C# ancestry. +_inkgd_ tries to follow the [official style guide], though it's not there yet +due to its C# ancestry. There are two important rules to follow: -1. Whenever accessing an instance property, it should be done through `self`. This ensures that setter and getter will always be called. -2. When converting a C# `struct`, which is value type, make sure you implement a `duplicate()` method and use it appropriately. +1. Whenever accessing an instance property, it should be done through `self`. + This ensures that setter and getter will always be called. +2. When converting a C# `struct`, which is value type, make sure you implement a + `duplicate()` method and use it appropriately. [official style guide]: http://docs.godotengine.org/en/latest/getting_started/scripting/gdscript/gdscript_styleguide.html #### Testing -Make sure all the tests are all green! _inkgd_ uses [Gut] to run tests. Adding tests to your PR is not expected, but feel free to do so 😉. +Make sure all the tests are all green! _inkgd_ uses [Gut] to run tests. Adding +tests to your PR is not expected, but feel free to do so 😉. [Gut]: https://github.com/bitwes/Gut #### Debugging -When debugging through the example project, don't forget to set `SHOULD_LOAD_IN_BACKGROUND = false` in `ink_runner.gd` since Godot's debugger doesn't work when threads are involved. +When debugging through the example project, don't forget to set +`InkPlayer.loads_in_background` to `false` in `ink_runner.gd` since Godot's +debugger doesn't work when threads are involved. ### Git branching model & pull requests -_inkgd_ has a very loose branching model. All improvements and fixes happen in `master`, since there isn't a real need to support different versions. Branches are created for two reasons: +_inkgd_ has a very loose branching model. All improvements and fixes happen in +`main`, since there isn't a real need to support different versions. Branches +are created for two reasons: -1. to deal with new features or large fixes, these will eventually be merged back into master; +1. to deal with new features or large fixes, these will eventually be merged + back into master; 2. to keep legacy code working with older versions of Godot -Pull requests need to focus on specific new features, changes or fixes. Keep them short and try to keep the number of files involved as low as possible, to ensure that the code review will be manageable. +Pull requests need to focus on specific new features, changes or fixes. Keep +them short and try to keep the number of files involved as low as possible, to +ensure that the code review will be manageable. -If you are making a non-trivial changes, which will require back and forth exchanges on the PR, the maintainer will often ask you to create (or move) your PR against a specific branch. The feature can then be dealt with in isolation. Therefore, you shouldn't merge any subsequent commit added to `master` into your PR without discussing it first with the maintainer. +If you are making a non-trivial changes, which will require back and forth +exchanges on the PR, the maintainer will often ask you to create (or move) your +PR against a specific branch. The feature can then be dealt with in isolation. +Therefore, you shouldn't merge any subsequent commit added to `main` into your +PR without discussing it first with the maintainer. ### License & contribution -_inkgd_ is licensed under the MIT License. Please use follow the header style (which mentions the license) when creating new files. +_inkgd_ is licensed under the MIT License. Please use follow the header style +(which mentions the license) when creating new files. Please don't be shy and credit yourself when you make a pull request. 👏 diff --git a/docs/source/advanced/migrating_to_godot_ink.rst b/docs/source/advanced/migrating_to_godot_ink.rst new file mode 100644 index 00000000..2192ace7 --- /dev/null +++ b/docs/source/advanced/migrating_to_godot_ink.rst @@ -0,0 +1,4 @@ +Migrating to *godot-ink* +======================== + +To be added. \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 2401b6cd..5b5caffc 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -44,6 +44,7 @@ If you prefer a more hands-on approach, feel free to tinker with the advanced/differences_between_api advanced/error_management advanced/performance + advanced/migrating_to_godot_ink .. toctree:: :maxdepth: 2