Commit 8a3aa10b authored by Christian Hergert's avatar Christian Hergert
Browse files

doc: add contributing sections

parent b95a5a37
#################
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/
......@@ -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=---
......
###############################
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.
#####################
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
......@@ -20,5 +20,5 @@ Contents
exploring
plugins/index
api/index
contributing
contributing/index
credits
.. _creating_plugins:
################
Creating Plugins
################
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment