Repository navigation
Add a design doc - #27
harendra-kumar wants to merge 11 commits into
Conversation
e0a784a to
1aa4d00
Compare
Split the code into PackDiff.* library modules and add the diff, check and api commands. Refs can be git revisions (including other local or remote repositories), the working directory, Hackage releases or hoogle files. Git refs are built in temporary work clones, hoogle files are cached, and the output uses sigils, a summary, colors, filtering and grouping by change. check reports the required PVP bump, and exit codes support CI use. Add golden tests, a cabal.project with a GHC heap limit, and dev/upstream-fixes.md listing workarounds for missing upstream features.
--expand lists the symbols of added and removed modules under their module lines. --collapse and --expand cannot be used together.
Use parserOptionGroup from optparse-applicative 0.19 to show the options under Source options, Module selection, Build options, Output options, Change filters and Help options. Pin optparse-applicative 0.19.0.0 in sources.nix for the nix shell.
The sdist check failed on cabal.project and sources.nix, which are not part of the source distribution. Without CABAL_PROJECT, packcheck removes cabal.project for the sdist build, but streamly-coreutils is only available through its source-repository-package. Also run hlint on cli and test.
8a1b0fa to
64926db
Compare
adithyaov
left a comment
adithyaov
left a comment
There was a problem hiding this comment.
I've only reviewed the design document.
| @@ -0,0 +1,923 @@ | |||
| # packdiff CLI Design | |||
There was a problem hiding this comment.
Does the design document need to be elaborate?
If the goal is to give an idea to the user, we could try to unverbose it.
| depends on the refs. This section also belongs in the user | ||
| documentation. | ||
|
|
||
| | Program | Needed for | |
There was a problem hiding this comment.
Just listing the programs may be enough
| | `ghc` | Same as `cabal`. Selected with `-w`; otherwise the `ghc` in `PATH`. | | ||
| | `haddock` | Same as `cabal`. cabal uses the `haddock` that matches the selected `ghc`. | | ||
|
|
||
| Network access is needed for: |
There was a problem hiding this comment.
Just listing the programs may be enough.
|
|
||
| ```sh | ||
| # two tags of a remote repository, without a local clone | ||
| packdiff diff --repo https://github.com/composewell/streamly v0.9.0 v0.10.0 |
There was a problem hiding this comment.
Should we change the usage to
packcheck diff github@composewell/streamly:v0.9.0 ../path...
to keep it consistent?
Sources:
- hackage:
- github@/: (alias to proper git url)
- <local_path>
- proper git url
There was a problem hiding this comment.
| that are not git refs, e.g. `--old-repo` with a `hackage:` or `file:` | ||
| `ref1`, or `--new-repo` with `.` as `ref2`. | ||
|
|
||
| ### Package selection |
There was a problem hiding this comment.
Maybe just having examples will help? If anyone requires more information on the design, they should look at the code.
The effort of reading plain text and haskell functionality is the same. Haskell may be easier to ingest :)
| magenta. In a pair of `-` and `+` lines, the parts that differ are | ||
| highlighted, so a changed constraint in a long signature stands out. | ||
|
|
||
| ### Line structure |
There was a problem hiding this comment.
For scripts, we can possibly just export in json.
| * A stable hash for cache keys and work clone names, e.g. 64-bit | ||
| FNV-1a. `hashable` is not used because its output may change between | ||
| versions, which would invalidate names on disk. | ||
| * Glob matching for `--module`, `--ignore-module` and | ||
| `--internal-module`, supporting only `*`. | ||
| * Highlighting the differing parts of `-` and `+` lines: drop the | ||
| common token prefix and suffix using streamly-core's | ||
| `dropCommonPrefixBy` and highlight the rest. |
There was a problem hiding this comment.
We can keep these design decisions but the rest of the text is given by looking at the cabal file.
| packdiff uses the hoogle file produced by haddock. Three limitations | ||
| follow from this. | ||
|
|
||
| ### 1. Unexposed modules are excluded |
There was a problem hiding this comment.
This however can be bypassed by just replacing "other-modules" with "exported-modules".
| exists only if the package was installed with its documentation. | ||
| Dependencies: no new library; the `ghc-pkg` program, which ships | ||
| with GHC. | ||
| * Show the documentation of a single entity, `package:module:name`. |
There was a problem hiding this comment.
We should not make packdiff a multipurpose tool. If it comes to that, we should just split it, I suppose.
| * Show the documentation of a single entity, `package:module:name`. | ||
| The parser already keeps the documentation of each entity. | ||
| Dependencies: none. | ||
| * `--old-cabal-option` and `--new-cabal-option`: cabal options for |
There was a problem hiding this comment.
This is not necessary. The users have all the power in the world to generate the .txt files and compare them.
2 participants
Will make any new changes according to the doc.