Add a first outline

1 files changed, 87 insertions, 0 deletions

diff --git a/doc/admin/000.mdwn b/doc/admin/000.mdwn
new file mode 100644
index 0000000..53c207f
--- /dev/null
+++ b/doc/admin/000.mdwn
@@ -0,0 +1,87 @@
+---
+title: Gitano Admininistration
+author: Lars Wirzenius and the Gitano project
+date: unversioned for now
+...
+
+
+# Introduction
+
+This document describes what a "Gitano admin" needs to know. Gitano
+admins are reponsible for setting the policy of a Gitano installation:
+who can access it, what they can do, what they can't do, and so on.
+The target audience of this document is those who are members of the
+`gitano-admin` group in a Gitano installation. We assume they know how
+to use Gitano as a user already, and are comfortable editing plain
+text files and using git to manage files.
+
+# Overview
+
+Gitano admins primarily enable people to do their jobs. This involves:
+
+* define Gitano access control rules using Lace
+* add and remove Gitano users
+* helping people with their Gitano problems
+* possibly add and remove Git repositories, unless they allow people
+  to do that themselves
+
+Access control to Gitano is defined using a language called Lace. It
+is a fairly simple textual language for expressing what actions Gitano
+users can and can't do.
+
+# Lace syntax and semantics
+
+META: This chapter describes Lace in some detail. It is example
+driven: rather than starting from a syntax BNF and then describing the
+semantics of each construct, we'll skip the formalism and go through a
+series of examples, starting from a minimal ruleset ("hello, world").
+
+## First example
+
+META: This section shows the "hello, world" example. It shows where
+the ruleset is kept, and how to edit and modify it.
+
+## META: This needs to be broken down into a series of examples
+
+* Defines.
+* allow/deny, conditions.
+* Includes.
+
+## Per-repository rules
+
+META: This section describes how per-repository rulesets work, where
+they're kept, etc.
+
+## Testing one's ruleset
+
+META: This section discusses systematic testing of one's ruleset.
+Might or might not include automated testing (with yarn).
+
+# The default Gitano ruleset
+
+META: This chapter is a walkthrough of the default Gitano ruleset.
+Ideally implemented in such a way that it is either generated from the
+Gitano source code, or vice versa.
+
+# Good practices for writing rulesets
+
+META: This chapter discusses various best practices for writing Gitano
+rulesets. It may initially have to be a skeleton until the Gitano
+community gathers enough experience to write something substantial.
+But an interview with Daniel for good ideas should come up with enough
+for an initial chapter.
+
+# Common things one may want to do
+
+META: This chapter discusses some common changes one may want to do to
+the default ruleset. Ideally, there would be none, but reality is ugly.
+
+## Anonymous access
+
+META: This section describes how to allow anyone access to specific
+repositories.
+
+## Cgit integration
+
+META: This section describes how to allow cgit show specific
+repositories.