[doc] Describe relation of dnf.conf with defaults in conf (RhBug:1738… #1486

j-mracek · 2019-09-17T14:28:15Z

…837)

Options skip_if_unavailable and best are shipped with different defaults
for particular distributions. Defaults are adjusted by different content
of dnf.conf. The patch mentions the situation for those two options.

https://bugzilla.redhat.com/show_bug.cgi?id=1738837

j-mracek · 2019-09-17T14:30:01Z

This is part of #1484, that is ready to merge. The rest requires deep discussion.

lukash · 2019-09-18T11:59:08Z

doc/cli_vs_yum.rst

@@ -121,6 +121,7 @@ Also see related Fedora bugzillas `982947
 ``skip_if_unavailable`` enabled by default
 ============================================

+In some distribution DNF is shipped with ``skip_if_unavailable=True`` in ``/etc/dnf/dnf.conf``.


Should read:

In some distributions ...

However, with or without this, I'm quite confused what this paragraph is actually trying to say... Especially with the back and forth that went on about this... Maybe it should be rephrased and start with defining what the real difference to yum actually is?

I wish we'd just get /etc/dnf/conf.d/*.conf files working... Then we can ship distro override snippets.

lukash · 2019-09-18T12:01:53Z

doc/api_conf.rst

+    Boolean option, ``True`` instructs the solver to either use a package with the highest available
+    version or fail. On ``False``, do not fail if the latest version can not be installed. Default
+    is ``True``. The default is overwritten by configuration in ``dnf.conf`` file
+    (``/etc/dnf/dnf.conf``) that could differ for particular distribution.


Instead of:

Default is True. The default is overwritten by configuration in dnf.conf file (/etc/dnf/dnf.conf) that could differ for particular distribution.

I'd use:

Default is True. The default can be overridden in the configuration <instead of the path, a reference to the config file documentation (ideally directly to the option in question) would be better?>.

I'd leave out the mention of the distribution. Maybe in the documentation of the config file option it can be mentioned.

The same goes for the other similar sentence added to this file.

Well I suggest that mentioning distribution and dnf configuration file is good approach for both options.

How about following?

Default is True. Distributions are advised to explicitly set this value in the dnf configuration file they distribute (typically /etc/dnf/dnf.conf) to enforce the desired behavior and make it obvious to the end users.

@dmach TBH that seems to me like putting recommendations for distribution maintainers into user-facing documentation. We should be addressing the end user here... 🙂

lukash · 2019-09-18T12:11:15Z

doc/conf_ref.rst

@@ -75,7 +75,8 @@ or :ref:`mirrorlist <mirrorlist-label>` option definition.
    When upgrading a package, always try to install its highest version
    available, even only to find out some of its deps are not
    satisfiable. Enable this if you want to experience broken dependencies in
-    the repositories firsthand. The default is False.
+    the repositories firsthand. The default is ``True``. The default is overwritten by configuration
+    in ``dnf.conf`` file (``/etc/dnf/dnf.conf``) that could differ for particular distribution.


So this is the documentation of the configuration file, so the sentence:

The default is overwritten by configuration in dnf.conf file (/etc/dnf/dnf.conf)

Is redundant here, right? So I'd leave it with:

The default is True.

I think I'd leave out the mention of the distribution here too. Your wording kind of says the value can be different across various distributions, but the man page should be specific to the distribution of the user. That distribution has a very concrete value in the config, but we can't know it here. But the information is perhaps not that relevant to the user and they may have changed the value themself anyway.

But, if you wanna keep it in, maybe something like:

The default is True. This value may be set in your configuration file according to your distribution policy.

j-mracek · 2019-09-18T14:36:43Z

Requires: rpm-software-management/libdnf#797

j-mracek · 2019-09-20T06:47:10Z

@lukash The patch was updated

doc/cli_vs_yum.rst

lukash · 2019-09-20T12:10:36Z

doc/cli_vs_yum.rst

+:ref:`DNF configuration file <conf_ref-label>` file. The reason for the change are the third-party
+repository that down often. Note that without this setting and without an explicit
+``skip_if_unavailable=True`` in the relevant repo .ini file YUM immediately stops on a repo error,
+confusing and bothering the user.


Please use this sentence:

... The reason for the change is that third-party repositories may often be unavailable. ...

And then for:

... Note that without this setting and without an explicit skip_if_unavailable=True in the relevant repo .ini ...

What is "this setting"? To me it seems "this setting" == skip_if_unavailable=True, so it seems to me this sentence is unnecessarily complex and confusing?

lukash · 2019-09-20T12:19:08Z

doc/conf_ref.rst

@@ -75,7 +75,8 @@ or :ref:`mirrorlist <mirrorlist-label>` option definition.
    When upgrading a package, always try to install its highest version
    available, even only to find out some of its deps are not
    satisfiable. Enable this if you want to experience broken dependencies in
-    the repositories firsthand. The default is False.
+    the repositories firsthand. The default is ``True``. The default can be overridden by
+    :ref:`DNF configuration file <conf_ref-label>` that could differ for particular distribution.


To me the sentence:

The default can be overridden by :ref:DNF configuration file <conf_ref-label>

points to the DNF Configuration Reference section, which this paragraph is part of, therefore it references itself, which is confusing.

If you want to reference the first paragraph of Description talking about the main config file and the .repo configs, IMO you need to separate that paragraph and reference directly to it, as well as phrase this in a bit more concrete way to point out what you mean by the reference. I also think this is really redundant. The user is reading the configuration reference documentation, they should be able to scroll up easily to find out where the files are. The text isn't long either.

If you put this here, you might as well put it in the description of every option listed here, which doesn't really make sense.

rh-atomic-bot · 2019-09-27T09:07:39Z

☔ The latest upstream changes (presumably 37ce203) made this pull request unmergeable. Please resolve the merge conflicts.

…837) Options skip_if_unavailable and best are shipped with different defaults for particular distributions. Defaults are adjusted by different content of dnf.conf. The patch mentions the situation for those two options. https://bugzilla.redhat.com/show_bug.cgi?id=1738837

j-mracek · 2019-10-07T16:53:19Z

@lukash Rebased, additional improvement added.

rh-atomic-bot · 2019-10-17T10:36:14Z

☔ The latest upstream changes (presumably ce51b6e) made this pull request unmergeable. Please resolve the merge conflicts.

j-mracek assigned lukash Sep 17, 2019

lukash reviewed Sep 18, 2019

View reviewed changes

lukash mentioned this pull request Sep 19, 2019

Adjust dnf.conf for particular distributions #1484

Merged

j-mracek force-pushed the dnf-doc branch from 5c061e5 to e87509e Compare September 20, 2019 06:45

j-mracek force-pushed the dnf-doc branch from e87509e to 9e5d31f Compare September 20, 2019 11:43

lukash reviewed Sep 20, 2019

View reviewed changes

j-mracek force-pushed the dnf-doc branch 2 times, most recently from d1003bf to 022670a Compare October 7, 2019 16:48

j-mracek force-pushed the dnf-doc branch from 022670a to b1312a0 Compare October 7, 2019 16:52

lukash mentioned this pull request Oct 16, 2019

[doc] best and skip_if_unavailable can by overriden by distributions #1505

Merged

j-mracek closed this Oct 17, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[doc] Describe relation of dnf.conf with defaults in conf (RhBug:1738… #1486

[doc] Describe relation of dnf.conf with defaults in conf (RhBug:1738… #1486

j-mracek commented Sep 17, 2019

j-mracek commented Sep 17, 2019

lukash Sep 18, 2019

Conan-Kudo Sep 18, 2019

lukash Sep 18, 2019 •

edited

j-mracek Sep 20, 2019

dmach Sep 20, 2019

lukash Sep 20, 2019

lukash Sep 18, 2019

j-mracek commented Sep 18, 2019

j-mracek commented Sep 20, 2019

lukash Sep 20, 2019

lukash Sep 20, 2019

rh-atomic-bot commented Sep 27, 2019

j-mracek commented Oct 7, 2019

rh-atomic-bot commented Oct 17, 2019

[doc] Describe relation of dnf.conf with defaults in conf (RhBug:1738… #1486

[doc] Describe relation of dnf.conf with defaults in conf (RhBug:1738… #1486

Conversation

j-mracek commented Sep 17, 2019

j-mracek commented Sep 17, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lukash Sep 18, 2019 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

j-mracek commented Sep 18, 2019

j-mracek commented Sep 20, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rh-atomic-bot commented Sep 27, 2019

j-mracek commented Oct 7, 2019

rh-atomic-bot commented Oct 17, 2019

lukash Sep 18, 2019 •

edited