How strong a language does the wiki need

classic Classic list List threaded Threaded
11 messages Options
Reply | Threaded
Open this post in threaded view
|

How strong a language does the wiki need

Jan Engelhardt-4

Think back to when Greg KH had to switch his Linux kernel release announcements
from "users should upgrade" to "all users must upgrade".

It would appear that the number of people that read and take texts the literal
RFC way is on the rise, and that the same s/SHOULD/MUST/g; operation might be
necessary for the openSUSE wiki concerning package submissions. The texts would
then be less ambiguous when it comes to disputed positions, though also change
to a stricter atmosphere, which might be an impediment for new-time users.

Like public places getting their "please clean up after your pet" signs
replaced by "$100 fine, you idiot". That hardly sounds like a solution.


Seeking comments for $wiki..
--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: How strong a language does the wiki need

Thorsten Kukuk
On Mon, Sep 04, Jan Engelhardt wrote:

> It would appear that the number of people that read and take texts the literal
> RFC way is on the rise, and that the same s/SHOULD/MUST/g; operation might be
> necessary for the openSUSE wiki concerning package submissions. The texts would
> then be less ambiguous when it comes to disputed positions, though also change
> to a stricter atmosphere, which might be an impediment for new-time users.
>
> Like public places getting their "please clean up after your pet" signs
> replaced by "$100 fine, you idiot". That hardly sounds like a solution.

You are mixing up two different things:

Nobody cares if you use a green, brown or black bag to clean up after
your pet. Important is, that you clean up after your pet.

Same with the openSUSE wiki concerning package submissions:
There is a lot of "best practice", where it does not matter how exactly
this is done, only that it is done. Like it makes no difference if you
use a brown or a black bag.
And then there are things, where it really makes a difference how you
do it. Like putting the bag in a trash can or throwing it behind the
next bush.

If we speak about pure cosmetical things, which have absolut no influence
on the build process, the package, or what the user will see, I don't like
to be forced to a style some few people prefer for personal reasons.
And I'm absolute sure I'm not the only one.
Here we should stay with the "best practice" style and write how it is
done preferrable, but not make the life of other harder than needed by
enforcing it for no good reason.
It's different if you look at things, which make a real difference in
the result. This should be enforced and clearly documented, why we
need to enforce it.
Like with *-devel-static: else we cannot find out, which packages need
a security update.

  Thorsten

--
Thorsten Kukuk, Distinguished Engineer, Senior Architect SLES & CaaSP
SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nuernberg, Germany
GF: Felix Imendoerffer, Jane Smithard, Graham Norton, HRB 21284 (AG Nuernberg)
--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: How strong a language does the wiki need

Jan Engelhardt-4

On Monday 2017-09-04 18:33, Thorsten Kukuk wrote:
>On Mon, Sep 04, Jan Engelhardt wrote:
>
>Same with the openSUSE wiki concerning package submissions:
>There is a lot of "best practice", where it does not matter how exactly
>this is done, only that it is done. Like it makes no difference if you
>use a brown or a black bag.

Best practices can also be specified for the how, not just the what.
In fact, the wiki is chock-full of "how"-type documents, because the
"what" is often quite self-evident as people go about scratching
their initial itches. The entire shared library guideline is a giant
pile of cosmetical "how", since you could just as well ignore it and
collect all files in a single package. It certainly worked in SUSE
6.0.

Best practices exist to be achieved. Otherwise, having these BP would
be quite pointless. If anyone does not like spending time trying to
achieve them, that is fine, and there is no need to feel bad about it
either. openSUSE is (supposed to be) a collaborative effort. Others
are very much willing to step in to further the project.

What puzzles me is that you are actively working against that.



If you feel the $best has problems, you can propose a new value for
$best. The collective will evalute and maybe come to the impression
it is time to switch. I mean, the board does it all the time with
version numbers... ;-)
--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: How strong a language does the wiki need

Thorsten Kukuk
On Mon, Sep 04, Jan Engelhardt wrote:

