Rewrite project history #5

c10k-cc · 2022-10-16T22:54:36Z

Rewrite project history

Summary

This issue / proposal aims to address the complete rewriting of the whole project git history.

Description

About

Hello folks!

@just-a-stream entrusted me a role of barter-rs GitHub organisation owner (along with him, of course),
mainly in order to assist him with structuring the GitHub organisation, teams, project, repositories etc.
One of the first items on my repo "housekeeping agenda" is addressing some problems with the project git history.
Afterwards, I will continue to make other advancements to the repository organisation, backlog, docs, CI etc.

Yes, I actually took my time and reviewed over 400 existing commits in this repo
in order to get a better understanding of the project structure & history (roughly 10 hours of work overall).
Hey, at least I learned the project structure and how the things evolved over time.

Intro

This proposal (along with its associated upcoming PR) aims to completely rewrite the whole project git history,
in order to fix few major otherwise unresolvable issues which are currently present.

However, performing such an unprecedented change is a very brave & dangerous task with a lot of risks associated.
That is why this proposal is designed in such a way to honour the above-limitations, reduce the risks to zero,
and remove any and all dangers associated with it.

Motivation

This whole open-source project was started as a @just-a-stream's personal hobby project.
It is completely understandable that starting a small project from scratch does not assume doing "boilerplatey" tasks,
such as properly organising git branches or formatting git commit messages.
Once the project starts growing, the organic need for a stricter project organisation comes by.
Overall, the author did an amazing job of designing and open-sourcing such an ambitious project.
Nonetheless, it does not change the fact that some things should've / can still be organised better, as mentioned below.

This is a list of issues with a varying degrees of severity / significance:

author's private e-mail & personal name are leaking from git commit metadata
(due to misconfiguration + lack of automatic author e-mail anonymisation feature on legacy commits made on GitLab)
project tries to follow Git Flow model, but diverges from some important conventions
- develop branch was merged into main branch without a fast-forward merge
  - it causes a redundant merge commit to be generated on merge (creates clutter, reduces visibility)
  - this is obviously against the model's conventions, only feature/* branches must be merged without FF merge
