Contributing to Manual

From MEPIS Documentation Wiki

Jump to: navigation, search

Contents

Introduction

During the development cycle of a new release of MEPIS the User Manual needs updating to reflect changes made to your favourite Linux distribution.

Now, you could do this all via email and leave some poor soul(s) to filter through the suggestions for change to the current manual. Or, you could use a version control system (VCS) like those that have been used for decades in the largest software projects on the planet (think Operating Systems and so on).

There are many VCSs available, but for various reasons we have chosen git and its associated hosting site github.

The main idea is that everyone who wishes to contribute will download the most recent version of the manual to their computer. Then, they make all the edits they like and, when they are happy with changes, they will 'push' the edits back up to the main repository for the manual. A 'manager' of the main repository will then be able to quickly go through all the contributions and 'merge' them into one coherent document.

There are two models that can be used in managing these changes: Fork & Pull or Shared Repository. The Fork & Pull model is described well here, but we will be using the alternative Shared repository model.

Set up Git and the Github.com Account

To make use of the Shared repository model for the MEPIS manual, do the following steps (only needs to be done once):

  1. Create an account on http://github.com
  2. Install the git-core package via Synaptic.
  3. Setup SSH keys: http://help.github.com/linux-key-setup/
  4. Introduce yourself to git (so that changes will be marked) by executing these commands in a Konsole:
 git config --global user.name "YourName"
 git config --global user.email "YourName@demo.com"

Github Playground Repo

If you're new to version control software and would like to experiment first, try the community playground repository at https://github.com/MEPIS-Community/git-playground. It's based on an old version of the manual so it's not that different from the main Manual repository. To get it type this command in a console session:

git clone git@github.com:MEPIS-Community/git-playground.git

This will create a directory called git-playground in your current directory.

Note: any changes you make are not monitored nor verified and will not make it into the main repository. To start contributing to the main repository it'll be best to delete the git-playground directory and then follow the instructions below.

Download the MEPIS User Manual from Git Repo

Get the files. The main repository for the MEPIS user manual is at https://github.com/MEPIS-Community/MEPIS-User-Manual and to get it to your computer use the following command in Konsole:

git clone git@github.com:MEPIS-Community/MEPIS-User-Manual.git

Editing

Once the git clone command finished you can cd to the project folder and start editing:

cd MEPIS-User-Manual

You can now modify and add files in that folder. Git doesn't track new files automatically, so when you add a new file you need to run this command:

git add filename

or:

git add .

to add tell git to track the file. The git add . command adds all the files in the directory and its sub-directories. Alternatively git add * adds all the files from the directory without adding the files from sub-directories.

Once you are done editing, you need to commit:

git commit -am "descriptive commit message"

Switches:
-a -- stage all modified and deleted files
-m -- is for adding a comment line

At this point, don't worry about making mistakes as you can always go back to a previous version without anyone seeing them as all the changes are locally stored. You can also start again from scratch, if you want. Feel free to experiment and try things out. Nothing is ever lost as long as you commit regularly.

Pushing Changes to the Main Repository

Once you're happy with the changes you've made to your local copy of the files, you can 'push' them up to the main repository. A simple command

git push

will make your changes available for everyone to see.

Before you're able to 'push' your changes you need to be added as a team member in Github. Please make a request in the MEPIS Documentation section of the MEPIS Community forum.

Important it's always a good idea to do a pull before you do a push to ensure that you have the latest upstream changes locally. The command (from inside the MEPIS-User-Manual directory) is:

git pull

Tips and tricks

Branching

If you want to do experimental edits keeping the main branch unchanged you can always create another branch like this:

git branch myedits

and change the branch to myedits with this command:

git checkout myedits

or do both steps in one command:

git checkout -b myedits

You can always revert to the original branch, you won't lose your work as long as you commit all your changes. Once you are done editing your branch and you are ready to merge the changes to the main branch you can do this, switch to the main branch with this command:

git checkout release11-dev

Merge edits with:

git merge myedits

Managing changes

A handy method for managing changes is to install Giggle from the repos. To use it, enter the directory of your git project, click F4 to open a terminal, and type

giggle

You will then see a directory on the left, the main code window, and the committed changes in the bottom panel. Double-click on a commit to be able to step through the changes.

Other Community Projects

As well as contributing to the manual there are other Community Projects which will benefit from community effort:

These projects require a bit more effort and some knowledge of bash or C++/Qt, but as always everyone is free to dowload the code and hack away at it, learning as they go along. This is beauty of Open Source projects :)

Links

Personal tools