[Draft] Mail for CGit ML
by Daniel Silverstone
[Note, this mail is intended for the CGit ML and is meant to discuss
the fact that we have use for namespace and would like CGit to support
such]
Hello,
One of the projects I am involved with is called Gitano[1] and is a Git server
along the lines of Gitolite or Gitosis, but not along the lines of Gitlab or
Gitorious. Among various technologies developed by other projects, we
recommend the use of CGit for visualising the Git repositories hosted in a
Gitano instance; and we have been very pleased with CGit in the three or
four years we've been using it.
We have recently been looking at switching up some of the ways we store
repositories on disk, and changing our use of a refs/gitano/* set of refs to a
proper Git namespace. In the act of doing that, we also thought about
server-side repository forks and how Git namespaces might help with that.
However if we were to use server-side namespaces for that, then we would need
to ensure our chosen web visualisation tool (CGit) was able to deal with it.
A very brief examination of the code failed to find any support for Git
namespaces in CGit, but I wondered firstly if namespaces had ever been
considered for support in CGit? If not yet considered, would support for
namespaces be something that the CGit project might entertain? We would be
very prepared to do a first pass set of patches, or indeed a design document
first if that were desirable; but given our relative inexperience in the CGit
codebase we would very much appreciate pointers and assistance from the CGit
community.
Obviously, if namespace support is not something that the CGit community wants
to see done then we will have to rethink some of our backend design decisions.
Ditto, if it's interesting but there is no intention to make a CGit release
within the timeframe we'd be working to (approx. November time at the latest)
then we'll need to think again.
I appreciate this is a fairly content-free mail that seems to be asking so much
and offering very little, so in brief summary:
1. We'd like CGit to support namespaces on a per-repo basis
2. We're prepared to head up the design and/or implementation of this
3. But only if the CGit community thinks this is at least possible to get
merged into a release the near future (next 6 months or so).
I look forward to your opinions, even if they're in the negative.
Regards,
Daniel.
--
Daniel Silverstone http://www.digital-scurf.org/
PGP mail accepted and encouraged. Key Id: 3CCE BABE 206C 3B69
6 years, 10 months
Design day
by Daniel Silverstone
Greetings,
I was hoping I might be able to persuade one or two of you to join me in
Manchester to do some planning work for Gitano 1.0 -- My hope is that we can
review the TODO list and decide what ought to go into 1.0 such that it can make
it into Debian in time for the next release's freeze period. This means
essentially we need to have it done by the end of the summer, though we can get
bug fixes in until about November or possibly beyond then if we're careful.
I have set up a Doodle poll at:
http://doodle.com/poll/3r3mkw8qx8kdsg5k
And I'd love it if any of you who could attend would fill out the poll so I can
pick a day. I'd find Saturdays easier, though I can do Sundays, and so I've
even put a line in for myself.
I will look again at the end of this week and if there's at least one other
person who wants to work on this with me, I'll pick a date based on the Doodle
at that time.
Thanks,
Daniel.
--
Daniel Silverstone http://www.digital-scurf.org/
PGP mail accepted and encouraged. Key Id: 3CCE BABE 206C 3B69
6 years, 11 months
Rough plan for i18n
by Daniel Silverstone
This is our notes from our language plans.
It's all very scary.
Places to load language pack content from
=========================================
1. core **Full Packs**
2. plugins **Full packs**
3. gitano-admin.git::site.conf **Clod for now**
4. some-repo::project.conf **Clod**
Full packs
==========
Full language packs are files which are named for the language they contain and
which are interpreted as code. They are run with a restricted set of funcions
all in the `i18n`, `table`, `math`, and `string` tables, along with a few basic
functions provided in the "global" context such as `pairs`, `ipairs`, `next`
etc.
A language is defined by the file returning a table containing the language
pack. Optionally the language may also return the name of the language pack to
be considered the _parent_ of this pack. For example, the `en_GB` pack may
consider the `en` pack to be its parent. A pack which does not define a parent
is automatically parented to the fallback language. If during expansion, the
language pack is unable to resolve a token, then the `i18n` module will
automatically inject a default function which formats up the arguments.
The keys of the returned table are the tokens which can be expanded by the
`i18n` module. The values are either strings (format described below) or
functions (semantics described below). Any other value type is an error and
will be detected at language pack loading.
Example
-------
### `en.lang`
return {
THINGY = "Bananas are excellent"
}
### `en_GB.lang`
return "en", {
THINGY = "Tea is excellent",
}
### `en_PIRATE.lang`
local t = {}
t.THINGY = "Yarr, grog is best"
return "en", t
Clod
====
Where language strings are defined in clod, they are of the form:
l10n.LANG.TOKEN = "Cheese is excellent"
If the clod is from `gitano-admin.git` then the tokens are implicitly prefixed
by `site.` and if the clod is from a project repository then the tokens are
implicitly prefixed by `project.` which prevents them from being able to
override core language tokens unless the core language explicitly intended for
them to be overridable.
To provide an overridable token you might, fr.ex. have in a core/plugin
language file:
return {
["site.TOKEN"] = "Bananas are the best"
}
Interpolation functions
=======================
Tokens whose value happen to be a function must be of the following form:
function (argtable)
-- Code thinking about argtable
return "some string expansion thereof"
end
These functions may use any functionality exported to the language pack module
as described above, including but not limited to the `string` library, the
`table` library, and various base functions such as `ipairs` etc.
The argtable is the set of `key=value` passed to the localisation function
along with the token name as the first element of the array part.
If you wish to expand a token as part of your function execution then the
`i18n` module exposes the `l10n` function as explained below.
If your function results in token expansion recursion then this shall be
considered an error.
Unrecognised keys passed in the `argtable` should be ignored by your function.
Code defensively but be permissive in what you accept.
Interpolation strings
=====================
Tokens whose value is a string will be parsed for expansion at language pack
load. They are essentially plain strings except for two expansion forms which
are prefixed by `$`.
Expanding arguments
-------------------
Arguments are expanded as:
Your name is ${name}
Where the `${name}` is the expansion of the `name` argument. Note that
`${foo.bar}` will look for an argument of the name `"foo.bar"` not an argument
called `foo` with a sub value called `bar`.
Expanding tokens
----------------
Tokens can be sub-expanded as:
We have decided that you are $(RENDER_JUDGEMENT,verdict=radical)
In this case, the token to be expanded is `RENDER_JUDGEMENT` and the argument
table to be passed in for expansion consists of a single key-value pair of
`verdict` = `radical`. If you wish to pass in the argument set given to the
string being expanded, you can include a key-value pair of `...` which can be
the only argument, or can be at any point in a list of arguments. The
arguments are evaluated in order allowing for earlier arguments to be
overridden by later ones. For example:
We have decided that you are $(RENDER_JUDEMENT,leniency=low,...,verdict=radical)
Where in this example, `leniency` is given a default of `low` but could be
overridden by an argument to this expansion, whereas `verdict` overrides any
argument of the same name to be `radical`.
Spaces around the `=` and `,` tokens will be trimmed, making:
$(RENDER_JUDGEMENT, verdict = radical)
exactly the same as:
$(RENDER_JUDGEMENT,verdict=radical)
Note: `$(TOKEN)` is valid, but `$(TOKEN,)` is an error since `""` is neither
a key-value pair, nor a `...`.
Note: If in the course of expanding a token, we encounter a token which has
already been expanded in the course of this expansion, it is an error and
expansion will be terminated. i.e. do not recurse.
i18n API
========
There are effectively two APIs which need to be considered here. The API
presented to the language packs as they are loaded, and the API presented to
the Gitano core. Where a function in the API is exposed shall be stated in the
function description herein.
rawAddLoader(fn)
----------------
This takes a function of the form:
function(languagename)
return "optionalparentlanguage", {languagetable}
end
This is exposed **ONLY** to the Gitano codebase
Calling this invalidates any caches.
rawAddPath(str)
---------------
This takes a string which is a filepath containing a single `?` which will be
replaced by the language name when the `i18n` module tries to load a language.
If the file thus-named exists then it shall be loaded as a language file.
This is exposed **ONLY** to the Gitano codebase.
Calling this invalidates any caches.
addPlugin(str)
--------------
This takes a string which is a plugin name. This chains through to
`rawAddPath` having expanded the string up into the form:
GITANO_SHARE_PATH/lang/PLUGINNAME/?.lang
This is exposed **ONLY** to the Gitano codebase.
Calling this invalidates any caches.
setCurrentLangName(str)
-------------------
This sets the current expansion language to the string passed in
This is exposed **ONLY** to the Gitano codebase.
getCurrentLangName()
----------------
This returns the current expansion language as a string
This is exposed **ONLY** to the Gitano codebase.
getLang(str)
------------
This takes a string which is a language name and returns a function which
when given an argtable will expand it and return the resulting string.
If the string is not provided (is nil) then it is effectively:
`getLang(getCurrentLangName())`
This is exposed **ONLY** to the Gitano codebase.
l10n(argtable)
--------------
This essentially chains as:
getLang()(argtable)
This is exposed to both the codebase and language packs.
l10nexpand(str, argtable)
-------------------------
This parses str as an expansion string and then expands it with the given
argtable. This is semantically equivalent to adding the string as a token and
then calling `l10n(argtable)`.
This allows for the caller to provide a runtime-generated expansion string
which shall be expanded as though it were a real language pack token's value.
This is exposed to both the codebase and language packs.
translit(str)
-------------
This function shall transliterate the given utf-8 string into the output
encoding specified by the current language.
Rough order of adding language packs
====================================
It is expected that the `i18n` module itself will add the Gitano core language
pack path to the loaders. During the loading of plugins, each plugin if it
has extra language tokens will add them at that point. Once the gitano-admin
core config has been loaded, it will add in any strings defined at that point.
Once a repository, which is not nascent, has been identified then its loader
will be added.
At each stage, the loaded language extends any language already defined. Any
attempt to re-parent a language will be considered an error and will prevent
that pack from loading. Thus it is recommended that only the core language
packs specify parent languages.
Encodings
=========
Language packs shall be in UTF-8. The i18n module shall be responsible for
looking at the defined language, extracting any encoding information from it,
and transforming the byte stream into the given encoding. It is *STRONGLY*
recommended that no encodings other than ascii, latin1, and utf-8 be used.
Gitano will use the `//TRANSLIT` feature of `lua-iconv` to do its best to
render the text down to the appropriate encoding.
--
Daniel Silverstone http://www.digital-scurf.org/
PGP mail accepted and encouraged. Key Id: 3CCE BABE 206C 3B69
6 years, 11 months
Rough first draft outline of Gitano docs
by Lars Wirzenius
Comments?
- - -
[[!meta title="Gitano documentation: an outline"]]
[[!meta author="Lars Wirzenius"]]
# Introduction
I've promised Daniel I'd write some Gitano documentation. I made that
promise years ago, and it's time to do something about it. This
document starts a rough outline of what I think Gitano needs.
# Goal
The Gitano documentation has several target audiences:
* Those who've never heard of Gitano, but are curious.
* Those who build from source, including sysadmins and packagers for
various Linux distros.
* Sysadmins who install Gitano and configure it for use. They have
shell access to the user under whom Gitano runs.
* Those who admin the Gitano instance via gitano itself. They are in
the "gitano-admin" group in Gitano.
* Those who use the Gitano instance as a git server.
There may be other audiences. For example, the ruleset may be such
that it implements a project concept, and this would add the audience
of "project manager". However, that's specific to the ruleset, and I
think the documentation that comes with Gitano should stick to the
ruleset that comes with it.
# Overview, web sites
* This should give a quick overview of what Gitano does and why it's
nice.
# Building from source
* This should be a README, plus the Makefile and any distro packaging
the Gitano project provides (which is Debian at this time).
* At least some of this already exists.
* I don't propose to write this at all. This belongs to the developers.
# Installing and configuring
* Mostly people will just install a .deb or other package for their
distro, I expect. However, installing from source is not
unimportant, and should be (and is?) covered by the README.
* For configuring, there's gitano-setup, and that's reasonably well
documented already.
* I don't think this needs any work at this time.
# Gitano admins
* This is important, since it covers Lace and writing ACL rulesets for
Gitano. Getting this right is crucial for a Gitano installation.
* I'm going to concentrate on this.
## A rough outline
* Overview
* What are gitano-admin members responsible for?
* What is Lace and where does it sit in the bigger Gitano picture?
* Lace syntax and semantics
* Defines.
* allow/deny, conditions.
* Includes.
* Rules in gitano-admin.git, and per repository?
* FIXME: I'm unclear if that even exists.
* Example driven.
* The default Gitano ruleset.
* A walkthrough, preferably done in a way that makes hard to get
out of sync with the actual code.
* Good practices for writing rulesets
* Common things one may want to do
* Anonymous access
* Cgit integration
* Testing one's ruleset
# Gitano users
* This is important, but less important than the admin documentation.
The Gitano help command suffices for most people, I think.
* Replicating documentation versus the built-in help texts is
duplication of work and should be avoided.
* I'm not going to work on this, at least not now.
--
Schrödinger's backup hypothesis: the condition of any backup is
undefined until a restore is attempted. -- andrewsh
6 years, 11 months