|
1 | | -# traceviewer-libs |
2 | | -Trace viewer libraries: traceviewer-base and traceviewer-react-components |
| 1 | +# Trace Viewer Libraries (git subtree) |
| 2 | + |
| 3 | +This repository contains the trace viewer libraries and minimal infrastructure to maintain them in source code form: |
| 4 | + |
| 5 | +- `traceviewer-base` and |
| 6 | +- `traceviewer-react-components` |
| 7 | + |
| 8 | +The libraries are meant to provide generally useful building blocks for making a Trace Viewer application based on the Trace Server Protocol (TSP). They are used in at least two components: |
| 9 | + |
| 10 | +- The VSCode Trace Viewer extension ([repo](https://github.com/eclipse-cdt-cloud/vscode-trace-extension)) |
| 11 | +- The Theia Trace Viewer extension ([repo](https://github.com/eclipse-cdt-cloud/theia-trace-extension)) |
| 12 | + |
| 13 | +It's possible to update the libraries using this repo here, but it might be preferable to update the local version, that's a copy of their source code, imported as a git subtree. In other words, this repo here is best used as for collaboration, where to share improvements to the libraries done in a local subtree, or to pull improvements done by someone else. |
| 14 | + |
| 15 | +## Why split the trace viewer libraries in their own repo? |
| 16 | + |
| 17 | +For historical reasons, the libraries were initially co-located with the Theia Trace Viewer and consumed in source form (built along with it) during development, making co-development easy. They were published to npm as needed, along with the extension. In the VSCode Trace Viewer extension, the libraries were consumed from npm at build time and bundled with the published extension (to the Microsoft Marketplace and Open VSX registry). This made it a lot more challenging to co-develop the VSCode Trace Viewer and the `traceviewer` libraries. |
| 18 | + |
| 19 | +We considered several ways to improve upon this situation, with the following goals: |
| 20 | + |
| 21 | +- Trace Viewer app/extension feature development testing and upstreaming: make it as easy as possible for all consumer of the libraries. Specially when the libraries need to be updated along with the consuming component. |
| 22 | +- Collaboration on the libraries: make it as simple as possible, so that consumers can share improvements and new features they added |
| 23 | +- Preserve git authorship contribution history even if the libraries are moved to a new repository |
| 24 | + |
| 25 | +The solution we picked is to use a `git subtree`. This involved splitting-out the trace viewer libraries from their original development location with `git subtree split`, without using the `--squash` option, so history is preserved. This repo here is the result of that operation, plus some minimal added infrastructure. |
| 26 | + |
| 27 | +In a separate step, this repo can be used in `vscode-trace-extension`, to "import" a local version of the libraries, as a git subtree. |
| 28 | + |
| 29 | +## How it was done |
| 30 | + |
| 31 | +The `traceviewer-*` libraries were split-out from `theia-trace-extension` repo like so: |
| 32 | + |
| 33 | +```bash |
| 34 | +cd theia-trace-extension |
| 35 | +git checkout master |
| 36 | +# update local branch to latest master |
| 37 | +git pull origin master |
| 38 | +# clean all local files |
| 39 | +git clean -ffdx |
| 40 | + |
| 41 | + |
| 42 | +# split content of the "packages" folder (where the traceviewer |
| 43 | +# libraries are). Put the resulting content on a branch called |
| 44 | +# "traceviewer-libs-branch" |
| 45 | +git subtree split --prefix=packages --branch traceviewer-libs-branch |
| 46 | + |
| 47 | +``` |
| 48 | + |
| 49 | +Note: by itself, the above does not remove the original libraries from the main branch of the `theia-trace-extension` repository. |
| 50 | + |
| 51 | +## TODO |
| 52 | + |
| 53 | +### ~~Push the `traceviewer-libs-branch` git subtree to its own repository~~ |
| 54 | + |
| 55 | +Below is how it was done for validation purposes. This can be repeated with an official repository, under the "eclipse-cdt-cloud" GitHub organization |
| 56 | + |
| 57 | +1) Open a ticket on the Eclipse Foundation Gitlab and ask for an empty repo to be created, named "traceviewer-libs" |
| 58 | +2) When done, push the latest version of the subtree branch to it (note: use the correct repo URL - below used a committer's GitHub): |
| 59 | + |
| 60 | +```bash |
| 61 | +git remote add traceviewer-libs [email protected]:marcdumais-work/traceviewer-libs.git |
| 62 | +git push traceviewer-libs traceviewer-libs-branch:master |
| 63 | + |
| 64 | +``` |
| 65 | + |
| 66 | +Depending how the repo it setup, it may be necessary to push to a PR branch and merge to master after a review. |
| 67 | + |
| 68 | +## Use the subtree in another repo |
| 69 | + |
| 70 | +### How to use the `traceviewer-libs` subtree in another repository |
| 71 | + |
| 72 | +This is an example on how to add the subtree to a repo, replacing that repo consuming the |
| 73 | +libraries from npm. |
| 74 | + |
| 75 | +```bash |
| 76 | +cd vscode-trace-extension |
| 77 | +# when available, use the official "eclipse-cdt-cloud" subtree repo instead |
| 78 | +git remote add traceviewer-libs [email protected]:marcdumais-work/traceviewer-libs.git |
| 79 | +git subtree add --prefix=traceviewer-libs traceviewer-libs master --squash |
| 80 | + |
| 81 | +``` |
| 82 | + |
| 83 | +In the root package.json, add the libraries in the "workspaces" array: |
| 84 | +"workspaces": [ |
| 85 | + [...] |
| 86 | + "local-libs/traceviewer-libs/*" |
| 87 | + [...] |
| 88 | +} |
| 89 | + |
| 90 | +More changes/tweaks might be necessary. |
| 91 | + |
| 92 | + |
| 93 | +### Push local changes made to the subtree towards the subtree repo |
| 94 | + |
| 95 | +```bash |
| 96 | +git subtree push -p <subtree folder> <subtree remote repo> <remote review branch> |
| 97 | + |
| 98 | +``` |
| 99 | + |
| 100 | +### Pulling latest changes from the subtree repo into the local subtree |
| 101 | + |
| 102 | +```bash |
| 103 | +# make sure your local master is up-to-date: |
| 104 | +git checkout master && git pull origin master |
| 105 | +git branch update-subtree && git checkout update-subtree |
| 106 | +git subtree pull --prefix=<local subtree folder> <subtree remote repo> master --squash |
| 107 | + |
| 108 | +e.g.: |
| 109 | +git subtree pull --prefix=local-libs/traceviewer-react traceviewer-react master --squash |
| 110 | + |
| 111 | +# push update branch and create a PR from it, have it reviewed and merged ASAP: |
| 112 | +git push origin update-subtree |
| 113 | + |
| 114 | +``` |
| 115 | + |
0 commit comments