# Backporting Process

## Intro

While the _porting_ process of `rustybuzz` is complete, _backporting_ is a never-ending task.
And even if we would be able to port simple commits in 5min, multiply it by a thousand
and you would understand why we're so behind. This is why any help is welcome.

If you want to help, you don't have to know anything about text shaping, fonts or even
C++ and Rust. Most `harfbuzz` commits consist of minor tweaks and fixes, which can easily be ported
by anyone with even basic CS knowledge.

If you have any questions, we have a dedicated [discussion] for backporting.

## Working Environment

Ideally, you should use Linux or macOS. While working on Windows is potentially possible,
it would be pain. Mainly because of `harfbuzz` and not `rustybuzz`. `harfbuzz` relies on
many Unix tools.

For one, you would need at least: git, Python, Rust, clang/gcc and meson.
Potentially even [ragel](./ragel.md), but it has to be built from sources.

## General Algorithm

The porting algorithm is quite simple and applies to most projects.

1. Take the latest not ported `harfbuzz` commit.
  You can find the last ported in `rustybuzz` commit messages.
1. Analyze it to make sure it applies to `rustybuzz` or not.
1. Port it to `rustybuzz`.
1. Port `harfbuzz` tests (if needed).
1. Run `rustybuzz` tests (`cargo test`).
1. Run auto-format `cargo fmt`.
1. Commit.
1. Rinse and repeat.

Overall, if tests are passing - we're good. Everything else doesn't really matter.

## Analyzing Changes

The main difference between `harfbuzz` and `rustybuzz` is that `rustybuzz` is just a shaper,
while `harfbuzz` is collection of things. More specifically, `harfbuzz` includes:
shaping, subsetting, fonts parsing, Unicode tables, precompiled state-machines,
custom C++ containers (instead of std one) and bindings to 3rd-party libraries.

`rustybuzz` doesn't have subsetting. If you see changes in a file/function
with a name `subset` or a commit with the `[subset]` prefix, you can easily skip those.

Fonts parsing is done via [`ttf-parser`](https://github.com/RazrFalcon/ttf-parser)
and any changes to the fonts parsing in `harfbuzz` probably do not affect us,
unless new tests are failing. In which case better ask about in the [discussion].

Unicode tables and related routines are done differently in `rustybuzz`,
usually by using 3rd-party crates instead of a custom solution.
Again, better ask about such changes in the [discussion].

Precompiled state-machines are generated by [ragel](./ragel.md).
Follow the linked instruction if you see that any of `*.rl` files had changed.

We do not use any custom C++ containers `harfbuzz` implements and rely on Rust's std instead.
So changes to those can be ignored as well.

Changes to the `harfbuzz` build systems (it has 3... welcome to C++) should be completely ignored
as well.

Overall, if you see a change in a `hb-ot-*` file - this change probably affects `rustybuzz`.

## Updating Tests

Almost all of `harfbuzz` shaping tests (found in `test/shaping`) are as simple as
font + text = glyph ids + positions.
The difference is that `harfbuzz` uses Python to run tests, while we auto-generate
the default Rust tests. And to do so, we use `scripts/gen-shaping-tests.py`.

But to get the expected output, we first have to build `harfbuzz` at the commit we're porting.
You cannot use the latest `harfbuzz` version to do so. For example the one installed on your
system if you're using Linux.

The easies way to do so is to use `meson`:

```sh
git clone https://github.com/harfbuzz/harfbuzz
cd harfbuzz
git checkout HASH # put the required hash here
meson builddir --reconfigure # `--reconfigure` is needed only on the first run
ninja -Cbuilddir
```

Now you can run:

```sh
# Pass harfbuzz clone dir, not `harfbuzz/src` one.
cd rustybuzz/scripts
./gen-shaping-tests.py /path/to/harfbuzz
```

It will do everything for you. All you need is to run `cargo test` afterward to make sure
all tests are passing.

If not, then either your change was incorrect or there is a bug in `rustybuzz`.

## Commit Messages

Make sure each `rustybuzz` commit contains a link to the related `harfbuzz` commit.
[Example](https://github.com/harfbuzz/rustybuzz/commit/5637691426b72dcac2c56a3d1fabe104438b5db7).
Commit message itself can be copy-pasted from `harfbuzz`.


[discussion]: https://github.com/harfbuzz/rustybuzz/discussions/79