mirror of
https://github.com/godotengine/godot-docs.git
synced 2026-01-05 22:09:56 +03:00
Contributing: improve bugsquad and docs guidelines
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*, *UWP*
|
||||
|
||||
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,85 +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.
|
||||
|
||||
Contribute
|
||||
----------------------
|
||||
|
||||
Creating/Updating a documentation page or tutorial page is done via the `github repo <https://github.com/godotengine/godot-docs>`_.
|
||||
The README file contains all the information you need to get you started.
|
||||
|
||||
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 (and the ones on the repo).
|
||||
|
||||
Titles
|
||||
------
|
||||
|
||||
Always begin pages with their title and a Sphinx reference name:
|
||||
|
||||
::
|
||||
|
||||
.. _doc_insert_your_title_here:
|
||||
|
||||
Insert your title here
|
||||
======================
|
||||
|
||||
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 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
|
||||
|
||||
Translating existing pages
|
||||
--------------------------
|
||||
|
||||
For the moment, only English documentation is supported. So localization is not possible right now.
|
||||
But please be patient, we are working on it ;) (`see issue #4 <https://github.com/godotengine/godot-docs/issues/4>`_)
|
||||
|
||||
**Remember** : even if Godot aims at being accessible to everyone, English is the most frequent language for documentation.
|
||||
|
||||
Important changes and discussions
|
||||
---------------------------------
|
||||
|
||||
You are welcome to correct mistakes or styles to respect these
|
||||
guidelines. However, in case of important changes: Use the forum, create a new topic with a link
|
||||
to the incriminated page and start discussing there about your remarks.
|
||||
|
||||
Licence
|
||||
-------
|
||||
|
||||
This documentation and every page it contains is published under the terms of the
|
||||
Creative Commons BY 3.0 license.
|
||||
111
community/contributing/documentation_guidelines.rst
Normal file
111
community/contributing/documentation_guidelines.rst
Normal file
@@ -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