BIND 9 ARM, html/pdf not in the source?

[Chuck Aurora]

I was about to reply to some other post on this list, when I
needed to look something up to be sure about it, and I looked in
my local OS (Slackware) documentation directory for the BIND 9
ARM. It's there in what appears to be a format for the Sphinx
documentation builder, but no longer shipped in HTML nor PDF.
See doc/arm/ in the source code.

The README still says this:

"Documentation

The BIND 9 Administrator Reference Manual is included with the source
distribution, in DocBook XML, HTML, and PDF format, in the doc/arm
directory."

This no longer appears to be the case, going back several minor
versions. I don't know exactly how far, but at least through the
9.16.11 release, which is what I had installed at the start of my
quest today. (I have 9.16.15 now.)

I guess the Sphinx processing should be done prior to generating
the tarball, is that correct?

Said README also says for reporting bugs to use Gitlab, but without
a Gitlab account I did not readily see how to do this. Are Gitlab
accounts for bug reports now? Can you accept one from someone who
does not have a Gitlab account? Does ***@isc.org no longer work
for bug reporting?
_______________________________________________
Please visit https://lists.isc.org/mailman/listinfo/bind-users to unsubscribe from this list

ISC funds the development of this software with paid support subscriptions. Contact us at https://www.isc.org/contact/ for more information.


bind-users mailing list
bind-***@lists.isc.org
https://lists.isc.org/mailman/listinfo/bind-users

[Ondřej Surý]

Chuck,

yes, the generated documentation is no longer part of sources, but you can read the rst files used to generate documentation - those are just plain text files with little extra markup.

Also yes, you need ISC GitLab account to create new issues (unless it’s a security vulnerability then OpenPGP encrypted email is accepted). We need to interact with the reporters from the issue and we think this is a reasonable requirement.

The README.md has to be reviewed and fixed, but I guess you don’t need to fill the issue for this.

Ondřej
--
Ondřej Surý — ISC (He/Him)

My working hours and your working hours may be different. Please do not feel obligated to reply outside your normal working hours.

Post by Chuck Aurora
I was about to reply to some other post on this list, when I
needed to look something up to be sure about it, and I looked in
my local OS (Slackware) documentation directory for the BIND 9
ARM. It's there in what appears to be a format for the Sphinx
documentation builder, but no longer shipped in HTML nor PDF.
See doc/arm/ in the source code.
"Documentation
The BIND 9 Administrator Reference Manual is included with the source
distribution, in DocBook XML, HTML, and PDF format, in the doc/arm
directory."
This no longer appears to be the case, going back several minor
versions. I don't know exactly how far, but at least through the
9.16.11 release, which is what I had installed at the start of my
quest today. (I have 9.16.15 now.)
I guess the Sphinx processing should be done prior to generating
the tarball, is that correct?
Said README also says for reporting bugs to use Gitlab, but without
a Gitlab account I did not readily see how to do this. Are Gitlab
accounts for bug reports now? Can you accept one from someone who
for bug reporting?
_______________________________________________
Please visit https://lists.isc.org/mailman/listinfo/bind-users to unsubscribe from this list
ISC funds the development of this software with paid support subscriptions. Contact us at https://www.isc.org/contact/ for more information.
bind-users mailing list
https://lists.isc.org/mailman/listinfo/bind-users

_______________________________________________
Please visit https://lists.isc.org/mailman/listinfo/bind-users to unsubscribe from this list

ISC funds the development of this software with paid support subscriptions. Contact us at https://www.isc.org/contact/ for more information.


bind-users mailing list
bind-***@lists.isc.org

[Chuck Aurora]

Post by Ondřej Surý
yes, the generated documentation is no longer part of sources, but you
can read the rst files used to generate documentation - those are just
plain text files with little extra markup.

Yes, I saw that. But the HTML markup is super nice to go to
hyperlinked settings and related documentation sections. Will
the HTML documentation no longer be available at all, other
than to access it online?

(I'm currently in a bandwidth-limited ISP, so I try to limit
such things. Fiber is ordered and coming soon! Yay! Those
of you who know me and where I live will understand how cool
and amazing this is. :) )

(But even with fiber and unlimited high speed connections, I
like having documentation on my trusty old laptop.)

Post by Ondřej Surý
Also yes, you need ISC GitLab account to create new issues (unless
it’s a security vulnerability then OpenPGP encrypted email is
accepted). We need to interact with the reporters from the issue and
we think this is a reasonable requirement.

FWIW I do not agree. I don't get why a free software project
would shut out input from non-users of a third-party service.
Email works since forever. But then, you're not shutting out
input, as we did settle this through the mailing list. :)

Post by Ondřej Surý
The README.md has to be reviewed and fixed, but I guess you don’t need
to fill the issue for this.

Thank you for the reply, Ondřej, much appreciated.

Post by Ondřej Surý

Post by Chuck Aurora
Said README also says for reporting bugs to use Gitlab, but without
a Gitlab account I did not readily see how to do this. Are Gitlab
accounts for bug reports now? Can you accept one from someone who

