From d0113d26aaa4ae0101a0bfe954c3f810413284f6 Mon Sep 17 00:00:00 2001 From: Amin Bandali Date: Sun, 26 Jul 2020 03:13:40 -0400 Subject: first pass at edit instructions for the wiki --- edit.md | 99 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 edit.md (limited to 'edit.md') diff --git a/edit.md b/edit.md new file mode 100644 index 00000000..f43d2875 --- /dev/null +++ b/edit.md @@ -0,0 +1,99 @@ +This site is a wiki, editable by anyone on the planet. The pages are +written in markdown, and converted to HTML using the +[ikiwiki](//ikiwiki.info) wiki compiler. You are welcome and +encouraged to edit and help improve the site. + +**Important:** before proceeding any further, see the [[EmacsConf wiki +license terms|COPYING]] before pushing any changes. + +To edit the wiki, you need to install `git` if it is not installed on +your machine already. Then, you can clone the sources from any one of +the following addresses: + + ssh://anon@git.emacsconf.org:emacsconf-wiki + git://git.emacsconf.org/emacsconf-wiki + https://git.emacsconf.org/emacsconf-wiki + +Note that the `https://` access is read-only and does not allow +pushing changes, while the `ssh://` and `git://` methods allow pushes +as well. Even though `https://` access is read-only, it can be useful +if you would like to manually cross-check and compare the hashes of +commits with hashes of the commits of a clone over the insecure +`git://` protocol. + +We strongly recommend using `ssh://` (which is both secure and allows +pushes), and avoiding `git://` (no transport security) and `https://` +(read-only access). + +## SSH access (recommended method) + +To use the `ssh://` method, you need `openssh` installed on your +machine, which is available on virtually all GNU/Linux distributions +and other Unix-like operating systems like the BSDs. You also need to +download the ssh private key [[id_rsa_anon_git_emacsconf]] and install +it into `~/.ssh/` (the `.ssh` directory in your home directory). The +key fingerprint is `SHA256:XbUoLgO2YH9+phNPKvwq8w0Q/8NhaKfS/VE6pDwTPsM +anon@git.emacsconf.org`, and its randomart image is: + + +---[RSA 2048]----+ + | . | + | o . | + | + o . o . | + | . * + o o | + | . * S + . | + | + &.B.o | + | ..+ E=* | + | o.ooo@.o | + | +o++.. | + +----[SHA256]-----+ + +Note that `openssh` requires SSH private keys to be secured with +permissions that prevent other users on your machine from reading or +modifying them. + +To download the key and set appropriate permissions on it, you run +something along these lines in your terminal: + + wget https://emacsconf.org/id_rsa_anon_git_emacsconf + mkdir -p ~/.ssh/ + mv id_rsa_anon_git_emacsconf ~/.ssh/ + 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: + + ssh-keygen -lf ~/.ssh/id_rsa_anon_git_emacsconf + +Lastly, you need to create a `~/.ssh/config` file (if you don't have +one already) and add the following to it: + + Host front0.emacsconf.org + Port 22 + User git + IdentityFile ~/.ssh/id_rsa_anon_git_emacsconf + +The `Port 22` line is optional, since SSH uses port 22 by default. +However, the SSH server listens on ports 21, 22, 53, 81, 8000, and +8080 for your convenience if you need it. + +You're now all set and ready to clone the repository containing the +wiki sources. To do so, run: + + git clone anon@git.emacsconf.org:emacsconf-wiki + +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)). + +Now, go ahead and make your changes to the website sources in the +repository you just cloned. When you're done, do: + + git add X Y Z + git commit -m"descriptive commit message" + +where `X`, `Y`, and `Z` are the files you changes; and `descriptive +commit message` is, well, a descriptive text describing your changes. +When you are ready, push your changes by running `git push`, and if +all went well, your commit should be pushed and your changes appear on +the website within a few seconds. -- cgit v1.2.3