Contributing: improve bugsquad and docs guidelines

community/contributing/bug_triage_guidelines.rst

@@ -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.

community/contributing/doc_and_l10n_guidelines.rst

@@ -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.

community/contributing/documentation_guidelines.rst

@@ -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.

community/contributing/index.rst

@@ -8,5 +8,5 @@ Contributing
    ways_to_contribute
    pr_workflow
    bug_triage_guidelines
-   doc_and_l10n_guidelines
+   documentation_guidelines
    updating_the_class_reference

community/contributing/ways_to_contribute.rst

@@ -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.