- feat/* branches weren't rebased when going out-of-date from develop, develop was merged into them
  - it causes annoying merge conflicts (and, therefore, generating annoying redundant conflict-resolving commits)
  - generates a redundant merge commit (sometimes even multiple commits)
  - the only exception for merges into feat/* is when the feature/* is going to squash its changes
    (rebase-squash commits)
- concept of version tagging on main branch was entirely ignored
  - too bad, since GitHub supports easy project release creation from properly-organised tags
- concept of release/* branches was almost entirely ignored
  - goes in-hand with tagging & merging to main
- on few occasions, changes were directly applied to main branch
  - this is against a concept of hotfix/* branch utilisation
project tries to follow Git Conventional Commits, but again, diverges from some conventions
- commit messages do not properly utilise topic: prefixes
  - most of the commits are incorrectly prefixed with feat: prefix
- commit titles do not consistently describe the changes applied (occasional too short & obfuscated message)
- commit titles are not written in an "imperative" or "present" form
- commits do not utilise title + body formatting at all, only a brief (and sometimes overly-long) title

Again, all the mentioned issues are completely normal and to-be-expected from an emerging open-source project.
When starting out, a dev works fast and breaks things.
Nobody has the time for such an overhead of a task such as properly organising git branches, commits or commit messages.
However, that is why it is important to perform some "git housekeeping" tasks before taking the project public,
e.g. making a "public appearance".

Now is better than never. The project is still very young and in its early stage.
The transfer to GitHub is also very recent, so it would be a good idea to do it as soon as possible,
before there is a swarm of forks, pull requests, stars & open issues.
All the forks are from the devs who are in communication with each other in the community (at the time of writing),
so nobody will be surprised by the change, without being informed in advance and offered additional migration help.

Constraints

There are multiple constraints due to the fragility & delicacy of such a task.
In other words, nobody recommends to rewrite git history, devs are afraid of merge hells & force git pushes,
git rebase is not well-understood or liked etc.

This set of changes is designed with a strict respect to the constraints in mind:

no breaking changes (or otherwise)
- actually, NO CHANGES AT ALL!
- changes are bad
no unnecessary modifications
- repeat, NO CHANGES AT ALL!!!
maximum historical compatibility (date & author preservation etc.)
- NO CHANGES!!!1!
no side effects for existing & future contributors (e.g. merge hell)

Changes applied

Proposed solution to this problem is to carefully rebase the project's git history.

During the implementation of this solution, additional steps were taken to respect the above-mentioned constraints:

no commit contents were actually changed (git tree remains intact for all commits)
no additional commits were added
only commit messages were modified

The result is a develop-new branch which is 1-to-1 compatible with the current develop branch
throughout all the versions of releases.

Achieved improvements

There are multiple benefits of this newly-rewritten project git history:

No leaking personal information from commits
Date & author of all the existing commits completely preserved
Consistent commit message formatting
- topic: prefix keywords are properly utilised
- no commit message title longer than 100 characters (still a very gracious length limit)
  - messages longer than that utilise commit message body separated by a blank line
    - indicated by * at the end of the commit message title / subject line
- all the symbols (module names, variables, structs, traits, functions etc.) encased in ` (backtick characters)
  - this gets rendered to a Markdown code block, like this: FooBar
    - this makes referenced symbols more visible, without polluting messages / sacrificing conciseness
- when multiple unrelated changes occur in a commit, they are split with ;
- messages written in an imperative / present form
- messages lower-cased and do not end with .
- overall useful for complying with modern CI/CD tool pipelines & parsing commit messages
Organised branch workflow
Easier to make future contributions (more inviting to work on a well-organised project)
All the project release versions can now be easily tagged, and their releases can be easily generated on GitHub.
The history of each file can be easily tracked & traced / inspected, due to tidy & expressive commit messages applied
- helpful for git blame & similar tools
There are now less commits (removed redundant merge commits & some obvious duplicate commits)
- doesn't affect any historical version, e.g. does not produce any differences at the point of any release
A good example is set for all the future project contributions
- organised git branches, commits & their messages!

Verification (steps to verify / reproduce the results)?

(expand)

Verification method: trust me bro

Nah, just kidding. You can really verify it yourself.
By performing the steps specified below,
you can easily check that all the changes are indeed compatible with the existing develop branch releases.

You can run this shell script, which is hopefully written concise enough and well-documented with expressive comments.
Yes, I had to write it from scratch, what a waste of time.

compare-branches.sh

#!/usr/bin/env bash

ORIG_DIR="$PWD/barter-rs-orig"
REBASED_DIR="$PWD/barter-rs-rebased"

# this array contains hard-coded original branch "version" commits a.k.a. release commits
# how to easily acquire these commit hashes yourself?
#  - run this shell command inside repo dir:
#    `git checkout develop; git log --format=oneline Cargo.toml`
#  - optionally, filter by commits containing "incr" (which is not 100% reliable due to unstructured message format):
#    `git log --format=oneline --grep=incr Cargo.toml`
ORIG_VER_COMMITS=(
  0d1467cc5a1b8318a3d2b4d941b1b8a38bd233a7 # v0.1.0
  5dba365d1fd53630c7aa82943d3faa12aa27f835 # v0.2.0
  1ff46f09f4db8003c816432c16e718e59e00fdd7 # v0.2.1
  68d96309bff2a7fc367dd51b0d5120dc09fc46c6 # v0.2.2
  fd85e3d47348e6c772116e368eca253075ea6c00 # v0.2.3
  ef717c03418840dedfdfc2d95edf950f67ec9e6a # v0.2.4
  57ec50a8551455c5102b2082a56f89676ffd9be6 # v0.2.5
  64de2b24a7c11391683c6265ffcb1e00e9a88aec # v0.2.6
  830c6c17e611107b53e49cdac44da99bade4687f # v0.2.7
  430a33b9df0052b24bd170a0f291847035ddbd1c # v0.2.8
  204b8f5ca50c260c41a1c1f7f6cdedfcd7f64dfd # v0.2.9
  22e0d1d765c64c172377b340716910fda1c4aa37 # v0.2.10
  78ab53fa5a042eb56ece795fb0a6a5b0aceca7a8 # v0.2.11
  25013f809da85bc5c20995397d20d170626bdcc9 # v0.3.0
  557b926e3c202616734dc4a9605253c72416231e # v0.3.1
  5221bf49ce227268b2e6868c6055f200c6321d4b # v0.4.0
  56e5668ad8ccdf4df4c3a7183d045772aef8f151 # v0.4.1
  6d27e30d0603683f2927c106646a3690a4939626 # v0.5.0
  6e659b7601cf107f6716315f52be03827e910599 # v0.5.1
  05830063457ae54db000a3158000a8dec3239fe6 # v0.5.2
  5bae25abc4ed878269bc8df9b679ccf42e235fd3 # v0.5.3
  e9021da46717379615be01eadfc4ccae97422441 # v0.5.4
  953a54cff61ab2dfc560f7adcf304a249aede437 # v0.5.5
  3571f630d2913c76a5eb05e0891b5a3c18c9ad25 # v0.5.6
  d322f9ac6d41fd39f738025cc8f789e28db04e26 # v0.5.7
  f1543e8da74309619da6d71b220528e14ff54671 # v0.5.8
  eaa19c6ed47930f6297692c6d0333d9442b9d336 # v0.5.9
  89fd2602199ad99aec2216611d476b34667cf3d3 # v0.5.10
  945cf1693de2bbaff6c3aa17775d4e67d5454239 # v0.6.0
  f16e763abe006002f7ebf0c295f6bb13a9923a18 # v0.6.1
  2022a73303f6ba467c68d8b2660e64b21912a8cb # v0.6.2
  c86cebcb47b8d3ff1d82dc179215f1d812893ed4 # v0.6.3
  d634cd5e5a3740eb838fefdc63fa8d0320c62419 # v0.6.4
  ca2b714b409686fedf01426533395408a3f48d39 # v0.6.5
  36e98f7ee9c0ad96fd45d3289a1d2b931f0ae122 # v0.7.0
  3d9d4203485ff4e41b0d82527ba14d4a009d39a8 # v0.7.1
  495a8727a796871038c1adad5ffa9cab49f791a7 # v0.7.2
  f855592f8f073d749ad62301724b9b4ac22d2aa8 # v0.8.0
  e10b4533175aadcc5898afed0a623105a2605435 # v0.8.1
  9d9fa2f6a35aace70c2b1e2f4d59adac72f94463 # v0.8.2
  2c5d2994118ac803a87b44f0bd5ce21c5086f50e # v0.8.3
  ba2af7d4639f8977b10dfde927bf4beaf727f9d4 # v0.8.4
)

# this array contains rebased branch "version" commits a.k.a. release commits
# these can be easily acquired, since commit messages are well-formatted
REBASED_VER_COMMITS=(
  `git log --format="%H" --grep="build: increment" Cargo.toml | tac`
)

# if arrays are unexpectedly of different length, the script has to terminate - it makes no sense to continue
if [ "${#ORIG_VER_COMMITS[@]}" -ne "${#REBASED_VER_COMMITS[@]}" ]; then
  echo "${#ORIG_VER_COMMITS[@]}"
  echo "${#REBASED_VER_COMMITS[@]}"
  echo "Error: different number of release commits between original & rebased branches" >&2
  exit 1
fi

# initial cleanup
rm -rf "$ORIG_DIR"
rm -rf "$REBASED_DIR"
rm -rf "diffs"

# clone repo & duplicate the dir (one for original branch releases & other for rebased branch releases)
git clone "https://www.github.com/barter-rs/barter-rs" "$ORIG_DIR"
cp -r "$ORIG_DIR" "$REBASED_DIR"

# iterate over commit arrays, checkout given commits & compare the differences between git trees at that point in time
#  - this is a reliable method, since it takes into account all the changes that might have accumulated over time
#    (up until the release commit)
for i in $(seq 1 "${#ORIG_VER_COMMITS[@]}"); do
  echo "Info: Comparing versions ($i / ${#ORIG_VER_COMMITS[@]})"
  cd "$ORIG_DIR"
  git checkout -q "${ORIG_VER_COMMITS[$(($i-1))]}" # add -q flag to hide verbose git commit info
  orig_ver="$(grep -Eo '^version\s*=\s*"\d\.\d\.\d+"' Cargo.toml | tr -d ' "' | cut -d = -f2)"
  echo "Info: Checked out v$orig_ver (original branch - ${ORIG_VER_COMMITS[$(($i-1))]})"
  cd ..
  cd "$REBASED_DIR"
  git checkout -q "${REBASED_VER_COMMITS[$(($i-1))]}" # add -q flag to hide verbose git commit info
  rebased_ver="$(grep -Eo '^version\s*=\s*"\d\.\d\.\d+"' Cargo.toml | tr -d ' "' | cut -d = -f2)"
  echo "Info: Checked out v$rebased_ver (rebased branch - ${REBASED_VER_COMMITS[$(($i-1))]})"
  cd ..
  # check if captured version variables contain exactly 1 line and are not empty
  if [ -z "$orig_ver" ] && [ "$(echo $orig_ver | wc -l)" -ne 1 ]; then
    err="original repo contains an invalid Cargo.toml file - most likely due to a git conflict"
    break
  fi
  if [ -z "$orig_ver" ] && [ "$(echo $rebased_ver | wc -l)" -ne 1 ]; then
    err="rebased repo contains an invalid Cargo.toml file - most likely due to a git conflict"
    break
  fi
  if [ "$orig_ver" != "$rebased_ver" ]; then
    err="version mismatch occurred on original version $orig_ver / rebased version $rebased_ver"
    break
  fi
  # compare different branch git trees (a.k.a. directories) for differences
  #  (`-r` is recursive, `-q` is quiet / brief - e.g. only show which files differ)
  diff_output_quiet="$(diff -qr -x ".git" -x ".idea" -x "target" -x "Cargo.lock" "$ORIG_DIR" "$REBASED_DIR")"
  if [ ! -z "$diff_output_quiet" ]; then
    # if differences exist (they are not an empty string), re-run a full diff to capture content differences as well
    diff_output="$(diff -r -x ".git" -x ".idea" -x "target" -x "Cargo.lock" "$ORIG_DIR" "$REBASED_DIR")"
    echo "Warning: branches differ on v$orig_ver" >&2
    # create dir for saving `diff` outputs
    mkdir -p diffs
    # save content differences to a file named by a version
    echo "$diff_output" > "diffs/v$orig_ver.diff"
  else
    echo "Info: branch releases are identical for v$orig_ver"
  fi
done

# exit cleanup - remove cloned repos
rm -rf "$ORIG_DIR"
rm -rf "$REBASED_DIR"

if [ ! -z "$err" ]; then
  echo "Error: $err" >&2
  exit 1
fi

Verification process output log (sample)

Info: Comparing versions (1 / 42)
Info: Checked out v0.1.0 (original branch - 0d1467cc5a1b8318a3d2b4d941b1b8a38bd233a7)
Info: Checked out v0.1.0 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.1.0
Info: Comparing versions (2 / 42)
Info: Checked out v0.2.0 (original branch - 5dba365d1fd53630c7aa82943d3faa12aa27f835)
Info: Checked out v0.2.0 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.2.0
Info: Comparing versions (3 / 42)
Info: Checked out v0.2.1 (original branch - 1ff46f09f4db8003c816432c16e718e59e00fdd7)
Info: Checked out v0.2.1 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.2.1
Info: Comparing versions (4 / 42)
Info: Checked out v0.2.2 (original branch - 68d96309bff2a7fc367dd51b0d5120dc09fc46c6)
Info: Checked out v0.2.2 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.2.2
Info: Comparing versions (5 / 42)
Info: Checked out v0.2.3 (original branch - fd85e3d47348e6c772116e368eca253075ea6c00)
Info: Checked out v0.2.3 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.2.3
Info: Comparing versions (6 / 42)
Info: Checked out v0.2.4 (original branch - ef717c03418840dedfdfc2d95edf950f67ec9e6a)
Info: Checked out v0.2.4 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.2.4
Info: Comparing versions (7 / 42)
Info: Checked out v0.2.5 (original branch - 57ec50a8551455c5102b2082a56f89676ffd9be6)
Info: Checked out v0.2.5 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.2.5
Info: Comparing versions (8 / 42)
Info: Checked out v0.2.6 (original branch - 64de2b24a7c11391683c6265ffcb1e00e9a88aec)
Info: Checked out v0.2.6 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.2.6
Info: Comparing versions (9 / 42)
Info: Checked out v0.2.7 (original branch - 830c6c17e611107b53e49cdac44da99bade4687f)
Info: Checked out v0.2.7 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.2.7
Info: Comparing versions (10 / 42)
Info: Checked out v0.2.8 (original branch - 430a33b9df0052b24bd170a0f291847035ddbd1c)
Info: Checked out v0.2.8 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.2.8
Info: Comparing versions (11 / 42)
Info: Checked out v0.2.9 (original branch - 204b8f5ca50c260c41a1c1f7f6cdedfcd7f64dfd)
Info: Checked out v0.2.9 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.2.9
Info: Comparing versions (12 / 42)
Info: Checked out v0.2.10 (original branch - 22e0d1d765c64c172377b340716910fda1c4aa37)
Info: Checked out v0.2.10 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.2.10
Info: Comparing versions (13 / 42)
Info: Checked out v0.2.11 (original branch - 78ab53fa5a042eb56ece795fb0a6a5b0aceca7a8)
Info: Checked out v0.2.11 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.2.11
Info: Comparing versions (14 / 42)
Info: Checked out v0.3.0 (original branch - 25013f809da85bc5c20995397d20d170626bdcc9)
Info: Checked out v0.3.0 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.3.0
Info: Comparing versions (15 / 42)
Info: Checked out v0.3.1 (original branch - 557b926e3c202616734dc4a9605253c72416231e)
Info: Checked out v0.3.1 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.3.1
Info: Comparing versions (16 / 42)
Info: Checked out v0.4.0 (original branch - 5221bf49ce227268b2e6868c6055f200c6321d4b)
Info: Checked out v0.4.0 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.4.0
Info: Comparing versions (17 / 42)
Info: Checked out v0.4.1 (original branch - 56e5668ad8ccdf4df4c3a7183d045772aef8f151)
Info: Checked out v0.4.1 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.4.1
Info: Comparing versions (18 / 42)
Info: Checked out v0.5.0 (original branch - 6d27e30d0603683f2927c106646a3690a4939626)
Info: Checked out v0.5.0 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.5.0
Info: Comparing versions (19 / 42)
Info: Checked out v0.5.1 (original branch - 6e659b7601cf107f6716315f52be03827e910599)
Info: Checked out v0.5.1 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.5.1
Info: Comparing versions (20 / 42)
Info: Checked out v0.5.2 (original branch - 05830063457ae54db000a3158000a8dec3239fe6)
Info: Checked out v0.5.2 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.5.2
Info: Comparing versions (21 / 42)
Info: Checked out v0.5.3 (original branch - 5bae25abc4ed878269bc8df9b679ccf42e235fd3)
Info: Checked out v0.5.3 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.5.3
Info: Comparing versions (22 / 42)
Info: Checked out v0.5.4 (original branch - e9021da46717379615be01eadfc4ccae97422441)
Info: Checked out v0.5.4 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.5.4
Info: Comparing versions (23 / 42)
Info: Checked out v0.5.5 (original branch - 953a54cff61ab2dfc560f7adcf304a249aede437)
Info: Checked out v0.5.5 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.5.5
Info: Comparing versions (24 / 42)
Info: Checked out v0.5.6 (original branch - 3571f630d2913c76a5eb05e0891b5a3c18c9ad25)
Info: Checked out v0.5.6 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.5.6
Info: Comparing versions (25 / 42)
Info: Checked out v0.5.7 (original branch - d322f9ac6d41fd39f738025cc8f789e28db04e26)
Info: Checked out v0.5.7 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.5.7
Info: Comparing versions (26 / 42)
Info: Checked out v0.5.8 (original branch - f1543e8da74309619da6d71b220528e14ff54671)
Info: Checked out v0.5.8 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.5.8
Info: Comparing versions (27 / 42)
Info: Checked out v0.5.9 (original branch - eaa19c6ed47930f6297692c6d0333d9442b9d336)
Info: Checked out v0.5.9 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.5.9
Info: Comparing versions (28 / 42)
Info: Checked out v0.5.10 (original branch - 89fd2602199ad99aec2216611d476b34667cf3d3)
Info: Checked out v0.5.10 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.5.10
Info: Comparing versions (29 / 42)
Info: Checked out v0.6.0 (original branch - 945cf1693de2bbaff6c3aa17775d4e67d5454239)
Info: Checked out v0.6.0 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.6.0
Info: Comparing versions (30 / 42)
Info: Checked out v0.6.1 (original branch - f16e763abe006002f7ebf0c295f6bb13a9923a18)
Info: Checked out v0.6.1 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.6.1
Info: Comparing versions (31 / 42)
Info: Checked out v0.6.2 (original branch - 2022a73303f6ba467c68d8b2660e64b21912a8cb)
Info: Checked out v0.6.2 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.6.2
Info: Comparing versions (32 / 42)
Info: Checked out v0.6.3 (original branch - c86cebcb47b8d3ff1d82dc179215f1d812893ed4)
Info: Checked out v0.6.3 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.6.3
Info: Comparing versions (33 / 42)
Info: Checked out v0.6.4 (original branch - d634cd5e5a3740eb838fefdc63fa8d0320c62419)
Info: Checked out v0.6.4 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.6.4
Info: Comparing versions (34 / 42)
Info: Checked out v0.6.5 (original branch - ca2b714b409686fedf01426533395408a3f48d39)
Info: Checked out v0.6.5 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.6.5
Info: Comparing versions (35 / 42)
Info: Checked out v0.7.0 (original branch - 36e98f7ee9c0ad96fd45d3289a1d2b931f0ae122)
Info: Checked out v0.7.0 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.7.0
Info: Comparing versions (36 / 42)
Info: Checked out v0.7.1 (original branch - 3d9d4203485ff4e41b0d82527ba14d4a009d39a8)
Info: Checked out v0.7.1 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.7.1
Info: Comparing versions (37 / 42)
Info: Checked out v0.7.2 (original branch - 495a8727a796871038c1adad5ffa9cab49f791a7)
Info: Checked out v0.7.2 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.7.2
Info: Comparing versions (38 / 42)
Info: Checked out v0.8.0 (original branch - f855592f8f073d749ad62301724b9b4ac22d2aa8)
Info: Checked out v0.8.0 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.8.0
Info: Comparing versions (39 / 42)
Info: Checked out v0.8.1 (original branch - e10b4533175aadcc5898afed0a623105a2605435)
Info: Checked out v0.8.1 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.8.1
Info: Comparing versions (40 / 42)
Info: Checked out v0.8.2 (original branch - 9d9fa2f6a35aace70c2b1e2f4d59adac72f94463)
Info: Checked out v0.8.2 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.8.2
Info: Comparing versions (41 / 42)
Info: Checked out v0.8.3 (original branch - 2c5d2994118ac803a87b44f0bd5ce21c5086f50e)
Info: Checked out v0.8.3 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.8.3
Info: Comparing versions (42 / 42)
Info: Checked out v0.8.4 (original branch - ba2af7d4639f8977b10dfde927bf4beaf727f9d4)
Info: Checked out v0.8.4 (rebased branch - <some SHA-1 hash>)
Info: branch releases are identical for v0.8.4

Migration (merging issues)

If you run into issues while attempting to merge your forked branch back into this rebased develop-new branch,
here are the steps you need to take to solve the issues:

Backup your branch just in case something goes wrong
- run git checkout <mybranch>; git checkout -b <mybranch-backup>; git checkout <mybranch>
  (if not already checked out)
Update your branch / sync it with develop-old branch (either via rebase or merge)
Rebase onto develop-new branch
- run git rebase --onto develop-new develop-old
That's it! Very simple & easy
If you run into problems by any chance (highly unlikely), you could consider few alternatives
- contact me (@carpetmaker), I can help you resolve it quickly, or do the migration / merge for you
- git cherry-pick all of your commits (which haven't yet been merged into develop-old branch) into a new branch
  based off / branched (forked) from develop-new
- export all of your unmerged commits (read above) with git format-patch and apply them to your newly created
  branch via git am (essentially the same as cherry-picking)

OFAQ (Opponent Frequently Asked Questions)

This section is meant for individual(s) who might oppose to the idea of this proposal,
and offers an alternative view in form of common answers for common questions you (or they) might ask.

Why rebasing?? My boss / co-worker / friend / cousin / joe / medium.com article told me that rebasing is bad?? We should never rebase, it is forbidden!

Well, such a generalised statement assumes some level of ignorance from your end.
Sure, if you are a dev who is just starting out and have an intern-level skills & experience, or are afraid of git,
then yes, treating the git tool as a black box, and avoiding common sources of problems & complications,
such as rebasing, might be a smart approach.
But if you take your time to actually dive deeper into how git works,
then there is no reason to be afraid of some more aggressive git tasks,
as long as nothing breaks & all the existing constraints are satisfied.
Who cares?? Who cares about the git history, commit messages and branches organisation...

Well, who cares about the version control at all? Why not just pack your code changes into a ZIP file,
upload it to Google Drive and share the link to other devs who want to collaborate?
Or even better, why not print out the new code which you wrote, pack it into an envelope / letter,
and ship it via postal service or use a homing pigeon who will deliver it to other devs?
We can go on and on like this... Same mentality, same level of ignorance, same answer.
Projects which have ambitions for growing and want to onboard a lot of new contributors (which we hope for here)
need a modern collaboration tools & approaches. Stricter order means less chaos, and more progress & advancement.
Changes are bad... I am afraid of changes, it will break my current and future commits!

Is this really a question?
Anyhow, if you have read this verbose & overly-explained proposal writeup up to this point,
then you would've understood that nothing will actually break, and you won't have any problems merging your changes,
or submitting new PRs in future.

Future Considerations

There are some minor additional items which should be considered in future.
For one, all the future contributions should continue to respect the conventions discussed in this proposal,
and improve the overall quality of project code & structure.
Another thing, there is some concrete room for a future improvement:

commit message length should be limited (open for discussion, might be too strict of a rule)
- titles / subject lines should be no longer than 50 characters (currently, a limit of 100 is enforced)
- body lines should be no longer than 72 characters each
commit messages should also utilise body which is separated from title by an empty line
- either always or only when the commit message is too long to fit into a descriptive title (open for discussion)
commits should be formed in such a way to strictly contain only changes of a single particular topic: type:
- feat
- fix
- test
- refactor
- perf
- style
- docs
- build
- chore
- ci
- revert
historical commits could be squashed into a single commit per version release, with their messages added to the body
all these conventions can and will be documented in a dedicated docs/CONTRIBUTING.md file

Conclusion

Pls just approve this proposal (and its associated PR) and let me take care of this stuff, I can handle it. Thx!

Outro

If any other contributor experiences issues with merging their work back to the repo (which is highly unlikely),
I am always available for one-on-one consultations, to help them resolve the issues without any trouble or pain.
But most likely, the problems won't even occur, or will be solved by running a single git rebase command
(git rebase --onto develop-new develop-old if you will) in the worst-case scenario. But I repeat, unlikely.

Thanks for taking your time to read this!

Sincerely,

@carpetmaker

Progress

This is a list of items which need to be performed:

rewrite barter-rs project git repo history
rewrite barter-data-rs project git repo history
rewrite barter-integration-rs project git repo history
rewrite barter-execution-rs project git repo history

The text was updated successfully, but these errors were encountered:

just-a-stream · 2022-10-18T19:53:09Z

LGTM

Michael-J-Ward · 2022-10-27T21:13:55Z

Are barter data and barter integration rewrites in progress?

sjmackenzie · 2024-05-05T03:33:07Z

Wanted to pop by and say this is very good code @just-a-stream you're doing well.

Points I'd like to suggest: drop the whole gitflow model, it's chaotic and will lead to more pain and frustration that anything else. I'd suggest using Pieter Hintjens C4 for optimal efficiency. Right down to structuring the commit messages and trunk based development. My 2c worth!

@just-a-stream I'm curious to get to know you personally by interviewing you. If you're up for it, do shoot me an email!

Thank you,
Stewart

c10k-cc added the issue::enhancement Issue which addresses a new feature request or proposal label Oct 16, 2022

This was referenced Oct 16, 2022

Rewrite project history #6

Closed

Rewrite project history (minimum git tree modifications) #7

Closed

c10k-cc self-assigned this Oct 17, 2022

This was linked to pull requests Oct 17, 2022

Rewrite project history #6

Closed

Rewrite project history (minimum git tree modifications) #7

Closed

c10k-cc added issue::meta Issue which addresses the project organisation, workflow and / or repository itself issue::crossrepo Issue which relates to multiple project repositories labels Oct 18, 2022

This was referenced Oct 18, 2022

Add GitHub Action for code testing barter-rs/barter-data-rs#5

Open

Rewrite project history (minimal changes) #11

Merged

c10k-cc mentioned this issue Oct 19, 2022

Rewrite project history (minimal changes) barter-rs/barter-execution-rs#1

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Rewrite project history #5

Rewrite project history #5

c10k-cc commented Oct 16, 2022 •

edited

just-a-stream commented Oct 18, 2022

Michael-J-Ward commented Oct 27, 2022

sjmackenzie commented May 5, 2024

Rewrite project history #5

Rewrite project history #5

Comments

c10k-cc commented Oct 16, 2022 • edited

Rewrite project history

Summary

Description

About

Intro

Motivation

Constraints

Changes applied

Achieved improvements

Verification (steps to verify / reproduce the results)?

Migration (merging issues)

OFAQ (Opponent Frequently Asked Questions)

Future Considerations

Conclusion

Outro

Progress

just-a-stream commented Oct 18, 2022

Michael-J-Ward commented Oct 27, 2022

sjmackenzie commented May 5, 2024

c10k-cc commented Oct 16, 2022 •

edited