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

Regenerate ChangeLog file only if git metadata got updated #2435

Merged
merged 4 commits into from
May 11, 2024

Conversation

jimklimov
Copy link
Member

@jimklimov jimklimov commented May 10, 2024

This should allow for some faster development cycles (not causing ChangeLog re-generation for every call that resolves to make ChangeLog, and subsequently taking a minutes or two for the HTML/PDF variants of the huge file).

Goes into guts of Git a bit too much, maybe, but this particular recipe is about being intimate with it anyway, and at worst we would keep generating the file when maybe we should not (if git repo filesystem backend design changes).

Should also help with networkupstools/nut-website#52 tangentially (at least regarding development cycles to fix that).

Example results in a nut-website build area (where nut is a submodule):

~/nut-website/nut$ ls -la .git
-rw-r--r-- 1 jim jim 28 Sep 12  2022 .git

~/nut-website/nut$ cat .git
gitdir: ../.git/modules/nut

~/nut-website/nut$ touch ../.git/modules/nut/HEAD
~/nut-website/nut$ time make ChangeLog
make[1]: Entering directory '/home/jim/nut-website/nut'
  DOC-CHANGELOG-GENERATE        /home/jim/nut-website/nut/ChangeLog
make[1]: Leaving directory '/home/jim/nut-website/nut'

real    0m3.484s
user    0m3.293s
sys     0m0.384s

~/nut-website/nut$ time make ChangeLog
make[1]: Entering directory '/home/jim/nut-website/nut'
  DOC-CHANGELOG-GENERATE        /home/jim/nut-website/nut/ChangeLog : SKIP (keep existing)
Using still-valid ChangeLog file generated earlier from same revision of Git source metadata in '../.git/modules/nut'
make[1]: Leaving directory '/home/jim/nut-website/nut'

real    0m0.020s
user    0m0.015s
sys     0m0.006s

The actual impact is about HTML/PDF files however - or rather about avoiding the remakes where possible:

~/nut-website/nut$ (cd docs/ && time make ChangeLog.pdf)
  DOC-CHANGELOG-ASCIIDOC        ../ChangeLog => ../ChangeLog.adoc
  DOC-ASCIIDOC-GITHUB-LINKS    Parsing GitHub link patterns ../ChangeLog.adoc => ../ChangeLog.adoc-parsed
  DOC-PDF  Generating ChangeLog.pdf
a2x: WARNING: --destination-dir option is only applicable to HTML and manpage based outputs

real    1m1.160s
user    1m0.312s
sys     0m0.622s

~/nut-website/nut$ (cd docs/ && time make ChangeLog.html)
  DOC-HTML Generating ChangeLog.html

real    0m14.491s
user    0m14.112s
sys     0m0.335s

### And re-runs are now no-ops:
~/nut-website/nut$ (cd docs/ && time make ChangeLog.html ChangeLog.pdf)
  DOC-CHANGELOG-GENERATE        ../ChangeLog : call parent Makefile
make[1]: Entering directory '/home/jim/nut-website/nut'
make[2]: Entering directory '/home/jim/nut-website/nut'
  DOC-CHANGELOG-GENERATE        /home/jim/nut-website/nut/ChangeLog : SKIP (keep existing)
Using still-valid ChangeLog file generated earlier from same revision of Git source metadata in '../.git/modules/nut'
make[2]: Leaving directory '/home/jim/nut-website/nut'
make[1]: Leaving directory '/home/jim/nut-website/nut'

real    0m0.028s
user    0m0.013s
sys     0m0.015s


### However, a Git change does cause a new document to appear:
~/nut-website/nut$ touch ../.git/modules/nut/HEAD
~/nut-website/nut$ (cd docs/ && time make ChangeLog.html)
  DOC-CHANGELOG-GENERATE        ../ChangeLog : call parent Makefile
make[1]: Entering directory '/home/jim/nut-website/nut'
make[2]: Entering directory '/home/jim/nut-website/nut'
  DOC-CHANGELOG-GENERATE        /home/jim/nut-website/nut/ChangeLog
make[2]: Leaving directory '/home/jim/nut-website/nut'
make[1]: Leaving directory '/home/jim/nut-website/nut'
  DOC-CHANGELOG-ASCIIDOC        ../ChangeLog => ../ChangeLog.adoc
  DOC-ASCIIDOC-GITHUB-LINKS    Parsing GitHub link patterns ../ChangeLog.adoc => ../ChangeLog.adoc-parsed
  DOC-HTML Generating ChangeLog.html

real    0m17.942s
user    0m17.504s
sys     0m0.663s

…le is newer than .git/HEAD [networkupstools/nut-website#52]

    if test -e .git/HEAD && ( rm -f "`find "$@" -not -newer .git/HEAD`" || true ) 2>/dev/null && ls -la .git/HEAD "$@" 2>/dev/null ; then SKIP ; else WORK ; fi

Hopefully this takes care of corner cases:

* No .git/HEAD => WORK (may be unsuccessfully, maybe not - e.g. Git submodules referring to parent)
* `rm` fails, maybe `find` returns empty => DON'T CARE, go to LS
* `ls` fails (one of target files is absent - e.g. ChangeLog removed or never was there) => WORK

Only if the ChangeLog is still there after the attempt on its life, SKIP and keep it

Signed-off-by: Jim Klimov <[email protected]>
…le is newer than anything in a NUT_GITDIR (may be not "./git/" directly) [networkupstools/nut-website#52]

Signed-off-by: Jim Klimov <[email protected]>
@jimklimov jimklimov added enhancement documentation CI Entries related to continuous integration infrastructure (historically also recipes like Makefiles) labels May 10, 2024
@jimklimov jimklimov added this to the 2.8.3 milestone May 10, 2024
@jimklimov jimklimov added the refactor/fightwarn PR or issue proposal to improve code maintainability without functional changes, or to fix warnings label May 10, 2024
…w that the parent Makefile knows when to slack off [networkupstools/nut-website#52]

Signed-off-by: Jim Klimov <[email protected]>
@jimklimov jimklimov force-pushed the regen-changelog-only-if-new-git branch from 86d0118 to d58dcb1 Compare May 10, 2024 08:28
@AppVeyorBot
Copy link

@jimklimov
Copy link
Member Author

AppVeyor problem does not seem related to this change => #2437

@jimklimov jimklimov merged commit c342e63 into master May 11, 2024
30 of 31 checks passed
@jimklimov jimklimov deleted the regen-changelog-only-if-new-git branch May 11, 2024 12:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
CI Entries related to continuous integration infrastructure (historically also recipes like Makefiles) documentation enhancement refactor/fightwarn PR or issue proposal to improve code maintainability without functional changes, or to fix warnings
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants