Contributing to the wiki

So, you’ve decided you want to edit the wiki. Awesome! This page will show you how to get started. Please follow the instructions that are most appropriate for you.

Cloning the wiki

Using repo

If you already have a LineageOS source tree checked out, then this step is done for you. The wiki’s git repository is present under $LINEAGE_SRC/lineage/wiki.

Using git

If you don’t have a LineageOS source tree on your device, then you can clone the wiki from GitHub to any directory you like. In this example, we’ll use ~/lineage_wiki.

Install Git

On Windows

Install Git for Windows.

On macOS

Install Git using the Git installer.

On Linux

You can install Git by running:

sudo apt-get install git

More specific instructions for different distributions can be found here.

Configure Git

Run:

git config --global user.name "Your Name"
git config --global user.email "youremail@example.com"
git clone https://github.com/LineageOS/lineage_wiki ~/lineage_wiki
cd ~/lineage_wiki
curl -Lo .git/hooks/commit-msg https://review.lineageos.org/tools/hooks/commit-msg
chmod +x .git/hooks/commit-msg

Making and previewing changes

You can now make changes in this folder using your favorite text editor. If you ever need to reset your folder to a known-good state, erasing your changes, just run:

git reset --hard HEAD

Preview using GitHub

This is probably the easiest method, but requires you to have forked the wiki repository, and have cloned from that.

Commit and preview your changes

Run:

git add .
git commit

An editor will pop up. In the first line, type a short (below 80 character) description of your changes, then put a blank line, and, if you want, a more detailed description of your changes. For example:

Add the contributing page

The contributing page will show people how they can edit our wiki, which
is important, since it wouldn't be much of a wiki without editors.

Save the file and exit the editor. Now upload your changes to GitHub:

git push origin

Preview your changes - you can see your fork of the wiki at http://yourusername.github.io/lineage_wiki.

Fixing mistakes

So, you’ve made your change, and you can look at the wiki on GitHub pages. But something’s wrong! You made a typo - or accidentally deleted something. Have no fear! You can fix it.

First, fix the mistake(s) you made. Then, to push them to GitHub:

git add .
git commit --amend

Your commit message should show up in an editor. You can edit it, or just quit the editor. Finally, run:

git push --force origin

Preview locally using docker

Install docker

Add docker keyring and install the package:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
sudo apt update
sudo apt install docker-ce

Add your user account to the docker group in order to use docker commands without prefixing sudo:

sudo gpasswd -a $USER docker
newgrp docker

Then log out of your user account and log back in or reboot to make the group membership changes take effect.

Build the docker image

This builds the docker image, which should only need to be done once:

cd $LINEAGE_SRC/lineage/wiki #Or to wherever you cloned the repository
docker build -t lineageos/wiki .

Edit the wiki

Each time that you want to edit the wiki, you will need to start a local web server running Jekyll:

cd $LINEAGE_SRC/lineage/wiki
docker run -p 4000:4000 -v $(pwd):/src -it lineageos/wiki

At this point you should be able to view the local Jekyll server.

Preview locally using rvm and jekyll

Install rvm

rvm is a great tool to isolate different usages of ruby from each other. During this setup, you will install ruby and a set of ruby modules (gems) which will be isolated from any other ruby use on the machine (now and in the future).

If you don’t have rvm already installed, go ahead and install it:

gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3
curl -sSL https://get.rvm.io | bash -s stable

Configure ruby for editing the wiki

These steps will configure and install the latest version of ruby MRI via rvm. All gems (modules) are stored in the namespace lineage_wiki and the environment will be configured to allow remote access to GitHub. Once configured, ruby will be installed and the required gems downloaded:

cd $LINEAGE_SRC/lineage/wiki
echo ruby > .ruby-version
echo lineage_wiki > .ruby-gemset
rvm install ruby
gem install bundler rails
bundle install

Edit the wiki

Each time that you want to edit the wiki, you will need to start a local web server running Jekyll:

source ~/.rvm/scripts/rvm
cd $LINEAGE_SRC/lineage/wiki
bundle exec jekyll serve --incremental

At this point you should be able to view the local Jekyll server.

Uploading your changes

LineageOS uses Gerrit to review proposed changes. Before you begin, you’ll need to create an account, and configure an SSH key (you will need to use the ed25519 type of key).

After you’ve done this, you can push your commits to Gerrit:

git remote add gerrit ssh://<gerritusername>@review.lineageos.org:29418/LineageOS/lineage_wiki
git push gerrit HEAD:refs/for/master

You can add the “Wiki Editors” group as reviewers (click on the little person to the right of “reviewers”). Someone will either: comment on the patch, asking for clarification or pointing out typos. You can reply to them, or fix any issues they point out, and then re-run:

git push gerrit HEAD:refs/for/master

Eventually, when your change looks perfect, someone will approve it, and submit it to the wiki. Awesome!