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

Jump to bottom

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

Merged
merged 2 commits into from May 18, 2020
Merged

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

merged 2 commits into from May 18, 2020

Conversation

primeos
Copy link
Member

@primeos 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.

@primeos primeos mentioned this pull request May 4, 2020
Closed
@ofborg ofborg bot requested review from the-kenny, wmertens, globin and peti May 4, 2020 21:58
@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 •
edited

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

  • 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
git: Add a doc output for the HTML and text files
54918d6 
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 NixOS#86022 (at least partly since the output has to be installed).
@primeos
git-doc: init
9f2faa1
@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
Staging automation moved this from Needs review to Done May 18, 2020
vcunat added a commit that referenced this pull request Jun 9, 2020
@vcunat
gitMinimal: fix build after PR #86848
0b4afef 
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
Reviewers

@the-kenny the-kenny Awaiting requested review from the-kenny

@wmertens wmertens Awaiting requested review from wmertens

@globin globin Awaiting requested review from globin

@peti peti Awaiting requested review from peti

Assignees
No one assigned
Labels
6.topic: nixos 8.has: changelog 8.has: documentation 10.rebuild-darwin: 501-1000 10.rebuild-darwin: 501+ 10.rebuild-linux: 501+ 10.rebuild-linux: 1001-2500
Projects
Staging
  
Done
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

None yet
2 participants
@primeos @wmertens