How we migrated postcss-preset-env to a mono repo. #162
romainmenke
announced in
Announcements
Replies: 1 comment
-
|
Update (2022-06-02) : 4 more plugins were migrated to this mono repo yesterday and will now be maintained from here.
Latest git history animation : https://www.youtube.com/watch?v=SdJ5_ab1n6s |
Beta Was this translation helpful? Give feedback.
0 replies
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
When working on PostCSS 8 compatibility we had to update each plugin individually.
Some had other or more modern build processes than others.
Others had unexpected down stream effects when making a change.
We had no way to quickly iterate and test the whole thing as each plugin was isolated in its own repository.
With native support for mono repo's in npm 7, we saw a way forward that didn't involve adding more tools or complexity.
Constraints and tools for the migration.
Preserving the git history
Simply moving the files from all plugins to a new repo would lose the git history and all the attributions to people who have spend so many hours on this project.
We needed two things to preserve the git history:
This would allow us to move
csstools/postcss-preset-env/README.mdtocsstools/postcss-plugins/plugin-packs/postcss-preset-env/README.md.For these operations we used :
git format-patchgit am --directorygit format-patch
The first step was to gather all commits for all previous repositories and store them as git patches.
git format-patchis excellent for this and allowed us to convert commits into plain text files.get patches script
All the patches are stored in a separate repository. This allows anyone to inspect the history of the patches and verify what was changed.
git am
After all patches were gathered we could apply them to the new repo with
git am.--no-gpg-signWe intentionally added the
--no-gpg-signas signing the commits gives a false signal. Signed commits are supposed to verify that the author is who they say they are.In this case we know that the committer is not the author and that these commits must not be trusted purely because services like GitHub display a trust label.
Having transparency about what should be distrusted allows the community to scrutinize these commits.
--directoryThe
--directoryoption allowed us to apply the patches to a different directory.This does not change the history of the commits and does not appear as a file move. The patches are applied as if the original commits were in the new repo in their final directory.
This is crucial to be able to inspect the git history for each file.
Unified git history
Having a unified git history also allows us to do fun stuff like creating a Gource video for the entire project :
Watch the video on YouTube.
Preserving contributors
git format-patchandgit ampreserve the original author and author date for each commit.At the time of writing we had 84 contributors with over a 1000 commits for all plugins combined, starting on 27 July 2014.
intact links to issues and pull requests
When referencing issues in commits or merging pull requests, the commit messages often have
#123style references.These link to issues and pull requests in the current repository.
If we applied these commit messages they would incorrectly reference issues and pull requests in the new repository as that would then become the current repository.
To correct this, we followed GitHub docs to reference issues in other repositories and changed each commit message with this script.
When browsing the git history in the new repository you can easily go back to the original issue or pull request to get more context on the commit.
transparency on who authored a commit and who moved it
This is another nice feature of using
git format-patchandgit am.Each commit moved to the mono repo has the original author and committer listed as the author and
romainmenke(me) as the committer.This makes it clear who authored the commit and who moved it.
transparency on how a commit moved from one repo to another
All the scripts, patches and history of modifications to the patches are preserved in a separate repository.
Anyone can inspect the scripts and even re-run the migration.
This makes it possible to do an audit of this process and verify that no malicious bits were added.
Running the migration
As everything was still in flux with the updates for PostCSS 8 we expected that we would have to keep working from the old repositories for some time.
At first the migration was only tested locally and re-run after each change in any of the repositories.
During this time the general setup was created to have a shared build process, CI, ...
Once every plugin was updated to PostCSS 8 and released, we did a final migration and pushed for the first time to csstools/postcss-plugins.
This was not without risk because we would create issue and pull requests references. Github creates inverse links for each reference and having to re-run the migration would cause duplicates and confusion.
Post Migration
It still took considerable time to clean up each plugin.
Each had to work correctly with the same build process and pass the same style of tests and checks.
This required analysis of the current build process and output artifacts to make sure we matched these without ending up with ±15 different build processes.
This took a couple of weeks to complete during which more changes were made to the original repositories.
Each commit made after the migration was manually moved and applied to the new repo.
Dev tools :
With everything in a single repository the cost/benefit tradeoff changes drastically.
postcss-preset-envIn closing
This migration has been executed with profound respect for all the work the came before.
We hope that the current setup will prove to be sustainable for the coming years so that
postcss-preset-envcan continue to grow.Beta Was this translation helpful? Give feedback.
All reactions