Conversation
It would be nice to include the manual pages and HTML documentation into the archives we produce so that it's easy for users to have them without needing to build them. For the tar archives, this is easy: just include "man" in the list of release targets. It's a little more complicated for zip archives, since we need to use the -j flag to strip off directories when we generate our archives, but we don't want to do that here. Instead, just explicitly add the files to the archive with the -u (update) flag after the fact. Note that unlike with tar, we cannot just specify the directory, since that only includes the directory, not its contents: we must specify the files themselves.
Now that we're building the manual pages as part of the release target in the Makefile, let's be sure to always install ronn before doing so so that it doesn't fail.
1d74b15 to
13a860f
Compare
chrisd8088
left a comment
There was a problem hiding this comment.
Thanks for doing this, and for breaking it up into two tidy commits! 👍
|
@bk2204 Just curious, have you considered using I'd be happy to submit a pull-request if you're interested. |
|
Hey, We use Markdown here because we embed the text output into the binary for the Also, while I am personally fine with writing manual pages in troff-based formats, a lot of newer folks are more familiar with Markdown and AsciiDoc and other similar formats, and continuing to use them benefits new contributors. |
Hold up. Troff "or a similar program" (I assume you mean |
Sorry, I was unclear. We embed the literal Markdown from the source (modified slightly to remove HTML) into the We do want some way to indicate things like headings in such a case, but we don't want terminal escape codes, because some people may be using dumb terminals (e.g., emacs's We also have to consider the tooling available on various Linux systems because we build packages there. CentOS 7 does ship Ruby, but it doesn't ship |
In PR git-lfs#3840 we introduced a GitHub Actions workflow to build our release assets when we push a new version tag. As a final step in this workflow we run our script/packagecloud.rb script, which requires the use of the "packagecloud-ruby" Ruby gem. At the time, these requirements meant we needed to first execute the actions/setup-ruby action so we could then install the gem and run our Ruby script. Later, in PR git-lfs#4230, we added steps to our CI workflow to build our manual pages, and since these required the use of the "ronn" Ruby gem, we also added the actions/setup-ruby action to our CI workflow. (We subsequently migrated our manual page source files to the AsciiDoc format, in PR git-lfs#5054, but we continue to use Ruby and the "asciidoctor" gem to build our manual pages.) Then in commit b7fa3a5 of PR git-lfs#5236 we upgraded both of our Actions workflows to use the ruby/setup-ruby action instead of the now-deprecated actions/setup-ruby one. Because the ruby/setup-ruby action installs the MSYS2 environment on Windows and sets several key environment variables like PATH and TMPDIR, we also introduced steps to make sure our CI and release processes continued to work as expected in this context, by clearing the TMPDIR variable and renaming the directory containing the MSYS2 executables. Fortunately, the default runners provided by GitHub Actions for the macOS, Windows, and Ubuntu Linux platforms are now all provisioned with an installation of Ruby 3.x which includes the "gem" utility we need to install the "asciidoctor" and "packagecloud-ruby" gems. As these are all we require to run our Ruby scripts, we no longer need the more extensive Ruby development environment provided by the ruby/setup-ruby action. We can therefore simply remove the ruby/setup-ruby steps from our workflows, along with all the special handling of the MSYS2 environment and the TMPDIR environment variable on Windows.
In PR git-lfs#3840 we introduced a GitHub Actions workflow to build our release assets when we push a new version tag. As a final step in this workflow we run our script/packagecloud.rb script, which requires the use of the "packagecloud-ruby" Ruby gem. At the time, these requirements meant we needed to first execute the actions/setup-ruby action so we could then install the gem and run our Ruby script. Later, in PR git-lfs#4230, we added steps to our CI workflow to build our manual pages, and since these required the use of the "ronn" Ruby gem, we also added the actions/setup-ruby action to our CI workflow. (We subsequently migrated our manual page source files to the AsciiDoc format, in PR git-lfs#5054, but we continue to use Ruby and the "asciidoctor" gem to build our manual pages.) Then in commit b7fa3a5 of PR git-lfs#5236 we upgraded both of our Actions workflows to use the ruby/setup-ruby action instead of the now-deprecated actions/setup-ruby one. Because the ruby/setup-ruby action installs the MSYS2 environment on Windows and sets several key environment variables like PATH and TMPDIR, we also introduced steps to make sure our CI and release processes continued to work as expected in this context, by clearing the TMPDIR variable and renaming the directory containing the MSYS2 executables. Fortunately, the default runners provided by GitHub Actions for the macOS, Windows, and Ubuntu Linux platforms are now all provisioned with an installation of Ruby 3.x which includes the "gem" utility we need to install the "asciidoctor" and "packagecloud-ruby" gems. As these are all we require to run our Ruby scripts, we no longer need the more extensive Ruby development environment provided by the ruby/setup-ruby action. We can therefore simply remove the ruby/setup-ruby steps from our workflows, along with all the special handling of the MSYS2 environment and the TMPDIR environment variable on Windows.
In general, it would be nice to include pre-built manual pages in the release archives, both in the normal troff format and as HTML. They're already baked into the binary as help output, but for some folks,
manis easier to use.This PR includes the manual pages in the archives and sets up the CI system to make sure Ruby and
ronnare installed so we can build the release assets on every platform. During the Windows CI run, we don't explicitly runmake release, so callmake manso we test that they can be built there.Fixes #4228
/cc @lunaryorn as submitter