> If you feel the $best has problems, you can propose a new value for
> $best. The collective will evalute and maybe come to the impression
> it is time to switch. I mean, the board does it all the time with
> version numbers... ;-)

The problem is, that you misuse your power to enforce best practice
against the will of the developers and not backed up by the policies.

If this would solve any problem or fix anything this would be ok, but
we are speaking here about pure cosmetic without any effect, creating
a lot of unecessary work for a lot of people.

  Thorsten

--
Thorsten Kukuk, Distinguished Engineer, Senior Architect SLES & CaaSP
SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nuernberg, Germany
GF: Felix Imendoerffer, Jane Smithard, Graham Norton, HRB 21284 (AG Nuernberg)
--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: How strong a language does the wiki need

Thorsten Kukuk
In reply to this post by Jan Engelhardt-4
On Mon, Sep 04, Jan Engelhardt wrote:

>
> On Monday 2017-09-04 18:33, Thorsten Kukuk wrote:
> >On Mon, Sep 04, Jan Engelhardt wrote:
> >
> >Same with the openSUSE wiki concerning package submissions:
> >There is a lot of "best practice", where it does not matter how exactly
> >this is done, only that it is done. Like it makes no difference if you
> >use a brown or a black bag.
>
> Best practices can also be specified for the how, not just the what.
[...]
> Best practices exist to be achieved. Otherwise, having these BP would
> be quite pointless.

I admit that calling it "best practice" by me was a bad choice.

"A best practice is a method or technique that has been generally
 accepted as superior to any alternatives because it produces results
 that are superior to those achieved by other means ..."
(wikipedia)

Coming back to your pet example: standarizing the color of the bag
to black is clearly no best practice, since it does not produce superior
results compared to the brown bag.
Same for the questionable parts of the openSUSE packaging guidelines.

In the end you can even say that some of the parts are the opposite of
best practice, since it limits the result to openSUSE only.

  Thorsten

--
Thorsten Kukuk, Distinguished Engineer, Senior Architect SLES & CaaSP
SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nuernberg, Germany
GF: Felix Imendoerffer, Jane Smithard, Graham Norton, HRB 21284 (AG Nuernberg)
--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: How strong a language does the wiki need

Adam Spiers
In reply to this post by Jan Engelhardt-4
Jan Engelhardt <[hidden email]> wrote:
>On Monday 2017-09-04 18:33, Thorsten Kukuk wrote:
>>On Mon, Sep 04, Jan Engelhardt wrote:
>>
>>Same with the openSUSE wiki concerning package submissions:
>>There is a lot of "best practice", where it does not matter how exactly
>>this is done, only that it is done. Like it makes no difference if you
>>use a brown or a black bag.
>
>Best practices can also be specified for the how, not just the what.

I would suggest focussing on the "why" more than the "what" or "how".
That way any disagreements over best practice are more likely to
result in productive conversations where the goal is alignment on
exactly what people are trying to accomplish.  Once alignment on the
goals is reached, it should be a lot easier to agree on the details.

OTOH if the "why" is omitted then people can waste days on
bike-shedding / religious wars without realising that they are coming
at the problem from different perspectives (which might be equally
valid in different ways).  In fact this thread is already showing
tendencies of going that way.
--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: How strong a language does the wiki need

Jan Engelhardt-4
In reply to this post by Thorsten Kukuk
On Monday 2017-09-04 22:08, Thorsten Kukuk wrote:
>
>The problem is, that you misuse your power to enforce best practice
>against the will of the developers and not backed up by the policies.

Dear readers,


The wiki has on the order of 29 pages of policy-like documents. Their
page titles have "policy" or synonyms like "guideline" or "rules" in
them, and some are out of pattern ("restricted formats"). They should
be considered all the same importance nonwithstanding the title
chosen by the page creator some 7 years or so ago.

Now, I could be in the minority with my opinion. To find out if that
is the case, posting to exactly this list was needed. If there is an
overwhelming stance that guidelines should just be guiding lines
(though I have a feeling SUSE won't be happy if people do that with
the "trademark guidelines"), then it should be so recorded so that
everyone can enjoy ignore the guiding lines at leisure.


