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: opensuse-packaging+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-packaging+owner@opensuse.org

Jan Engelhardt 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: opensuse-packaging+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-packaging+owner@opensuse.org

Simon Lees wrote:

On 05/09/17 18:43, Adam Spiers wrote:

...

Jan Engelhardt 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: opensuse-packaging+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-packaging+owner@opensuse.org

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: opensuse-packaging+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-packaging+owner@opensuse.org