edit: improve the instructions

1 files changed, 87 insertions, 19 deletions

diff --git a/edit.md b/edit.md
index 593f8d41..bf6687fc 100644
--- a/edit.md
+++ b/edit.md
@@ -26,9 +26,9 @@ commits with hashes of the commits of a clone over the insecure
 
 We strongly recommend using `ssh://` (which is both secure and allows
 pushes), and avoiding `git://` (no transport security) and `https://`
-(read-only access).
+(read-only access) when possible.
 
-## SSH access (recommended method)
+## First time SSH setup (recommended method)
 
 To use the `ssh://` method, you need `openssh` installed on your
 machine, which is available on virtually all GNU/Linux distributions
@@ -65,7 +65,7 @@ something along these lines in your terminal:
     chmod 600 ~/.ssh/id_rsa_anon_git_emacsconf
 
 You can show the fingerprint of the key to examine with the expected
-fingerprint mentioned ealier using:
+fingerprint mentioned earlier using:
 
     ssh-keygen -lf ~/.ssh/id_rsa_anon_git_emacsconf
 
@@ -86,27 +86,95 @@ wiki sources.  To do so, run:
 
     git clone anon@git.emacsconf.org:emacsconf-wiki
 
+Now that you have cloned the sources of the wiki to your machine, you
+can type `cd emacsconf-wiki` to change directory to the wiki sources,
+and start making changes.
+
 If this is your first time using Git, please set valid and real
 `user.name` and `user.email` configurations options (see [Getting
 Started - First-Time Git
-Setup](//git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup)).
+Setup](//git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup)
+for more details and instructions).
 
-Now, go ahead and make your changes to the website sources in the
-repository you just cloned.  When you're done, do:
+## Pulling in changes by others
 
-    git add X Y Z
-    git commit -m"descriptive commit message"
+If you just cloned the `emacsconf-wiki` repository using `git clone`
+moments ago, you can skip this section.  I still recommend reading it
+now though, as it contains important information for your future
+edits.
+
+Git is a distributed version control system, meant to allow many
+people to simultaneously work on a repository, and ultimately
+consolidate their changes together into a canonical copy of the
+repository.  For our purposes, the canonical `emacsconf-wiki`
+repository is the one on the `git.emacsconf.org` server.
+
+It is quite likely that others have made changes to the
+`emacsconf-wiki` since the last time you made changes, and making new
+changes without first consolidating the changes by others is likely to
+cause headaches for you down the line.
+
+As such, before making new changes to the wiki, it's always a good
+idea to check for potential changes by others, by fetching the latest
+state of the canonical repository from the `git.emacsconf.org` server.
+You can do so by running `git fetch`.  You can then see a compact list
+of changes using `git log --pretty=short ..origin`.  You can omit the
+`--pretty=short` to get a more details about the changes.  To learn
+more about `git log` you can read its manual by running `man git-log`.
+
+To see a diff of the changes, run `git diff ..origin`.
 
-where `X`, `Y`, and `Z` are the files you changed; and `descriptive
-commit message` is, well, a descriptive text describing your
-changes. :-)
+Having examined the changes, you can now try pulling them into your
+local repository.  In this workflow, you should almost always be able
+to run `git merge --ff` to do that.  If for some reason there are any
+merge conflicts, Git will ask you to resolve them.  There are a great
+many articles around the web explaining how to do that.
 
-When you are ready, and assuming you have read and agree with the
-license terms linked at the top of this page, you can push your
-changes by running `git push`.  If all goes well, your commit will be
-pushed, and your changes will appear on the website within a few
-seconds.
+If you really get stuck and cannot successfully pull in others'
+changes, the best approach would be to try looking for others running
+into similar situations online (e.g. on question boards) and learn how
+to resolve them.  If you're short of time, you can also rename your
+local copy of `emacsconf-wiki` repository to something else, clone the
+repository again, and proceed to make new changes.
+
+## Editing pages and committing changes
+
+The wiki pages are written in markdown, and you should be able to use
+any decent text editor ;-) to edit them.
+
+Once you're done making changes, do:
+
+    git add X Y Z
+    git commit -m"descriptive commit message"
 
-If you have any questions, or still cannot push to the wiki having
-followed the above instructions, don't hesitate to get in touch with
-[[bandali]].
+where `X`, `Y`, and `Z` are the names of the files you changed; and
+`descriptive commit message` is, well, a descriptive text describing
+your changes. :-)
+
+The first command tells git to get ready to record your changes to the
+said files, and the second command tells git to "commit" (record) your
+changes now.
+
+After making a commit, you can start making more changes, `add` and
+`commit` them, and so on.  These will all be only in your local
+repository, until you explicitly push them to the canonical
+repository.
+
+When you are ready to push your changes from your local copy of
+`emacsconf-wiki` to the canonical repository on `git.emacsconf.org`,
+and assuming you have read and agree with the license terms linked at
+the top of this page, you can push your changes by running `git push`.
+If all goes well, your commit will be pushed, and your changes will
+appear on the website within a few seconds.
+
+Note that the act of pushing commits using `git push` is an
+irreversible step and cannot be undone.  The effects of changes, of
+course, can be reversed by making a series of new changes that reverse
+the current changes.  Git even has a `revert` subcommand just for that
+(see `man git-revert`).
+
+## Have questions?
+
+If you have any questions, or are having trouble pushing your changes
+to the wiki despite following the above instructions, don't hesitate
+to get in touch with [[bandali]].