Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

git: Add a doc output for the HTML and text files #86848

Merged
merged 2 commits into from May 18, 2020

Conversation

@primeos
Copy link
Member

primeos commented May 4, 2020

This will install the HTML and text documentation into a separate output
so that users can install it without having to rebuild Git.
Previously only doc/git/git-subtree.html was installed (which is now
in $doc as well).
The current output sizes are as follows:

$ du -sh $(nix-build -A git)
47M     /nix/store/wyqgalp61kmavx06rams7z8jz177nd8y-git-2.26.2
$ du -sh $(nix-build -A git.doc)
14M     /nix/store/6zi22fl5xc3sg23d9shsviinvwk89wvq-git-2.26.2-doc

Fixes #86022 (at least partly since the output has to be installed).

Motivation for this change

This is a draft for #86022. It basically works, but we could e.g. discuss if we should install this output by default for gitFull among other things.

Things done
  • Tested using sandboxing (nix.useSandbox on NixOS, or option sandbox in nix.conf on non-NixOS linux)
  • Built on platform(s)
    • NixOS
    • macOS
    • other Linux distributions
  • Tested via one or more NixOS test(s) if existing and applicable for the change (look inside nixos/tests)
  • Tested compilation of all pkgs that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review wip"
  • Tested execution of all binary files (usually in ./result/bin/)
  • Determined the impact on package closure size (by running nix path-info -S before and after)
  • Ensured that relevant documentation is up to date
  • Fits CONTRIBUTING.md.
@wmertens
Copy link
Contributor

wmertens commented May 6, 2020

LGTM - not sure if gitFull should get the doc; the man pages are still available right?

@primeos
Copy link
Member Author

primeos commented May 6, 2020

the man pages are still available right?

Yes. And to document the exact file changes:

  • $out: Only that share/doc/git/git-subtree.html is now in $doc
  • $doc: Now contains share/doc/git/{,RelNotes,technical,howto} with .html and .txt files (and one CSS file)
@wmertens
Copy link
Contributor

wmertens commented May 6, 2020

I'm ok with merging, the only reservation I have is that the doc output isn't very discoverable, so people looking for the info or docs have to know to install it. Or is there a nixpkgs-wide setting?

@primeos
Copy link
Member Author

primeos commented May 6, 2020

the only reservation I have is that the doc output isn't very discoverable

Yes, that's unfortunate and AFAIK we don't have a good solution for this (we could add an alias like git-doc = git.doc or a flag like withDocumentation ? false but both of those seem to make things only worse).

Or is there a nixpkgs-wide setting?

On NixOS there's environment.extraOutputsToInstall but I doubt that many use it for doc.

@FRidh FRidh added this to WIP in Staging via automation May 8, 2020
@FRidh FRidh moved this from WIP to Needs review in Staging May 8, 2020
@wmertens
Copy link
Contributor

wmertens commented May 18, 2020

  • I like adding the git-doc attribute, at least that will show up in nix search git, no?
  • Let's add something to the changelog
  • Other than that, LGTM
primeos added 2 commits May 4, 2020
This will install the HTML and text documentation into a separate output
so that users can install it without having to rebuild Git.
Previously only `doc/git/git-subtree.html` was installed (which is now
in $doc as well).
The current output sizes are as follows:
```
$ du -sh $(nix-build -A git)
47M     /nix/store/wyqgalp61kmavx06rams7z8jz177nd8y-git-2.26.2
$ du -sh $(nix-build -A git.doc)
14M     /nix/store/6zi22fl5xc3sg23d9shsviinvwk89wvq-git-2.26.2-doc
```

Fixes #86022 (at least partly since the output has to be installed).
@primeos
Copy link
Member Author

primeos commented May 18, 2020

@wmertens I applied your changes, feel free to squash the commits (the second one is only for reviewing).

I like adding the git-doc attribute, at least that will show up in nix search git, no?

Yes, git-doc will now appear in nix search git.

Let's add something to the changelog

I'm not sure if this change is important enough (mainly since it's difficult to filter the changelog for relevant entries), but I've added a short note anyway ;)

@wmertens wmertens merged commit fd05023 into NixOS:staging May 18, 2020
2 of 4 checks passed
2 of 4 checks passed
grahamcofborg-eval Complete, with errors
Details
grahamcofborg-eval-lib-tests nix-build --arg pkgs import ./. {} ./lib/tests/release.nix
Details
grahamcofborg-eval-package-list nix-env -qa --json --file .
Details
grahamcofborg-eval-package-list-no-aliases nix-env -qa --json --file . --arg config { allowAliases = false; }
Details
Staging automation moved this from Needs review to Done May 18, 2020
vcunat added a commit that referenced this pull request Jun 9, 2020
In that case it specified $doc output but didn't even create it.
I expect it's better to do it this way instead of creating it
as an empty directory.
(Only the failed builds get rebuilt by this commit.)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Staging
  
Done
Linked issues

Successfully merging this pull request may close these issues.

None yet

2 participants
You can’t perform that action at this time.