>If this would solve any problem or fix anything this would be ok, but
>we are speaking here about pure cosmetic without any effect, creating
>a lot of unecessary work for a lot of people.

Only for yourself, really. You could have simply taken the request
and be done with it in a button click. You chose not to.
Intentionally. Instead, you went to argue that,

"If you personal dislike with how spec-cleaner is doing something,
than you should convience the maintainer of spec-cleaner to change
it." –https://build.opensuse.org/request/show/520340

The changes that I made are among what spec-cleaner would have done.
You preach spec-cleaner, but you do not practice it. In my humble
opinion, this double standard is inappropriate for package
maintainers in openSUSE. It is discouraging to (in particular) new
developers.


(And so, if the submission 519825 is knowingly different from what
the developer intended, in other words, that something is missing on
purpose, the submit is best returned to the develprj for further
refinement.)
--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: How strong a language does the wiki need

Johannes Meixner
In reply to this post by Thorsten Kukuk

Hello,

On Sep 4 Thorsten Kukuk wrote (excerpt):
>
> If this would solve any problem or fix anything this would be ok,
> but we are speaking here about pure cosmetic without any effect,
> creating a lot of unecessary work for a lot of people.
>
and he also wrote (excerpt):
>
> "A best practice is a method or technique that has been generally
> accepted as superior to any alternatives because it produces results
> that are superior to those achieved by other means ..."
> (wikipedia)
> ...
> In the end you can even say that some of the parts are the opposite
> of best practice, since it limits the result to openSUSE only.

Cf.
https://lists.opensuse.org/opensuse-packaging/2017-07/msg00079.html
where I had written (excerpt):
--------------------------------------------------------------------
[obs-service-format_spec_file is moving comments around]

In general it seems to be good when openSUSE RPM spec files
are in compliance with a reasonable openSUSE standard.

But on the other hand enforcing it could be a hindrance
for openSUSE contributors to use ready-made RPM spec files
from whatever upstream projects also for openSUSE RPMs
with only some minor openSUSE-specific adaptions
to get software easily built also for openSUSE.

What is more important for openSUSE:
Be open for others (and accept diversity)
or
be uniform (to make maintenance easier)?
--------------------------------------------------------------------
and cf.
https://lists.opensuse.org/opensuse-packaging/2017-07/msg00095.html
where I had written (excerpt):
--------------------------------------------------------------------
[Poll about Url vs URL in RPM preamble]

What is the benefit for openSUSE users and contributors
to enforce a special openSUSE uniformity for spelling
things like "Url vs URL" regardless that both are valid?

I need to repeat myself:

What is more important for openSUSE:
Be open and accept diversity or enforce uniformity?
--------------------------------------------------------------------

To make it clear:
I also mean cosmetic things without real positive effect
to make the openSUSE result actually superior to others.


Kind Regards
Johannes Meixner
--
SUSE LINUX GmbH - GF: Felix Imendoerffer, Jane Smithard,
Graham Norton - HRB 21284 (AG Nuernberg)

--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: How strong a language does the wiki need

Adam Spiers
In reply to this post by Jan Engelhardt-4
Jan Engelhardt <[hidden email]> wrote:
>The wiki has on the order of 29 pages of policy-like documents. Their
>page titles have "policy" or synonyms like "guideline" or "rules" in
>them, and some are out of pattern ("restricted formats"). They should
>be considered all the same importance nonwithstanding the title
>chosen by the page creator some 7 years or so ago.

That seems highly unlikely.

>Now, I could be in the minority with my opinion. To find out if that
>is the case, posting to exactly this list was needed. If there is an
>overwhelming stance that guidelines should just be guiding lines
>(though I have a feeling SUSE won't be happy if people do that with
>the "trademark guidelines"), then it should be so recorded so that
>everyone can enjoy ignore the guiding lines at leisure.