^ required

Post by Ondřej Surý

Post by Chuck Aurora
for bug reporting?

_______________________________________________
Please visit https://lists.isc.org/mailman/listinfo/bind-users to unsubscribe from this list

ISC funds the development of this software with paid support subscriptions. Contact us at https://www.isc.org/contact/ for more information.


bind-users mailing list
bind-***@lists.isc.org
https://lists.isc.org/mailman/listinf

[Ondřej Surý]

Post by Chuck Aurora
Yes, I saw that. But the HTML markup is super nice to go to
hyperlinked settings and related documentation sections. Will
the HTML documentation no longer be available at all, other
than to access it online?

1. install sphinx-build (pip(3) install sphinx sphinx-rtd-theme)
2. make html
3. (xdg-)open doc/arm/_build/html/index.html

or just download it from:

https://bind9.readthedocs.io/_/downloads/en/v9_16_15/pdf/
https://bind9.readthedocs.io/_/downloads/en/v9_16_15/htmlzip/
https://bind9.readthedocs.io/_/downloads/en/v9_16_15/epub/

Post by Chuck Aurora
I don't get why a free software project
would shut out input from non-users of a third-party service.

Umm, what? The ISC GitLab is run by ISC. All the data is handled
by ISC.

But even if it wasn’t - it’s about choices where to invest the time.
Do you want us rather improving the code because we can focus
or rather the development team should invest the time to scan
multiple sources for incoming issues? I think that the rational choice
here is obvious.

I can chit-chat here as much as I like because it’s Sunday and I was
waiting for the vaccination registration to be open for my age group,
but as long as I am fully in the work mode, I need a single source of
truth for all the issues, all the merge requests, so I don’t spend much
time on searching “where the heck the information was” because it’s
all in the one place. I don’t think it’s too much to ask a little bit of
inconvenience from the users, so we can actually focus on fixing
bugs and improving the software.

Ondrej
--
Ondřej Surý (He/Him)
***@isc.org

_______________________________________________
Please visit https://lists.isc.org/mailman/listinfo/bind-users to unsubscribe from this list

ISC funds the development of this software with paid support subscriptions. Contact us at https://www.isc.org/contact/ for more information.


bind-users mailing list
bind-***@lists.is

[G.W. Haywood via bind-users]

Hi there,

Post by Chuck Aurora

... yes, you need ISC GitLab account to create new issues (unless
it's a security vulnerability then OpenPGP encrypted email is
accepted). We need to interact with the reporters from the issue and
we think this is a reasonable requirement.

FWIW I do not agree.

... I don't think it's too much to ask a little bit of inconvenience
from the users, so we can actually focus on fixing bugs and
improving the software.

I feel strongly that I should chime in with my experiences of trying
to use Git/Web interfaces to report issues. Not, I hasten to add,
issues with BIND - I don't recall ever trying to use ISC's GitLab and
I'd have no particular issues with creating an account except that I'd
try to make sure that it could never be linked to me by criminals when
it's almost inevitably compromised.

I don't want this to sound like an attempt to pour fuel onto the flames
but insisting on Git/HTTP is not just "a little bit of inconvenience".

After finding it necessary to download tens of megabytes of source to
make a ten character change to the code, and finding that the little
'Commit' button that you have to press to the pull request would not
come out of its greyed-out state no matter what I do, and on enquiry
after some hours of digging being told that I need to use a different
browser (I use Palemoon; one suggestion was Firefox), I've now reached
the point that if it says 'http' and 'git' I will look for the little
'X' in the tab near the top of my browser window. Call me a dinosaur
if you like but after wasting much time on it, I flatly refuse to even
try to use a Git/Web interface any more. If I expected to use it all
day every day things might be different, but for chipping in a minor
report or small improvement the bars to entry seem to be set too high.
If I found a mistake in the ARM I'd cheerfully send an email, but I'd
never even consider navigating through a GitLab maze to do the same
thing and I'd just keep quiet about it.

There is an email interface for GitLab. It requires no account to be
created by the user. You get to keep the single repository of wisdom.

https://docs.gitlab.com/ee/user/project/service_desk.html

Would it be too onerous for the ISC to make this available?
--
73,
Ged.
_______________________________________________
Please visit https://lists.isc.org/mailman/listinfo/bind-users to unsubscribe from this list

ISC funds the development of this software with paid support subscriptions. Contact us at https://www.isc.org/contact/ for more information.


bind-users mailing list
bind-***@lists.isc.org
https://lists.isc.org/mailman/listinfo/bind-users

[Ondřej Surý]

Hi,

I am sorry, but what? I would suggest to actually try the interface
before you write angry emails. There’s nothing of sorts as you
describe. The only hassle is that before forking, you need to ask
ISC to actually allow your user account to create forks.

There’s no requirement to use anything like “Git/Web”, I don’t even
know what you exactly mean by that.

Also for this

Post by G.W. Haywood via bind-users
After finding it necessary to download tens of megabytes of source

