Commit 8b3c0a49 authored by Georges Racinet's avatar Georges Racinet 🦑
Browse files

Updated changelog and install instructions in main branch

These files tend to have a separate life in release branches,
this isn't a problem, yet's it's more practical for the
version in the main branch not to lag too much.

branch : heptapod
parent 4e7f76755757
......@@ -15,6 +15,227 @@ the exact revision of the main repository in the user help page.
Please read migration instructions in the
[installation notice](
### Heptapod 0.13.2 (2020-06-15)
- heptapod#297: missing notifications for merge changesets and file editing
done from the interface, affecting pipelines, service integrations etc.
- heptapod#292: on Python 3, import of Bitbucket Pull Requests from personal
forks was failing
- heptapod#289: connection test to Read the Docs
- heptapod#290: on Golang version of SSH support, trailing slash wasn't
- Bumped Mercurial from 5.4 to 5.4.1
### Heptapod 0.13.1 (2020-06-11)
- heptapod#269 (internal): major refactor of the way GitLab branches get removed
("pruned") according to changes in Mercurial repository content, together
with new, faster and more robust detection of manual merges for
Merge Requests. User visible improvements:
+ heptapod#288: avoid lingering branches in the Web UI corresponding to
published topics. Such previously existing phantom branches should be
"pruned" at first push after the version upgrade.
+ heptapod#278: users shouldn't be prompted to create or update Merge Requests
for phantom topic branches.
+ heptapod#268: no pipeline should be created for topics upon publication
(merge), only for the target branch.
+ heptapod#207: Merge Request detection works if named branches are closed
in the same push (before or after the merge).
- heptapod#282: Read the Docs, new Project integration for Mercurial only.
Does not test connection in this first version, see heptapod#289.
- heptapod-shell#2 (technology preview): rewrite of Mercurial SSH access in
the Go programming language. Will become the only option in Heptapod 0.14.
- py-heptapod#3: `HEPTAPOD_REPOSITORY_USAGE` environment variable is available
for Mercurial hooks, with values such as `project` and `wiki`.
### Heptapod 0.13.0 (2020-05-29)
#### Major changes since Heptapod 0.12
For more details, see the changelogs related to 0.13.0rcN
- Wikis are fully supported, with Bitbucket import
- Python 3 is supported. Two series of Docker images are available, with
Python 2 the default. The default can change in later 0.13 versions.
Source installation instructions include a recommended
setup to switch Python version easily.
- Heptapod Workhorse is included (Docker) and required (source installs).
This is a major progress in HTTP performance for Mercurial repository content.
- Full support for editing repository files through the web, except with the
Web IDE (problems with branch creation, see heptapod#285).
- GitLab 12.3.9, Mercurial 5.4, hg-evolve 10.0.0.
Mercurial and Python version details are now displayed on the help page and
the admin dashboard.
#### Changes since 0.13.0rc2
- heptapod#280: implementation of server-side rebase (for topics only)
- heptapod#107: restored edit/replace/delete buttons for files. Web IDE not
fully supported
- heptapod#279: Bitbucket import for wikis
- heptapod#284: Prevent merge/accept of Merge Requests targeting topics to
avoid dangerous publications. Proper behaviour to be determined.
### Heptapod 0.13.0rc2 (2020-05-23)
- Python 3 support either from source or with the
`octobus/heptapod:0.13.0rc2-py3` Docker image. Python 2 is still the default.
Testing with Python 3 is encouraged. It is strongly advised to
switch back to Python 2 for comparison in case of issue.
- heptapod#275: backups for wikis
- heptapod#277: partial fix for temporary working directories (hg shares)
- heptapod#199, heptapod#271: Python, Mercurial and hg-evolve version are
now displayed in the help page and the admin dashboard.
- heptapod-workhorse#1: version properly displayed if installed from a tarball
(which is the case in the Docker image)
### Heptapod 0.13.0rc1 (2020-05-14)
- heptapod#173: Support Wikis (still to be considered experimental. Not
imported from Bitbucket, no preview for RST)
- heptapod#255: Heptapod Workhorse is now standard and mandatory
- heptapod#245: GitLab 12.3.9
- Mercurial 5.4
- hg-evolve 10.0.0
- (Docker): the `octobus/heptapod` is about 1 GB smaller, see heptapod-docker#5
- heptapod#107 (related): improvements for commit creations by the web
- heptapod#243: cloning with deploy tokens now works
#### Internal changes
- py-heptapod!20: Mercurial notifies GitLab by calling the internal REST API
- Separation of internal Git and Mercurial logic in preparation for HGitaly
and Git support.
### Heptapod 0.12.4 (2020-05-19)
- In some cases, failing to backup a single repository could abort the
whole process
- heptapod#260: pipelines weren't created for new tags, and stale view of
tag names from the web app.
- heptapod#126: default GitLab branch can't be a topic any more unless there
is nothing else. In that case, the first publication will update the GitLab
### Heptapod 0.12.3 (2020-05-06)
- heptapod#263: Bitbucket import page was broken for users with group creation
rights (regression introduced in 0.12.2)
- heptapod#265: all pushes could be blocked if search for latest topic
changeset before publication failed, which can happen in inconsistent states
- heptapod#145: ensure that pipelines run in the target branch after merge from
the web application. Possible improvements for heptapod#261 and heptapod#215
will be inv
- heptapod#251: now Bitbucket importer sets the default branch as it was on
Bitbucket (named branch only)
- heptapod#242: bump to hg-evolve 9.3.1, unblocking some scenarios involving
stacked topics and Merge Requests.
#### potential improvements
(untested as of this writing)
- heptapod#215: update dependent Merge Request after merge
- heptapod#265: detect merge of Merge Request for topic if a dependent one
is merged from the web application (hence publishing the two topics)
#### Docker image changes
- heptapod-docker#6: general base OS upgrade
- heptapod-docker#5: the `octobus/heptapod` is now about 1GB smaller, mostly
by not moving the biggest conversion to Mercurial to `octobus/heptapod-dev`
### Heptapod 0.12.2 (2020-04-30)
- heptapod#256: (major UX) users that can create projects in groups but
not in their personal namespaces didn't see the various "New projects" links.
Now they do.
- heptapod#217: implemented the Merge Request squash option
- heptapod#258: pushing a topic related to another branch than the default one
from GitLab's point of view now gives rise to the correct Merge Request
### Heptapod 0.12.1 (2020-04-23)
- heptapod#104: Bitbucket import for issues attachments (global ones)
- heptapod#120: Heptapod Workhorse available for source installs only
- heptapod#250: Broken MR page if target branch has vanished
- heptapod#254: Free input form for Bitbucket imports, activable by new setting
in the admin area.
### Heptapod 0.12.0 (2020-04-06)
#### Changes since Heptapod 0.8.4
##### Breaking changes
- heptapod#212: jump to GitLab CE 12.2.12 – do not migrate directly.
- heptapod#221: users will need `hg-evolve>=9.3.0` to pull topics. Clients
without the `topics` extension won't pull them – that's the point.
##### Major improvements
- heptapod#135: removed inner Git push for a major performance boost in pushes
(up to x10 on the largest repositories). We're now using only one inner Git
repository instead of two, also saving some space on storage.
- Mercurial 5.3.1, Evolve 9.3.0
- heptapod#224: core adaptation of the GitLab features to write repository
files (including README etc) from the web UI
##### Minor improvements
- heptapod#226: better support for Bitbucket import of overlapping or stacked
Pull Requests
- heptapod#192: optimize repository after import
#### Changes since Heptapod 0.12.0rc6
- heptapod#235: fixed project transfers on legacy storage
- heptapod#234: removed irrelevant GitHub and GitLab import sources
- heptapod#228: support migration from legacy to hashed repository storage
and back
- heptapod#226: better support for Bitbucket import of overlapping or stacked
Pull Requests
- heptapod#221: do not serve changeset with topics to clients that don't have
the `topics` extension
- heptapod#218, heptapod#219: hide unsupported cherry-pick and revert options
on merged MRs
- heptapod#192: optimize repository after import
### Heptapod 0.12.0rc5 (2020-03-30)
- heptapod#229: backups were not working in previous RC releases
- all fixes from Heptapod 0.8.4 (see below)
### Heptapod 0.12.0rc4 (2020-03-25)
- heptapod#223: the pages behind commits main URLs were broken
- heptapod#224: core adaptation of the GitLab features to write repository
files (including README etc) from the Rails app, except in the case of
empty repositories
### Heptapod 0.12.0rc3 (2020-03-18)
- fixed an issue with initialisation of Bitbucket Import SSO provider that was
impairing migrations.
Bitbucket import features aren't tested yet in this release.
### Heptapod 0.12.0rc2 (2020-03-17)
- fixed merge changeset generation, which would fail on most setups except
some development rigs.
- fixed bundler version in `Gemfile.lock` that was impairing Docker start.
### Heptapod 0.12.0rc1 (2020-03-16)
#### Major improvements
......@@ -23,11 +244,23 @@ Please read migration instructions in the
- heptapod#135: removed inner Git push for a major performance boost in pushes
(up to x10 on the largest repositories). We're now using only one inner Git
repository instead of two, also saving some space on storage.
- Mercurial 5.3.1, Evolve 9.3.0
#### Known issues affecting this version.
- heptapod#213: group HGRCs won't work on hashed projects
### Heptapod 0.8.4 (2020-03-29)
This release should be the last of the 0.8 series. It fixes issues about
backups that could be annoying when users start to upgrade to 0.12.x
- heptapod#174: group-level HGRCs are now backuped
- heptapod#232: part of the HGRC that's manageable through the Rails
application (API only for now) wasn't backuped.
- heptapod#208: prevented Git pulls and pushes on Mercurial repositories over
SSH (possible due to inner implementation details, but very bogus)
### Heptapod 0.8.3 (2020-02-19)
- heptapod#165: a subset of Mercurial settings from the `[heptapod]` section
# Heptapod installation guide
## Important: migrating from Heptapod 0.8
## Important: migrating from Heptapod 0.8 to 0.12
Because Heptapod 0.12 is a jump from GitLab CE 10.5 to 12.2, it is not
possible to upgrade directly, because major GitLab version bump must be done
......@@ -66,12 +66,69 @@ All other standard GitLab components (Gitaly, etc) have to be taken
from the canonical upstream locations, at the version specified at the root
of the Rails application sources (`GITALY_SERVER_VERSION` etc).
### Installing the Mercurial component
#### Heptapod Shell: activating the Golang version of Mercurial SSH support
This is for Heptapod 0.13 from 0.13.1 onwards. The Go programming language
version will become the only one in Heptapod 0.14, same as in in GitLab ≥ 12.4.
In the `config.yml` file of GitLab / Heptapod Shell, put this:
# Migration to Go: anything listed here has two implementations. Use these flags
# to try the new implementations out, or to revert to the old behaviour if there
# problems arise.
enabled: true
features: ["hg"]
The `config.yml.example` file in the sources was also updated to include
this new `hg` feature among the possible values.
### Installing Mercurial components
We need a specific Mercurial version, a WSGI server (usually Gunicorn), and
some additional Python packages from source.
For now, this is Python2 only.
#### Python versions
Before version 0.13.0, Heptapod runs with Python 2.7 only.
Heptapod 0.13.0 supports Python 2.7 and Python ≥ 3.7, with Python 3 still
considered a technology preview.
Python 3 will become default or even mandatory with Heptapod 0.14.
On Python 3, the preferred version should be 3.8.
In theory, the minimal Python 3 version should be 3.6.2, but it is completely
untested, whereas developer setups have routinely been running 3.7.
For the record the Docker images currently ship with 3.8.3.
#### Be ready to fallback to Python 2
We encourage you to run Heptapod with Python 3, but you must be aware that
this can cause some friction, especially in interactions with external
systems. Therefore you should **prepare the means to switch easily between
Python 2 and Python 3**. This way, if you encounter problems, you'll be able to qualify them (thank you in advance for the resulting bug report)
and you'll have a workaround.
An easy way to do that is to prepare a virtualenv for each Python version,
and point a symbolic link to the one to actually use.
Assuming you'll reference only that link in the
various configuration files (see below), to switch Python versions, you'll only
need to
1. change the link target
2. restart `gunicorn` (internal Mercurial service).
Almost no perceptible interruption.
3. restart the Rails application so that the Python version displayed in the
help page and admin dashboard is the right one. This is a noticeable
interruption of service, but you can delay it if that's a problem.
#### Install the Python packages
You can install them system-wide if that suits you (Mercurial has very few
dependencies, it's very unlikely it'll clash with system libraries) or with
......@@ -85,27 +142,7 @@ Install the Python packages to be taken from using the
$PIP install -U -r python/requirements.txt
where `$PIP` is `pip --user` or `some/virtualenv/bin/pip` according to your
Then, we need a special unreleased version of `hg-git`.
Rather to use `pip install hg+https`, which is quite error
prone, the simplest best way looks like this:
hg clone -u $TAG hg-git
$PIP install -e hg-git
- this repository is small enough that pulling exactly the wanted
revision is a needless complication.
- the `-e` flag will make your subsequent updates easier: you'll just have
to `hg pull -u NEW_TAG`, redo the `pip install -e` to account for package
metadata changes (notably entry points if any) and restart relevant processes.
where `$PIP` is `pip --user` or `some/virtualenv/bin/pip` according to your choice (see above how to prepare for Python 3 with easy fallback onto Python 2).
### Configuration
......@@ -142,6 +179,32 @@ installation details.
A simple way is to create a `heptapod.hgrc` file using the `%include` directive.
See the example in `$PY_HEPTAPOD/heptapod.example.hgrc`.
##### Heptapod >= 0.13: configuring Mercurial to notify the Rails application
Starting with Heptapod 0.13, Mercurial will send notifications about incoming
changesets directly.
For that to work, you need tell it where to find the `.gitlab_shell_secret`
file and configure the internal API address. This is done in the `[heptapod]`
section of your `heptapod.hgrc`:
* the default internal API URL is `http://localhost:8080`.
* the older `heptapod.gitlab-shell` setting is still supported to find
the `.gitlab_shell_secret` file
If you're upgrading from Heptapod 0.12 *and* the Rails application is binding
to `localhost:8080` (the default with unicorn) then the configuration should
be readily compatible.
### Internal Mercurial service
Repository content is exposed to GitLab through an internal HTTP service.
......@@ -162,6 +225,8 @@ is on the path.
Again, this `gunicorn` must be able to load the Heptapod Python packages, so
you should use the one that's been installed with `requirements.txt`.
If you're using the dual virtualenv setup for Python 3 with fallback on
Python 2, then use the symbolic link in the path to gunicorn.
......@@ -176,47 +241,12 @@ Edit the configuration files for the Rails application
to provide the full path to your `heptapod.hgrc` file, and the `hg` executable
in the `mercurial` section.
Note: in those YaML files, `hgrc` must always be a list. This is for separation
in several files with different persistence properties.
#### Special cases
##### Heptapod 0.12: secondary GitLab shell
You need to copy over `config.yml` and `.gitlab_shell_secret`
from GitLab shell to the appropriate `gitlab-shell` subdirectory of the Gitaly
installation. The exact path may depend on your installation. Worst case is
you'll be told about it in Mercurial logs if pushes don't work.
Reason: we're using the Ruby GitLab Shell code shipping with Gitaly
to tell GitLab about
changes in repositories. This is prone to disappear in favour of a more direct
approach in forthcoming Heptapod versions.
### Using Heptapod Workhorse
Heptapod Workhorse is a technology preview in Heptapod 0.12.1 and following,
expected to become the standard in Heptapod 0.13.
Its benefits should be:
- better concurrency support by reducing involvement of the Rails application
in interaction with Mercurial HTTP clients to the minimum, i.e.,
permissions assessment.
- better RAM usage, with Mercurial bundles being streamed from the `hgserve`
service to the HTTP client instead of being loaded in RAM
- no need to up the timeout of the Rails application for longer Mercurial
operation over HTTP.
To use Heptapod Workhorse:
- fetch it like any other Heptapod component (see "Fetching source" above)
- compile it in the same way as GitLab Workhorse
- set `mercurial:workhorse_enabled` to `true` in `config/gitlab.yml`.
If you're using Heptapod Workhorse, please help us making it the standard by
providing your feedback, thanks!
- in those YaML files, `hgrc` must always be a list. This is for separation
in several files with different persistence properties.
- if you're using the double virtualenv approach to testing Python 3, remember
to use the symbolic link for the path to the `hg` executable.
### Validation with the functional tests
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment