imfreedom/contributors-guide

Add some documentation on repository hosting

22 months ago, Gary Kramlich
3e82406a692c
Parents 5a4431aaa06d
Children 723e60f85f8c
Add some documentation on repository hosting
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/repository-hosting.md Tue May 17 00:25:24 2022 -0500
@@ -0,0 +1,116 @@
+Title: Repository Hosting
+Slug: repository-hosting
+
+# Repository Hosting
+
+Currently the number of publicly accessible Mercurial repository hosting
+solutions is rather limited. To deal with this Instant Messaging Freedom hosts
+the canonical repositories for all of the projects under it's umbrella. It also
+provides repository hosting for the developers of that project, including
+crazy patch writers and Google Summer of Code students.
+
+However, Instant Messaging Freedom will not provide repository hosting for the
+general public. This is for many reasons, but the most important one is that we
+do not have the compute nor the human resources to be able to support such a
+thing.
+
+However, if you do not meet any of those requirements, you can see our
+[guide below](#sourcehut-repositories) for using [sourcehut](https://sr.ht/) to
+keep your own mirror of any Instant Messaging Freedom related repository.
+
+## Repository Management
+
+Once you have your own repository hosted somewhere, you're are going to need
+to be able to keep it in sync with the canonical repository. There are no tools
+to do this automatically for you, but it's relatively painless with a few
+simple tweaks.
+
+The following will work for any urls, but we're using the Instant Messaging
+Freedom's HGKeeper instance as an example.
+
+For this example, we're going to assume you have a copy of the Pidgin
+repository hosted at `keep.imfreedom.org/alice/pidgin` that you created by
+pushing your local clone via `hg push ssh://keep.imfreedom.org/alice/pidgin`.
+You can continue pushing commits that way, but there's an easier way.
+
+In the top directory of your local copy, you should have a `.hg` directory. In
+that directory is a file named `hgrc`. The `.hg/hgrc` file contains a list of
+all the remotes and a friendly name for them under the `[paths]` key. To make
+things easier, we can add your remote there.
+
+```ini
+[paths]
+default = https://keep.imfreedom.org/pidgin/pidgin
+alice = ssh://keep.imfreedom.org/alice/pidgin
+```
+
+Once you save this file you can now just type `hg push alice` and Mercurial
+will now push changes to `keep.imfreedom.org/alice/pidgin` over SSH.
+
+So this solves the initial problem, but we can make it even better by adding
+an additional `default-pushurl` remote to your `.hg/hgrc` file as well.
+
+```ini
+[paths]
+default = https://keep.imfreedom.org/pidgin/pidgin
+alice = ssh://keep.imfreedom.org/alice/pidgin
+default-pushurl = ssh://keep.imfreedom.org/alice/pidgin
+```
+
+This allows you to push to your copy of the repository by not specifying a
+remote name at all. a simple `hg push` will now use the value from the
+`default-pushurl` which we set to your respository. This now means that the
+only time you need to specify a remote name, is when you want to pull commits
+from your copy of the repository.
+
+To sync your repository with upstream, you can now just run
+`hg pull && hg push`. This will pull in all changesets from the canonical
+repository at `https://keep.imfreedom.org/pidgin/pidgin` and then push them to
+your copy of the repository at `ssh://keep.imfreedom.org/alice/pidgin`.
+
+## Instant Messaging Freedom Repositories
+
+Every developer, Crazy Patch Writer, and Google Summer of Code student gets a
+namespace in our [HGKeeper](https://keep.imfreedom.org/grim/hgkeeper/) instance
+under their username. Your access is controlled via an SSH key and are managed
+manually by one of the administrators. You can provide as many as you like, we
+just ask that you make sure they are password protected. You can use an
+[ssh-agent](https://en.wikipedia.org/wiki/Ssh-agent) to avoid having to
+constantly type your password.
+
+To interact with these repository is no different than any other. But you first
+need to create them, which you can do via the `hg init` command. Say you want
+to create a new pidgin repository in your name space. You can use the following
+command to create the repository.
+
+```sh
+hg init ssh://keep.imfreedom.org/alice/pidgin
+```
+
+You won't get any output from the command if it is successful. You can now push
+an existing clone to it by making sure you are in the check out directory and
+typing `hg push ssh://keep.imfreedom.org/alice/pidgin`.
+
+To avoid typing the full SSH url everytime, be sure to check out the
+[Repository Management](#repository-management) section above.
+
+## Sourcehut Repositories
+
+[Sourcehut](https://sr.ht/) is a collection of tools useful for software
+development. The tool they provide that we are interested in, is hosted
+Mercurial repositories.
+
+Creating an account is free, but hosting code repositories is only free while
+the [site is in alpha](https://sourcehut.org/alpha-details/). However, pricing
+is very modest and we highly recommend supporting them regardless.
+
+Once you have an account, and have added an SSH key you can easily create your
+own copy of any of the Instant Messaging Freedom repositories by just pushing
+to them. For example, if your Sourcehut username is bob and your shell is
+currently in the an Instant Messaging Freedom related repository, you can type
+`hg push ssh://hg@hg.sr.ht/~bob/pidgin` to push that repository up to
+Sourcehut!
+
+You can now use this repository just like any other, but to avoid typing the
+full SSH url everytime, be sure to check out the
+[Repository Management](#repository-management) section above.