$ git clone --depth=1 https://gitlab.isc.org/isc-projects/bind9.git
Cloning into 'bind9'...
remote: Enumerating objects: 4755, done.
remote: Counting objects: 100% (4755/4755), done.
remote: Compressing objects: 100% (3558/3558), done.
remote: Total 4755 (delta 2009), reused 2211 (delta 865), pack-reused 0
Receiving objects: 100% (4755/4755), 6.81 MiB | 4.29 MiB/s, done.
Resolving deltas: 100% (2009/2009), done.

It’s less then 7MB when you use proper `git clone` options (and probably even less
on the wire as the compression is used transparently).

Post by G.W. Haywood via bind-users
I flatly refuse to even try to use a Git/Web interface any more.

So, here’s my blunt question - do you have any experience using ISC GitLab?

Post by G.W. Haywood via bind-users
Would it be too onerous for the ISC to make this available?

Well, unless the goal is to keep us busy with handling all the incoming spam…

Again, I don’t think that the creating user account is such high-entry barrier
that it would require shifting the costs from the reported to the already too-busy
open-source developers.

Ondrej
--
Ondřej Surý (He/Him)

Post by G.W. Haywood via bind-users
Hi there,

... yes, you need ISC GitLab account to create new issues (unless

it's a security vulnerability then OpenPGP encrypted email is
accepted). We need to interact with the reporters from the issue and
we think this is a reasonable requirement.
FWIW I do not agree.

... I don't think it's too much to ask a little bit of inconvenience
from the users, so we can actually focus on fixing bugs and
improving the software.

I feel strongly that I should chime in with my experiences of trying
to use Git/Web interfaces to report issues. Not, I hasten to add,
issues with BIND - I don't recall ever trying to use ISC's GitLab and
I'd have no particular issues with creating an account except that I'd
try to make sure that it could never be linked to me by criminals when
it's almost inevitably compromised.
I don't want this to sound like an attempt to pour fuel onto the flames
but insisting on Git/HTTP is not just "a little bit of inconvenience".
After finding it necessary to download tens of megabytes of source to
make a ten character change to the code, and finding that the little
'Commit' button that you have to press to the pull request would not
come out of its greyed-out state no matter what I do, and on enquiry
after some hours of digging being told that I need to use a different
browser (I use Palemoon; one suggestion was Firefox), I've now reached
the point that if it says 'http' and 'git' I will look for the little
'X' in the tab near the top of my browser window. Call me a dinosaur
if you like but after wasting much time on it, I flatly refuse to even
try to use a Git/Web interface any more. If I expected to use it all
day every day things might be different, but for chipping in a minor
report or small improvement the bars to entry seem to be set too high.
If I found a mistake in the ARM I'd cheerfully send an email, but I'd
never even consider navigating through a GitLab maze to do the same
thing and I'd just keep quiet about it.
There is an email interface for GitLab. It requires no account to be
created by the user. You get to keep the single repository of wisdom.
https://docs.gitlab.com/ee/user/project/service_desk.html
Would it be too onerous for the ISC to make this available?
--
73,
Ged.
_______________________________________________
Please visit https://lists.isc.org/mailman/listinfo/bind-users to unsubscribe from this list
ISC funds the development of this software with paid support subscriptions. Contact us at https://www.isc.org/contact/ for more information.
bind-users mailing list
https://lists.isc.org/mailman/listinfo/bind-users

_______________________________________________
Please visit https://lists.isc.org/mailman/listinfo/bind-users to unsubscribe from this list

ISC funds the development of this software with paid support subscriptions. Contact us at https://www.isc.org/contact/ for more information.


bind-users mailing list
bind-***@lists.isc.org
https://lists.is

[Ondřej Surý]

a simple unified diff and sending a patch by email

Here’s what happens when you do that:

1. somebody has to download your patch locally
2. somebody needs to triage the patch (and the issue) and if the description isn’t up-to-par write back to you
3. this might continue for a while ending up with multiple patches in multiple emails
4. somebody has to create a git branch out of the patch
5a. the patch might not apply because the branch could have been modified meanwhile, so back to 2) or
5b. the developer will have to spend a time fixing the patch themselves.
6. then there might be additional questions that goes between you and the reporter
7. oh no, the developer went to PTO for next two weeks and everything is stalled because there’s no record of the communication

So, when you say “simple unified diff” it means a huge pile of additional work with the record of any changes and communications being inaccessible to other team members (or it will have to be posted publicly creating clutter in the mailing list). So, what’s simple for you will burn time for multiple people that could be spent on fixing stuff.

On the contrary:

* A good descriptive bug report in the GitLab issue helps
* Merge requests that follows the coding standard, has a good commit message and good description and is based on the current `main` branch helps…

So, is it really that much to ask?

Ondrej
--
Ondřej Surý (He/Him)
***@isc.org

_______________________________________________
Please visit https://lists.isc.org/mailman/listinfo/bind-users to unsubscribe from this list

ISC funds the development of this software with paid support subscriptions. Contact us at https://www.isc.org/contact/ for more information.


bind-users mailing list
bind-***@lists.isc.org
https://lists.isc.org