lists.openwall.net   lists  /  announce  owl-users  owl-dev  john-users  john-dev  passwdqc-users  yescrypt  popa3d-users  /  oss-security  kernel-hardening  musl  sabotage  tlsify  passwords  /  crypt-dev  xvendor  /  Bugtraq  Full-Disclosure  linux-kernel  linux-netdev  linux-ext4  linux-hardening  linux-cve-announce  PHC 
Open Source and information security mailing list archives
 
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Date: Thu, 25 Jan 2024 11:39:42 +0100
From: Anna-Maria Behnsen <anna-maria@...utronix.de>
To: Randy Dunlap <rdunlap@...radead.org>, linux-kernel@...r.kernel.org
Cc: Thomas Gleixner <tglx@...utronix.de>, Frederic Weisbecker
 <frederic@...nel.org>, Ingo Molnar <mingo@...nel.org>, John Stultz
 <jstultz@...gle.com>, Stephen Boyd <sboyd@...nel.org>, Jonathan Corbet
 <corbet@....net>, Clemens Ladisch <clemens@...isch.de>,
 linux-doc@...r.kernel.org
Subject: Re: [PATCH 6/8] Documentation: Create a new folder for all timer
 internals

Randy Dunlap <rdunlap@...radead.org> writes:

> Hi,
>
> On 1/23/24 08:47, Anna-Maria Behnsen wrote:
>> The structure of documentation changed. There is 'core-api' where also
>> timer related documentation belongs to. But the timer related documentation
>> (doesn't matter whether it is up to date or outdated) is still located in a
>> separate folder with no relation to core-api.
>> 
>> Create a new folder which is located below core-api and make it the new
>> place for all timer related documentation. Instead of revisiting all files
>> below the already existing timer folder right now, add a warning banner to
>> the top of all those files. When it is ensured the content is up to date,
>> they can be moved to the final destination.
>> 
>> Signed-off-by: Anna-Maria Behnsen <anna-maria@...utronix.de>
>> ---
>>  Documentation/core-api/index.rst        |  1 +
>>  Documentation/core-api/timers/index.rst | 22 ++++++++++++++++++++++
>>  Documentation/timers/highres.rst        |  5 +++++
>>  Documentation/timers/hpet.rst           |  5 +++++
>>  Documentation/timers/hrtimers.rst       |  5 +++++
>>  Documentation/timers/index.rst          |  5 +++++
>>  Documentation/timers/no_hz.rst          |  4 ++++
>>  Documentation/timers/timekeeping.rst    |  5 +++++
>>  Documentation/timers/timers-howto.rst   |  5 +++++
>
> When can we remove the old, "might be outdated" files?
> Do you think that some of their contents might be valuable to someone?
>
> I prefer not to have the old documentation and the new.
>

This is also nothing I prefere for a final solution. But I got stucked
when I was looking for a way to add the actual documentation because I
wanted to add it into a cleaned-up environment. But I don't have the
possibility at the moment to cleanup the existing timer documentation
right away with all its aspects (content, formatting, referencing,
location below Documentation,... ).

So I had those options:

1. wait until I have time for all this before publishing the new
   documentation -> not an option because I don't know when there is
   time to do all those things in one go

2. Put the new documentation below the existing one and ignore the rest
   silently (maybe someone else will clean it up someday) -> not an
   option because it suggests that the new documentation structure is
   just ignored

3. Just move the old documentation without revisiting it -> not an
   option because there might be outdated information and then it
   doesn't has a benefit for the reader

4. Add a warning banner at the existing documentation and prepare
   everything to get the timer documentation to the proper place and
   create a place for timer documentation below the current structure.

The benefit of 4. for me is, that there is this warning banner at the
top. So this suggests the reader, that this has to be revisited before
relying on it for 100%. This banner might also remind the original
author/technically deep involved developer that this should be
updated.

If there is a better way to go, please let me know!

Thanks,

        Anna-Maria


Powered by blists - more mailing lists

Powered by Openwall GNU/*/Linux Powered by OpenVZ