Why isn't this wiki open to all users for editing?

The one benefit of having had the xastir.org wiki in the past was that it could be a community-built documentation site, with users easily creating and editing pages.

Unfortunately, it was also a way for bots and spammers to attack the site. In 2014 it got so bad that several times every day the administrators were deleting spam pages and bot-made accounts. Some of these spam accounts were also defacing the actual pages on the wiki. As a result, we had to shut down the automated registration system and require all users to request an account directly from an administrator. Few did, and community contributions ground to a halt --- as did any maintenance of pages that other contributors had created and then abandoned.

But I want to contribute to this wiki now!

Direct editing of the wiki can't be done except by developers of the project (those who have write access to the code repository itself). We are reluctant to add too many people to this cadre just so they can edit the wiki freely. But you can still contribute by editing files locally and feeding back your changes to the developers in a Github Issue.

Clone the wiki locally

At the bottom right of any wiki page on Github, you'll see a URL for "Clone this wiki locally": Copy and paste that URL into a git command:

git clone https://github.com/Xastir/Xastir.wiki.git

and you now have a git clone of the repository as it existed when you did the clone command.

Do your edits locally, committing as you go

It is best if you now do your edits on a branch:

git checkout -b mybranch

You can now edit the files in this repo to your heart's content, possibly viewing them in a Gollum instance (see Offline-Docs) to check formatting. You can even use Gollum to edit the files and preview them as you go.

As you work, commit your changes to your local clone. You can do this through Gollum directly: every time you save an edit in gollum, it automatically commits your work to your local git clone. Or you can use

git status   # check that only the files you WANT changed have changed
git add .
git commit   # add a helpful commit message

Create a patch to feed back to the developers

But your changes are still all just local. You now need to create a patch file:

git format-patch master

This will create a patch file for each commit you've done since your branch was created. They'll be named stuff like "0001-First-line-of-your-commit-message.patch".

Attach your patches to a Github issue

Go onto github, open an Issue in Xastir's "Issues" section, and attach your patch (all the files it created) to that issue with an explanation of why you think your contribution should be accepted.

We'll review the change and apply it if we accept your patches.

After you finish your changes

You will want to switch back to the master branch after you've completed your edits.

git checkout master

Keep your clone up to date

While checked out on the master branch, simply pull any updates since your last update:

git pull