mirror of
https://github.com/stan220/godot-docs.git
synced 2026-09-08 18:29:11 +00:00
Contributing: improve bugsquad and docs guidelines
(cherry picked from commit f24e9803cd)
This commit is contained in:
Rémi Verschelde
@@ -11,17 +11,24 @@ hesitate to propose modifications to the following guidelines.
|
||||
Issues management
|
||||
-----------------
|
||||
|
||||
GitHub proposes three features to manage issues:
|
||||
GitHub proposes various features to manage issues:
|
||||
|
||||
- Set one or several labels from a predefined list
|
||||
- Set one milestone from a predefined list
|
||||
- Keep track of the issue in the project dashboard
|
||||
- Define one contributor as "assignee" among the Godot engine
|
||||
organization members
|
||||
|
||||
As the Godot engine organization on GitHub currently has a restricted
|
||||
number of contributors and we are not sure yet to what extent we will
|
||||
use it or OpenProject instead, we will not use assignees extensively for
|
||||
the time being.
|
||||
number of contributors, we do not use assignees extensively for now. All
|
||||
contributors are welcome to take on any issue, if relevant after mentioning
|
||||
it on the issue ticket and/or discussing the best way to resolve it with
|
||||
other developers.
|
||||
|
||||
For the time being we do not use the project dashboard feature either.
|
||||
|
||||
As far as possible, we try to assign labels (and milestones, when relevant)
|
||||
to both issues and pull requests.
|
||||
|
||||
Labels
|
||||
~~~~~~
|
||||
@@ -45,53 +52,61 @@ The following labels are currently defined in the Godot repository:
|
||||
discussion to define what exactly should be done to address the
|
||||
topic.
|
||||
- *Documentation*: issue related to the documentation. Mainly to request
|
||||
documentation that don't exist yet.
|
||||
enhancements in the API documentation. Issues related to the ReadTheDocs
|
||||
documentation should be filed on the
|
||||
`godot-docs <https://github.com/godotengine/godot-docs>`_ repository.
|
||||
- *Enhancement*: describes a proposed enhancement to an existing
|
||||
functionality.
|
||||
- *Feature proposal*: describes a wish for a new feature to be
|
||||
implemented.
|
||||
- *Junior job*: the issue is *assumed* to be an easy one to fix, which makes
|
||||
it a great fit for junior contributors who need to become familiar with
|
||||
the code base.
|
||||
- *Needs rebase*: the issue need a git rebase to be merged.
|
||||
- *Needs testing*: the issue/pull request could not be completely tested
|
||||
and thus need further testing. This can mean that it needs to be tested
|
||||
on different hardware/software configurations or even that the steps to
|
||||
reproduce are not certain.
|
||||
- *PR welcome*: you are welcome to work on this issue and propose a pull request.
|
||||
Note that this **doesn't** mean you can't work on bugs without this label.
|
||||
- *Reviewed*: The pull request has been reviewed by a contributor.
|
||||
- *Tracker*: issue used to track other issues (like all issues related to the plugin system).
|
||||
- *PR welcome*: you are welcome to work on this issue and propose a pull
|
||||
request. Note that this **doesn't** mean you can't work on bugs without
|
||||
this label.
|
||||
- *Tracker*: issue used to track other issues (like all issues related to
|
||||
the plugin system).
|
||||
- *Usability*: issue that directly impact user usability.
|
||||
|
||||
The categories are used for general triage of the issues. They can be
|
||||
combined in some way when relevant, e.g. an issue can be labelled
|
||||
*Enhancement* and *Usability* at the same time if it's an issue to improve usability.
|
||||
Or *Feature proposal* and *Discussion* if it's a non-consensual feature request, or one that is not
|
||||
precise enough to be worked on.
|
||||
*Enhancement* and *Usability* at the same time if it's an issue to improve
|
||||
usability. Or *Feature proposal* and *Discussion* if it's a non-consensual
|
||||
feature request, or one that is not precise enough to be worked on.
|
||||
|
||||
**Topics:**
|
||||
|
||||
- *Assetlib*: relates to issues with the asset library.
|
||||
- *Audio*: relates to the audio features (low and high level).
|
||||
- *Buildsystem*: relates to building issues, either linked to the SCons
|
||||
buildsystem or to compiler peculiarities.
|
||||
- *Core*: anything related to the core engine. It might be further
|
||||
split later on as it's a pretty big topic.
|
||||
- *Drivers*: relates to issues with the drivers used by the engine.
|
||||
- *Editor*: relates to issues in the editor (mainly UI).
|
||||
- *GDNative*: relates to the GDNative module.
|
||||
- *GDScript*: relates to GDScript.
|
||||
- *Physics*: relates to the physics engine (2D/3D).
|
||||
- *Plugin*: relates to problems encountered while writing plugins.
|
||||
- *Porting*: relates to some specific platforms.
|
||||
- *Rendering*: relates to the 2D and 3D rendering engines.
|
||||
- *Visual script*: relates issues with visual scripting.
|
||||
- *VisualScript*: relates to issues with the visual scripting language.
|
||||
|
||||
Issues would typically correspond to only one topic, though it's not
|
||||
unthinkable to see issues that fit two bills. The general idea is that
|
||||
there will be specialized contributors teams behind all topics, so they
|
||||
can focus on the issues labelled with their team topic.
|
||||
can focus on the issues labelled with their team's topic.
|
||||
|
||||
**Platforms:** *Android*, *HTML5*, *iOS*, *Linux*, *OS X*, *Windows*, *Winrt*
|
||||
|
||||
By default, it is assumed that a given issue applies to all platforms.
|
||||
If one of the platform labels is used, it is the exclusive and the
|
||||
If one of the platform labels is used, it is then exclusive and the
|
||||
previous assumption doesn't stand anymore (so if it's a bug on e.g.
|
||||
Android and Linux exclusively, select those two platforms).
|
||||
|
||||
@@ -101,8 +116,12 @@ Milestones
|
||||
Milestones correspond to planned future versions of Godot for which
|
||||
there is an existing roadmap. Issues that fit in the said roadmap should
|
||||
be filed under the corresponding milestone; if they don't correspond to
|
||||
any current roadmap, they should be set to *Later*. As a rule of thumb,
|
||||
an issue corresponds to a given milestone if it concerns a feature that
|
||||
is new in the milestone, or a critical bug that can't be accepted in any
|
||||
any current roadmap, they should be left without milestone. As a rule of
|
||||
thumb, an issue corresponds to a given milestone if it concerns a feature
|
||||
that is new in the milestone, or a critical bug that can't be accepted in any
|
||||
future stable release, or anything that Juan wants to work on right now
|
||||
:)
|
||||
|
||||
Contributors are free to pick issues regardless of their assigned milestone;
|
||||
if a fix is proposed for a bug that was not deemed urgent and thus without
|
||||
milestone, it would likely still be very welcome.
|
||||
|
||||
@@ -1,147 +0,0 @@
|
||||
.. _doc_doc_and_l10n_guidelines:
|
||||
|
||||
Documentation and localisation guidelines
|
||||
=========================================
|
||||
|
||||
This page describes the rules to follow if you want to contribute Godot
|
||||
Engine by writing documentation or translating existing documentation.
|
||||
|
||||
What is a good documentation?
|
||||
-----------------------------
|
||||
|
||||
A good documentation is well written in plain English and well-formed
|
||||
sentences. It is clear and objective.
|
||||
|
||||
A documentation page is not a tutorial page. We differentiate these
|
||||
concepts by these definitions:
|
||||
|
||||
- *Tutorial*: a page aiming at explaining how to use one or more
|
||||
concepts in Godot Editor in order to achieve a specific goal with a
|
||||
learning purpose (ie. "make a simple 2d Pong game", "apply forces to
|
||||
an object"...)
|
||||
- *Documentation*: a page describing precisely one and only one concept
|
||||
at the time, if possible exhaustively (ie. the list of methods of the
|
||||
Sprite class for example).
|
||||
|
||||
You are free to write the kind of documentation you wish, as long as you
|
||||
respect the following rules.
|
||||
|
||||
Create a new wiki page
|
||||
----------------------
|
||||
|
||||
**TODO: Needs review for Sphinx doc**
|
||||
|
||||
Creating a new documentation page or tutorial page is easy. The
|
||||
following rules must be respected:
|
||||
|
||||
- Choose a short and explicit title
|
||||
- Respect the grammar and orthography
|
||||
- Make use of the :ref:`doc_wiki_syntax`
|
||||
|
||||
Try to structure your page in order to enable users to include a page
|
||||
directly in another page or even forum posts using the include wiki
|
||||
syntax. For example, the syntax to include the page you are reading is
|
||||
:
|
||||
|
||||
::
|
||||
|
||||
:ref:`the cool documentation guidelines <doc_doc_and_l10n_guidelines>`
|
||||
|
||||
Titles
|
||||
~~~~~~
|
||||
|
||||
Please always begin pages with their title and a reference based on the
|
||||
file name (which should ideally be the same as the page title):
|
||||
|
||||
::
|
||||
|
||||
.. _insert_your_title_here:
|
||||
|
||||
Insert your title here
|
||||
======================
|
||||
|
||||
Also, avoid American CamelCase titles: titles' first word should begin
|
||||
with a capitalized letter, and every following word should not. Thus,
|
||||
this is a good example:
|
||||
|
||||
- Insert your title here
|
||||
|
||||
And this is a bad example:
|
||||
|
||||
- Insert Your Title Here
|
||||
|
||||
Only project names (and people names) should have capitalized first
|
||||
letter. This is good:
|
||||
|
||||
- Starting up with Godot Engine
|
||||
|
||||
And this is bad:
|
||||
|
||||
- Starting up with godot engine
|
||||
|
||||
Note for non-English authors
|
||||
----------------------------
|
||||
|
||||
For the moment, we will not pull contributed pages that have no English counterpart.
|
||||
We aim to provide a tool to help translators and writers determine whether certain languages have pages that do not exist in other languages, but this is not done yet. When it is done, we will open the documentation to new contributions.
|
||||
|
||||
Please be patient, we are working on it. ;)
|
||||
|
||||
..
|
||||
If you intend to create a new page in your language, you are asked to
|
||||
firstly create the corresponding English page if it doesn't already
|
||||
exist. **Do it even if you will not write it yourself, just leave it
|
||||
blank.** Only then, create the corresponding page in your own
|
||||
language. Maybe later, another contributor will translate your new
|
||||
page to English.
|
||||
|
||||
**Remember** : even if Godot aims at being accessible to everyone,
|
||||
English is the most frequent language for documentation.
|
||||
|
||||
Translating existing pages
|
||||
--------------------------
|
||||
|
||||
**New guidelines will come soon !**
|
||||
|
||||
..
|
||||
**TODO: Needs review for Sphinx doc**
|
||||
|
||||
You are very welcome to translate existing pages from English to your
|
||||
language, or from your language to English. If these guidelines were
|
||||
respected, an English page already exists for every page of this wiki,
|
||||
even if it is empty. To translate an existing page, please follow these
|
||||
few rules:
|
||||
|
||||
- Respect the grammar and orthography
|
||||
- Make use of the :ref:`doc_wiki_syntax`
|
||||
- Re-use images
|
||||
- Always keep the structure of the English page (if it is written yet,
|
||||
follow the structure of the original language page you are
|
||||
translating from).
|
||||
|
||||
To translate an existing page, simply copy its original content. Then,
|
||||
create the new page in the section of your language, copy the English
|
||||
content in it and start translating.
|
||||
|
||||
Please add a line at the very beginning of your translation, linking
|
||||
to the English base page you translate from:
|
||||
|
||||
Traduction de ![[Godot Engine:Creating 2D Games]]
|
||||
|
||||
The previous link is of the form ![[<project name>:<project page>]] which
|
||||
enables you to add a link to a page located in an other project. Here,
|
||||
"Godot Engine" is the English project.
|
||||
|
||||
Important changes and discussions
|
||||
---------------------------------
|
||||
|
||||
You are welcome to correct mistakes or styles to respect these
|
||||
guidelines. However, in case of important changes, please do not start a
|
||||
discussion on this page: use the forum, create a new topic with a link
|
||||
to the incriminated page and start discussing there about your remarks.
|
||||
|
||||
Licence
|
||||
-------
|
||||
|
||||
This wiki and every page it contains is published under the terms of the
|
||||
Creative Commons BY 3.0 license.
|
||||
@@ -0,0 +1,111 @@
|
||||
.. _doc_documentation_guidelines:
|
||||
|
||||
Documentation guidelines
|
||||
========================
|
||||
|
||||
This page describes the rules to follow if you want to contribute to Godot
|
||||
Engine by writing or reviewing documentation, or by translating existing
|
||||
documentation.
|
||||
|
||||
How to contribute
|
||||
-----------------
|
||||
|
||||
Creating or modifying documentation pages is mainly done via the
|
||||
`godot-docs GitHub repository <https://github.com/godotengine/godot-docs>`_.
|
||||
The HTML (or PDF and EPUB) documentation is generated from the .rst files
|
||||
(reStructuredText markup language) in that repository. Modifying those pages
|
||||
in a pull request and getting it merged will trigger a rebuild of the online
|
||||
documentation.
|
||||
|
||||
.. seealso:: For details on Git usage and the pull request workflow, please
|
||||
refer to the :ref:`doc_pr_workflow` page. Most of what it
|
||||
describes regarding the main godotengine/godot repository is
|
||||
also valid for the docs repository.
|
||||
|
||||
The README.md file contains all the information you need to get you started,
|
||||
please read it. In particular, it contains some tips and tricks and links to
|
||||
reference documentation about the reStructuredText markup language.
|
||||
|
||||
.. warning:: If you want to edit the **API reference**, please note that it
|
||||
should *not* be done in the godot-docs repository. Instead, you
|
||||
should edit the ``doc/base/classes.xml`` XML file of Godot's
|
||||
main repository. This file is then later used to generate the
|
||||
in-editor documentation as well as the API reference of the
|
||||
online docs.
|
||||
|
||||
What makes good documentation?
|
||||
------------------------------
|
||||
|
||||
Documentation should be well written in plain English, using well-formed
|
||||
sentences and various levels of sections and subsections. It should be clear
|
||||
and objective.
|
||||
|
||||
We differentiate tutorial pages from other documentation pages by these
|
||||
definitions:
|
||||
|
||||
- Tutorial: a page aiming at explaining how to use one or more concepts in
|
||||
the editor or scripts in order to achieve a specific goal with a learning
|
||||
purpose (e.g. "Making a simple 2d Pong game", "Applying forces to an
|
||||
object").
|
||||
- Documentation: a page describing precisely one and only one concept at a
|
||||
time, if possible exhaustively (e.g. the list of methods of the
|
||||
Sprite class, or an overview of the input management in Godot).
|
||||
|
||||
You are free to write the kind of documentation you wish, as long as you
|
||||
respect the following rules (and the ones on the repo). In particular, you
|
||||
can contribute tutorials in the "Community" section of the docs, where they
|
||||
could be merged relatively easily, improved by other contributors and
|
||||
eventually moved to an "official" section if relevant.
|
||||
|
||||
Titles
|
||||
------
|
||||
|
||||
Always begin pages with their title and a Sphinx reference name:
|
||||
|
||||
::
|
||||
|
||||
.. _doc_insert_your_title_here:
|
||||
|
||||
Insert your title here
|
||||
======================
|
||||
|
||||
The reference allows to link to this page using the ``:ref:`` format, e.g.
|
||||
``:ref:`doc_insert_your_title_here``` would link to the above example page
|
||||
(note the lack of leading underscore in the reference).
|
||||
|
||||
Also, avoid American CamelCase titles: title's first word should begin
|
||||
with a capitalized letter, and every following word should not. Thus,
|
||||
this is a good example:
|
||||
|
||||
- Insert your title here
|
||||
|
||||
And this is a bad example:
|
||||
|
||||
- Insert Your Title Here
|
||||
|
||||
Only project, people and node class names should have capitalized first
|
||||
letter.
|
||||
|
||||
Translating existing pages
|
||||
--------------------------
|
||||
|
||||
For the moment, only English documentation is provided. We want to propose
|
||||
localized documentation in the future, but this is not a priority for now.
|
||||
Indeed, since the English documentation is still evolving a lot as the
|
||||
community improves it and make it more professional, we prefer that
|
||||
translators do not spend too much time on it, as their translated
|
||||
documentation might quickly grow out of sync with the original.
|
||||
|
||||
When the English documentation is ready for translations, we will provide
|
||||
tools to simplify the work of translators by tracking changes to the English
|
||||
docs that they should translate on their end.
|
||||
|
||||
Licence
|
||||
-------
|
||||
|
||||
This documentation and every page it contains is published under the terms of
|
||||
the Creative Commons Attribution 3.0 license (CC-BY-3.0), with attribution to
|
||||
"Juan Linietsky, Ariel Manzur and the Godot community".
|
||||
|
||||
By contributing to the documentation on the GitHub repository, you agree that
|
||||
your changes are distributed under this license.
|
||||
@@ -8,5 +8,5 @@ Contributing
|
||||
ways_to_contribute
|
||||
pr_workflow
|
||||
bug_triage_guidelines
|
||||
doc_and_l10n_guidelines
|
||||
documentation_guidelines
|
||||
updating_the_class_reference
|
||||
|
||||
@@ -178,5 +178,4 @@ There are two separate resources referred to as "documentation" in Godot:
|
||||
are generated from plain text files in the reStructured Text (rst) format,
|
||||
to which you can contribute via pull requests on the
|
||||
`godot-docs <https://github.com/godotengine/godot-docs>`_ GitHub repository.
|
||||
|
||||
.. TODO. See :ref:`doc_documentation_guidelines` for more details.
|
||||
See :ref:`doc_documentation_guidelines` for more details.
|
||||
|
||||
Reference in New Issue
Block a user