I think your original suggestion of adopting RFC2119 language is a
very good one.  More precision around language can only help.  Having
said that, this is very different the other suggestion you made in the
same sentence: doing a global s/SHOULD/MUST/g, which would actually
achieve the opposite and reduce precision by collapsing all
recommendations to the same weight, i.e. mandatory.  Let's not confuse
the two - it is entirely possible to use more precise language without
imposing extra restrictions and creating more work for people.  In
fact the opposite is true: using more precise language can even reduce
the amount of work, by making it clear that some items are only
"should" or "may" rather than "must".

So the relative weight of each item in policies / guidelines / best
practices needs to be carefully considered, and the wording chosen
accordingly.  Unfortunately that creates a bit more work, but I expect
a subject matter expert could correct several pages per hour based on
their own opinion.  The real problem is reaching consensus on whether
any given item should be a "must" or a "should" or a "may", and
unfortunately the fact that we are hosting these documents on a wiki
page does nothing to help that.  To this end I think that it would
make far more sense if a "Policy As Code" approach (or "ProcessOps" as
I have started calling it) was adopted, i.e. policy documents (and
maybe guidelines / best practices / tutorials too) were stored in git
and subject to peer review with formalised rules for voting and
merging.  That way should produce higher quality documents, and ensure
that the history and rationale behind any specific detail could be
viewed via "git blame".

>On Monday 2017-09-04 22:08, Thorsten Kukuk wrote:
>>If this would solve any problem or fix anything this would be ok, but
>>we are speaking here about pure cosmetic without any effect

To nitpick: at the point when you wrote this, this was not clear,
since nothing in this thread referenced specific examples, and
$SUBJECT is clearly a question about the whole wiki in general.  So
this sounded like an overgeneralization to me and probably everyone
else except Jan.  However with the benefit of hindsight from
subsequent posts, I guess you were implicitly referring to some
specific examples relating to specfiles (also subsequently mentioned
in the sister thread "Updated rationales for specfile guidelines"[0]).

This highlights the importance of maintaining a distinction between a
general approach to policy-like documents, vs. discussions about
specific items.  So please can we:

a) agree that *in general* using more precise RFC2119 would help,

b) consider the idea of moving at least official policy documents to
   git, to allow pre-merge peer review, and

c) keep discussion on policy/guidelines for specific aspects of spec
   files in their own thread, focusing on the "why" rather than the
   "what" or "how"?

Thanks!

[0] https://lists.opensuse.org/opensuse-packaging/2017-09/msg00002.html
--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: How strong a language does the wiki need

Simon Lees-3


On 05/09/17 18:43, Adam Spiers wrote:
> Jan Engelhardt <[hidden email]> wrote:
>> The wiki has on the order of 29 pages of policy-like documents. Their
>> page titles have "policy" or synonyms like "guideline" or "rules" in
>> them, and some are out of pattern ("restricted formats"). They should
>> be considered all the same importance nonwithstanding the title
>> chosen by the page creator some 7 years or so ago.
>
> That seems highly unlikely.
>

No i'd believe it there is separate pages with guidelines for many
languages as well as some other components its a significant chunck of
our wiki.

--

Simon Lees (Simotek)                            http://simotek.net

Emergency Update Team                           keybase.io/simotek
SUSE Linux                           Adelaide Australia, UTC+10:30
GPG Fingerprint: 5B87 DB9D 88DC F606 E489 CEC5 0922 C246 02F0 014B


signature.asc (499 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: How strong a language does the wiki need

Adam Spiers
Simon Lees <[hidden email]> wrote:

>On 05/09/17 18:43, Adam Spiers wrote:
>> Jan Engelhardt <[hidden email]> wrote:
>>> The wiki has on the order of 29 pages of policy-like documents. Their
>>> page titles have "policy" or synonyms like "guideline" or "rules" in
>>> them, and some are out of pattern ("restricted formats"). They should
>>> be considered all the same importance nonwithstanding the title
>>> chosen by the page creator some 7 years or so ago.
>>
>> That seems highly unlikely.
>
>No i'd believe it there is separate pages with guidelines for many
>languages as well as some other components its a significant chunck of
>our wiki.

I wasn't doubting the amount of material; I was doubting that it
should all be considered exactly the same importance.
--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]