diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-10-15 18:08:45 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-10-15 18:08:45 +0300 |
commit | d9e71b0d412fb9d2d7fc8b00dddac21617eaaf19 (patch) | |
tree | 704cd8a52cf1e068bcd2e82cc1a0112e9674ef5d /doc/development/wikis.md | |
parent | 6ae38bb3b5dc719fb6a046dcbcce4671176395a2 (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc/development/wikis.md')
-rw-r--r-- | doc/development/wikis.md | 94 |
1 files changed, 94 insertions, 0 deletions
diff --git a/doc/development/wikis.md b/doc/development/wikis.md new file mode 100644 index 00000000000..9a436762645 --- /dev/null +++ b/doc/development/wikis.md @@ -0,0 +1,94 @@ +--- +type: reference, dev +stage: none +group: Development +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +description: "GitLab's development guidelines for Wikis" +--- + +# Wikis development guide + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227027) in GitLab 13.5. + +## Overview + +The wiki functionality in GitLab is based on [Gollum 4.x](https://github.com/gollum/gollum/), +which is used in [Gitaly's](gitaly.md) Ruby service and accessed from the Rails app through Gitaly RPC calls. + +Wikis use Git repositories as storage backend, and can be accessed through: + +- The [Web UI](../user/project/wiki/index.md) +- The [REST API](../api/wikis.md) +- [Git itself](../user/project/wiki/#adding-and-editing-wiki-pages-locally) + +[Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2214) in GitLab 13.5, wikis are also available +for groups, in addition to projects. + +## Involved Gems + +Some notable gems that are used for wikis are: + +| Component | Description | Gem name | GitLab project | Upstream project | +|:--------------|:-----------------------------------------------|:-------------------------------|:--------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------| +| `gitlab` | Markup renderer, depends on various other gems | `gitlab-markup` | [`gitlab-org/gitlab-markup`](https://gitlab.com/gitlab-org/gitlab-markup) | [`github/markup`](https://github.com/github/markup) | +| `gitaly-ruby` | Main Gollum library | `gitlab-gollum-lib` | [`gitlab-org/gollum-lib`](https://gitlab.com/gitlab-org/gollum-lib) | [`gollum/gollum-lib`](https://github.com/gollum/gollum-lib) | +| | Gollum Git adapter for Rugged | `gitlab-gollum-rugged_adapter` | [`gitlab-org/gitlab-gollum-rugged_adapter`](https://gitlab.com/gitlab-org/gitlab-gollum-rugged_adapter) | [`gollum/rugged_adapter`](https://github.com/gollum/rugged_adapter) | +| | Rugged (also used in Gitaly itself) | `rugged` | - | [`libgit2/rugged`](https://github.com/libgit2/rugged) | + +### Notes on Gollum + +We only use Gollum as a storage abstraction layer, to handle the mapping between wiki page slugs and files in the repository. + +When rendering wiki pages, we don't use Gollum at all and instead go through a +[custom Banzai pipeline](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/banzai/pipeline/wiki_pipeline.rb). +This adds some [wiki-specific markup](../user/markdown.md#wiki-specific-markdown), such as Gollum's `[[link]]` syntax. + +Since we do not make use of most of Gollum's features, we plan to move away from it entirely at some point. +[See this epic](https://gitlab.com/groups/gitlab-org/-/epics/2381) for reference. + +## Model classes + +The `Wiki` class is the main abstraction around a wiki repository, it needs to be initialized +with a container which can be either a `Project` or `Group`: + +```mermaid +classDiagram + Wiki --> ProjectWiki + Wiki --> GroupWiki + + class Wiki { + #container + #repository + } + + class ProjectWiki { + #project → #container + } + + class GroupWiki { + #group → #container + } +``` + +Some models wrap similar classes from Gitaly and Gollum: + +| Rails Model | Gitaly Class | Gollum | +|:------------|:--------------------------------------------------------|:---------------| +| `Wiki` | `Gitlab::Git::Wiki` | `Gollum::Wiki` | +| `WikiPage` | `Gitlab::Git::WikiPage`, `Gitlab::Git::WikiPageVersion` | `Gollum::Page` | +| | `Gitlab::Git::WikiFile` | `Gollum::File` | + +Only some data is persisted in the database: + +| Model | Description | +|:----------------------|:-----------------------------------------| +| `WikiPage::Meta` | Metadata for wiki pages | +| `WikiPage::Slug` | Current and previous slugs of wiki pages | +| `ProjectRepository` | Gitaly storage data for project wikis | +| `GroupWikiRepository` | Gitaly storage data for group wikis | + +## Attachments + +The web UI uploads attachments through the REST API, which stores the files as commits in the wiki repository. + +Prior to GitLab 11.3 attachments were stored outside of the repository, [see this issue](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33475). |