GNOME.org
 

[gnome-builder] doc: add contributing sections

commit 8a3aa10bff66bb27bf95954083137561e29e7fcc
Author: Christian Hergert <chergert redhat com>
Date:   Wed Mar 8 13:04:41 2017 -0800

    doc: add contributing sections

 doc/contributing/code.rst                        |   14 ++++
 doc/{contributing.rst => contributing/index.rst} |   25 ++-----
 doc/contributing/planning.rst                    |   18 +++++
 doc/contributing/writingdocs.rst                 |   80 ++++++++++++++++++++++
 doc/index.rst                                    |    2 +-
 doc/plugins/index.rst                            |    2 +
 6 files changed, 123 insertions(+), 18 deletions(-)
---
diff --git a/doc/contributing/code.rst b/doc/contributing/code.rst
new file mode 100644
index 0000000..5d37510
--- /dev/null
+++ b/doc/contributing/code.rst
@@ -0,0 +1,14 @@
+#################
+Contributing Code
+#################
+
+There are a lot of things that need to be written in Builder and we'd love to have your help in doing so.
+Take a look at :ref:`Creating Plugins<creating_plugins>` to learn how to write plugins.
+Most things in Builder are implemented as plugins while the scaffolding is written in C and foundin libide_.
+
+Plugins can be written in C, C++, Python, or Vala.
+
+If you're interested in working on ``libide``, the core C library behind Builder, you'll want to peruse the 
libide_ directory in the code-base.
+
+.. _libide: https://git.gnome.org//browse/gnome-builder/tree/libide/
+
diff --git a/doc/contributing.rst b/doc/contributing/index.rst
similarity index 72%
rename from doc/contributing.rst
rename to doc/contributing/index.rst
index 497aa24..01716a8 100644
--- a/doc/contributing.rst
+++ b/doc/contributing/index.rst
@@ -6,6 +6,14 @@ If you're interested in contributing to Builder and GNOME at large, we would lov
 Only with people like you can GNOME exist.
 We love seeing people that use GNOME transform into people that create GNOME.
 
+.. toctree::
+   :maxdepth: 1
+   :titlesonly:
+
+   planning
+   writingdocs
+   code
+
 IRC
 ===
 
@@ -35,23 +43,6 @@ Learn out how to install :ref:`via-jhbuild` in our installation documentation.
 Currently, JHBuild is how we recommend contributing to Builder.
 We do expect this to change very soon in that you'll be able to easily contribute to Builder from our 
flatpak-version of Builder.
 
-Improve This Documentation
-==========================
-
-One great way to learn about a software project is to try to document it!
-Writing great documentation can be both challenging and rewarding.
-And writing great documentation requires you learn about the product.
-
-This is one way to improve things for the next person while you explore the code-base.
-You can find the documentation in the ``doc/`` directory of the `git repository`_.
-
-Planning And Project Management
-===============================
-
-Many of us that work on the Builder code-base are great at writing code.
-But we are not so great at managing schedules, planning feature priorities, and coordinating with other 
projects.
-Helping us do this in Builder will make you a shepard of geeks.
-
 .. _`Builder IRC channel`: irc://irc.gnome.org/#gnome-builder
 .. _`Builder Bug Tracker`: https://bugzilla.gnome.org/enter_bug.cgi?product=gnome-builder
 .. _`newcomer bugs`: 
