Documentation Team » Guide »

Contributing to the Desktop Help

Get Started

1. Install git.
2. Set up git:

    $ git config --global user.email yourname@somewhere.com

    $ git config --global user.name "Your Name"

3. Log into GitLab and add your SSH key to GitLab.

4. Fork the gnome-user-docs repository by following the GitLab help.

5. Clone your fork of the gnome-user-docs repository:

    $ git clone git@gitlab.gnome.org:YOUR-USERNAME/gnome-user-docs.git

6. Create a topic branch for the changes you want to make in the repository.

7. Go into the directory which contains the Mallard files (.page files) by typing:

    $ cd gnome-user-docs/gnome-help/C/

   To view the current state of the desktop help from the index page type:

    $ yelp index.page

Editing existing pages

1. To view the Mallard source and/or make changes to existing pages you can use a text editor (like Gedit):

    $ gedit <pagename>

   • Do not include the angle brackets.
   • Make your edits.
2. To view your changes using the help viewer:

    $ yelp <pagename>

   If the page doesn't show up in yelp, there may be a problem with the Mallard markup. If this happens, check the terminal output for errors (the error and line number of the error will be output to the terminal).

Creating new pages

1. Install yelp-tools.

2. To create a new topic page name <newtopic> with <Title> type:

    $ yelp-new task <taskname> "<Page Title>"

   • Do not include the angle brackets. <taskname> becomes the name of the .page file.

3. Add the new page to git:

    $ git add <newpagename>

   • Make sure you add each new page you create. If you forget, it will not be included in the .patch file, and your hard work may get lost.
   • You will notice the new page already has your name inserted as the author. Delete any of the boiler-plate markup or paragraphs which you do not need, and write, write, write.

Pre-commit checks

These pre-commit checks will save the person reviewing your patch time and help you get your patch committed faster. The first is just a visual check, the second requires you to have yelp-tools installed, while the last is the most difficult as it depends on your having some other software installed and need to be able to understand output from a terminal.

• Check that you have updated the <revision> tag and added yourself to the credits

• Use yelp-tools to 'yelp-check validate' the pages and 'yelp-check links' to check that xref (internal) links are valid

• Build gnome-user-docs to make sure the gnome-help/Makefile.am is correct

  1. Open a terminal

  2. 'cd' into the gnome-user-docs directory (for example, 'cd work/gnome-user-docs')

  3. Run './autogen.sh'

  4. Run 'make'

  5. Check for errors in the output

Create a merge request

1. When you are happy with your changes, commit your them. In the Terminal, type:

    $ git commit -a -m "A commit message goes here explaining what your changes are.  If your changes fix an issue, include the issue #."

   The commit message should be less than 50 characters, but informative.
2. When committed, push your changes to your repository fork:

    $ git push --set-upstream origin YOUR-TOPIC-BRANCH

3. Create a merge request by clicking the link in the terminal, or follow the GitLab help.

NOTE: You can make multiple commits, and then create one merge request for all of them.

If you are working along and want to see a log of the commits, you can type:

$ git log

Once your merge request is submitted, a member of the GNOME Documentation Team will get back to you with comments, suggestions and edits, and we can work together on finalizing the topics you wrote. They will then be added to the Desktop Help.

CategoryDocumentationProject