Document the relationship between ComponentId, UnitId, MungedPackageId, PackageId etc.
- Dominant language
- Haskell
- Stars
- 1.7k
- Forks
- 750
- Avg merge
- 4d 3h
- Merged PRs (30d)
- 28
Description
There are these types: `ComponentId`, `UnitId`, `MungedPackageId`, `PackageId` etc. which all seems to be *same same but different*. There should be a **technical note** in the code describing their relationship, with
- links issues describing planned clean ups to be done (and what's blocking them, if they cannot be done)
- whether the types are intended to be used in public text-based APIs
- with remarks what's the current state, previous point
- haddocks of these types pointing to the note.
---
Honestly, I have no idea what are the subtle differences about these types, and I won't read through GitHub issues to find out. The note in the code would be the right place to refer.
---
As an example, `ComponentId` is documented as
> For non-Backpack components, this corresponds one to one with
> the 'UnitId', which serves as the basis for install paths,
> linker symbols, etc.
And there are no remarks how things are different in Backpack case.
---
Related issue https://github.com/haskell/cabal/issues/4761
There is a *Mapping from semantic objects in this thesis (Fig. 3.5 and Fig. 6.1) to their definitions
in GHC* table in Edwards thesis. Something similar but for Cabal types would be great to have too.
Contributor guide
Assessment
This issue has not been assessed yet.