https://bugzilla.gnome.org/buglist.cgi?bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&columnlist=component%2Cchangeddate%2Cbug_severity%2Cpriority%2Cshort_desc&keywords=newcomers&list_id=193415&order=changeddate%20DESC%2Ccomponent&product=gnome-builder&resolution=---
diff --git a/doc/contributing/planning.rst b/doc/contributing/planning.rst
new file mode 100644
index 0000000..0b8cb78
--- /dev/null
+++ b/doc/contributing/planning.rst
@@ -0,0 +1,18 @@
+###############################
+Planning and Project Management
+###############################
+
+Many of us that work on the Builder code-base are great at writing code.
+But we are not so great at managing schedules, planning feature priorities, and coordinating with other 
projects.
+Helping us do this in Builder will make you a shepard of geeks.
+
+Responsibilities
+================
+
+ * Helping us stay on schedule with GNOME releases and releasing tarballs on time.
+ * Ensure that we plan the feature before writing it.
+ * Helping to plan features on realistic timelines.
+ * Planning a roadmap that makes sense.
+   Some features do not matter unless other features are implemented first.
+ * Help us find new contributors and ensure that our community is healthy towards new recruits.
+
diff --git a/doc/contributing/writingdocs.rst b/doc/contributing/writingdocs.rst
new file mode 100644
index 0000000..e50097f
--- /dev/null
+++ b/doc/contributing/writingdocs.rst
@@ -0,0 +1,80 @@
+#####################
+Writing Documentation
+#####################
+
+We are using sphinix to write our new documentation.
+
+In ``conf.py`` you'll see that we use the theme from readthedocs.io.  That
+means you need to install that theme as well as sphinx to build the
+documetnation.
+
+.. code-block:: bash
+   :caption: Install dependencies for building documentation (Fedora 25)
+   :name: install-sphinx-deps-fedora
+
+   sudo dnf install python3-sphinx python3-sphinx_rtd_theme
+
+
+.. code-block:: bash
+   :caption: Now build the documentation with sphinx
+   :name: sphinx-build
+
+   [user@host gnome-builder/]$ cd doc
+   [user@host doc/]$ sphinx-build . _build
+   [user@host doc/]$ xdg-open _build/index.html
+
+The first command builds the documentation.
+Pay attention to warnings which will be shown in red.
+Some of them may be useful to help you track down issues quickly.
+
+To open the documentation with your web browser, use ``xdg-open _build/index.html``.
+
+Submitting Patches
+==================
+
+We will accept patches for documentation no matter how get them to us.
+However, you will save us a lot of time if you can:
+
+ * Create a patch with git.
+ * Create a new bug on `Builder Bugzilla`_ and attach the patch.
+
+Creating a Patch
+================
+
+First off, if you have not configured git to include your full name and email, do so like:
+
+.. code-block:: bash
+
+   $ git config --global user.name 'My Full Name'
+   $ git config --global user.email 'example example com'
+
+After you have modified the documentation to your liking, prepare the files to be committed to git.
+The add a short commit message and commit the files.
+
+.. code-block:: bash
+
+   [user@host doc/]$ git add path/to/file.rst
+   [user@host doc/]$ git commit -m 'doc: update example documentation'
+
+Now we can export the patch to be uploaded to `Builder Bugzilla`_
+
+.. code-block:: bash
+
+   [user@host doc/]$ git format-patch HEAD^
+
+At this point you'll see a file similar to ``0001-doc-update-example-documentation.patch`` in the current 
directory.
+We want to upload this patch to `Builder Bugzilla`_.
+
+Submitting a Patch
+==================
+
+Now that we have our patch file, we need to create a new bug.
+Head over to `Builder Bugzilla`_ and fill out the bug details.
+
+Just give a bit of information about what you documented, and then find the "Add an Attachment" section near 
the bottom.
+Upload the patch file you exported with ``git format-patch HEAD^`` above.
+
+Click "Submit Bug" and we'll take care of the rest!
+
+
+.. _`Builder Bugzilla`: https://bugzilla.gnome.org/enter_bug.cgi?product=gnome-builder&component=docs
diff --git a/doc/index.rst b/doc/index.rst
index 8c5b51d..3c80a27 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -20,5 +20,5 @@ Contents
    exploring
    plugins/index
    api/index
-   contributing
+   contributing/index
    credits
diff --git a/doc/plugins/index.rst b/doc/plugins/index.rst
index ad7c84d..3716dae 100644
--- a/doc/plugins/index.rst
+++ b/doc/plugins/index.rst
@@ -1,3 +1,5 @@
+.. _creating_plugins:
+
 ################
 Creating Plugins
 ################
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]