Packaging Guidelines Organization

[Toshio Kuratomi]

Howdy folks,

I'm on the Fedora Packaging Committee and we are in desperate need of
some docs help.

We manage the Packaging Guidelines which help packagers and reviewers
create quality packages for Fedora.  Unfortunately, as time has
progressed the Guidelines have grown larger and larger in an "organic"
fashion.  In order to keep the policies managable for people new to
Fedora we need to organize them somehow.  There's several threads in this:

1)
We want something that helps the packager and reviewer find all the
Guidelines that apply to the package that they are working on but not to
the ones they are not.  So we need some sort of navigation based on
questions the packager and reviewer can answer about the packages:

General Review Items

What programming languages is this written in?

Is this a library or an application?

2)
We want to have a checklist of items to look at with more in-depth
information about why a Guideline exists available to those who want to
know more.

3)
Some of our extra information is more HOWTO-oriented.  For instance, the
section on Package Naming talks about how to choose a name for a package
and how to structure the version strings so that they are always upgradable.

If we could get someone to help us work out this restructuring I'm here
to work on these things from the FPC side.  Feel free to contact me via
this list, email, fedora-packaging-list, or on IRC: abadger1999
(#fedora-devel, #fedora-admin).

-Toshio

[Ian Weller]

On Fri, Dec 12, 2008 at 09:50:22AM -0800, Toshio Kuratomi wrote:
>  Howdy folks,
>   
I moved this thread to fedora-wiki(a)lists.fedoraproject.org. It'd be
preferred that all discussion stays there :)

-- 
Ian Weller <ianweller(a)gmail.com&gt;                  http://ianweller.org
GnuPG fingerprint:  E51E 0517 7A92 70A2 4226  B050 87ED 7C97 EFA8 4A36
"Technology is a word that describes something that doesn't work yet."
  ~ Douglas Adams

[Karsten Wade]

On Fri, Dec 12, 2008 at 11:15:20PM -0600, Ian Weller wrote:
>  On Fri, Dec 12, 2008 at 09:50:22AM -0800, Toshio Kuratomi wrote:
>  > Howdy folks,
>  > 
>  I moved this thread to fedora-wiki(a)lists.fedoraproject.org. It'd be
>  preferred that all discussion stays there :) 
Sorry I missed this one in my reply.

I'm not sure this should move to the wiki list.  The Packaging Guide
is probably not destined for a wiki-only existence because:

* The content needs to be immutable for people outside of the
  Packaging Committee (and writing team).  This is one of the reasons
  we want a CMS for publishing.

* We really need to make the Packaging Guide available for
  translation.  For the foreseeable future, the wiki l10n process is
  the one oddity in an otherwise PO-using/Transifex-submitting system.

Anyway, that's my perspective on things.

Regardless, we really, really need a single lead writer for this one.

https://fedoraproject.org/wiki/Docs_Project_content_tasks_for_experienced...

If we don't get a lead writer, we basically have to tell the FPC et
al, "Sorry."

- Karsten
-- 
Karsten 'quaid' Wade, Community Gardener
http://quaid.fedorapeople.org
AD0E0C41

[Eric Christensen]

What needs to happen with the Packaging Guide?  Is there something
already there that needs some attention?

Eric



On Mon, 2008-12-15 at 11:23 -0800, Karsten Wade wrote:
>  On Fri, Dec 12, 2008 at 11:15:20PM -0600, Ian Weller wrote:
>  > On Fri, Dec 12, 2008 at 09:50:22AM -0800, Toshio Kuratomi wrote:
>  > > Howdy folks,
>  > > 
>  > I moved this thread to fedora-wiki(a)lists.fedoraproject.org. It'd be
>  > preferred that all discussion stays there :)
>  
>  Sorry I missed this one in my reply.
>  
>  I'm not sure this should move to the wiki list.  The Packaging Guide
>  is probably not destined for a wiki-only existence because:
>  
>  * The content needs to be immutable for people outside of the
>    Packaging Committee (and writing team).  This is one of the reasons
>    we want a CMS for publishing.
>  
>  * We really need to make the Packaging Guide available for
>    translation.  For the foreseeable future, the wiki l10n process is
>    the one oddity in an otherwise PO-using/Transifex-submitting system.
>  
>  Anyway, that's my perspective on things.
>  
>  Regardless, we really, really need a single lead writer for this one.
>  
>
> https://fedoraproject.org/wiki/Docs_Project_content_tasks_for_experienced...
>  
>  If we don't get a lead writer, we basically have to tell the FPC et
>  al, "Sorry."
>  
>  - Karsten
>  -- 
>  fedora-docs-list mailing list
>  fedora-docs-list(a)redhat.com
>  To unsubscribe: 
>  https://www.redhat.com/mailman/listinfo/fedora-docs-list

[Karsten Wade]

On Mon, Dec 15, 2008 at 03:23:43PM -0500, Eric Christensen wrote:
>  What needs to happen with the Packaging Guide?  Is there something
>  already there that needs some attention? 
Take a look at Toshio's original email:

http://www.redhat.com/archives/fedora-docs-list/2008-December/msg00096.html

https://fedoraproject.org/wiki/Special:Prefixindex/Packaging

- Karsten
-- 
Karsten 'quaid' Wade, Community Gardener
http://quaid.fedorapeople.org
AD0E0C41

[Eric Christensen]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Karsten,
So some sort of decision tree, maybe?  Seems like an interesting task.
I'm not sure how to approach it, though.

Eric


Karsten Wade wrote:
>  On Mon, Dec 15, 2008 at 03:23:43PM -0500, Eric Christensen wrote:
> > What needs to happen with the Packaging Guide?  Is there something
> > already there that needs some attention?
>  
>  Take a look at Toshio's original email:
>  
>  http://www.redhat.com/archives/fedora-docs-list/2008-December/msg00096.html
>  
>  https://fedoraproject.org/wiki/Special:Prefixindex/Packaging
>  
>  - Karsten
> >   
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.9 (GNU/Linux)
> Comment: Using GnuPG with Fedora - http://enigmail.mozdev.org
>
> iEYEARECAAYFAklHIpgACgkQL5V8yddJCO0AFQCffiny5j89B2PRuauMuJTPYGXB
> 1ZkAnjglc+ch/wYpTKFBnBNtklATcc6H
> =BYI1
> -----END PGP SIGNATURE-----

[Toshio Kuratomi]

Eric Christensen wrote:
>  Karsten,
>  So some sort of decision tree, maybe?  Seems like an interesting task.
>  I'm not sure how to approach it, though.
>   
<nod>

A decision tree would be a major part of it.  Also, making sure that the
documentation is all findable.  Where is the link to the Fonts Packaging
Guidelines, for instance.

-Toshio

[Eric Christensen]

Toshio,
So you basically need someone (or a group) to locate all the guidelines,
make sure they represent what needs to be accomplished for a package,
and then make a single page where all of the guidelines can be found
with ease?

-Eric


On Tue, 2008-12-16 at 10:31 -0800, Toshio Kuratomi wrote:
>  Eric Christensen wrote:
>  > Karsten,
>  > So some sort of decision tree, maybe?  Seems like an interesting task.
>  > I'm not sure how to approach it, though.
>  > 
>  <nod>
>  
>  A decision tree would be a major part of it.  Also, making sure that the
>  documentation is all findable.  Where is the link to the Fonts Packaging
>  Guidelines, for instance.
>  
>  -Toshio
>  
>  -- 
>  fedora-docs-list mailing list
>  fedora-docs-list(a)redhat.com
>  To unsubscribe: 
>  https://www.redhat.com/mailman/listinfo/fedora-docs-list

[Paul W. Frields]

On Tue, Dec 16, 2008 at 02:19:23PM -0500, Eric Christensen wrote:
>  Toshio,
>  So you basically need someone (or a group) to locate all the guidelines,
>  make sure they represent what needs to be accomplished for a package,
>  and then make a single page where all of the guidelines can be found
>  with ease? 
When John Poelstra and I broke up the Feature policy into separate
pages, it became much more readable.  You can establish a "flow," much
like a procedure.  I also don't mean that you want one step per page
necessarily -- but you can balance the information so that it's
grouped logically, but also digestible.

https://fedoraproject.org/wiki/Features/Policy

-- 
Paul W. Frields                                http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
  http://redhat.com/   -  -  -  -   http://pfrields.fedorapeople.org/
  irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug

[Toshio Kuratomi]

Eric Christensen wrote:
>  Toshio,
>  So you basically need someone (or a group) to locate all the guidelines,
>  make sure they represent what needs to be accomplished for a package,
>  and then make a single page where all of the guidelines can be found
>  with ease?
>   
Maybe.  The end goal is that a reviewer or packager can easily find all
the Guidelines that they need to make a quality package.  The
organization comes in two parts:

1) It's not obvious where all the Guidelines are and they might not be
linked from obvious places.  I think the single page idea above could
help with that.

2) There's so many Guidelines and they won't all apply to every package.
 That's where the decision tree type of solution comes in.  (Or a table
of contents with "General Guidelines -- Check these for all packages"
"Libraries -- Check these if your package has a library in any language"
"Python -- Check these if the package is written in or interface with
Python")

Right now we have the Package Review Guidelines[1]_ sort of does #1 but
it isn't complete.  The Review Guidelines and Guidelines[2]_ pages kinda
reflect each other so they capture the main Guidelines.  But we still
need to add other information such as the language specific Guidelines
(examples: Python_ and Java_) and Scriptlets_ pages.

Working on only one of the two issues would be helpful but eventually we
need something that addresses both problems.

.. _[1]: http://fedoraproject.org/wiki/Packaging/ReviewGuidelines
.. _[2]: http://fedoraproject.org/wiki/Packaging/Guidelines

.. _Python: http://fedoraproject.org/wiki/Packaging/Python
.. _Java: http://fedoraproject.org/wiki/Packaging/Java
.. _Scriptlets: https://fedoraproject.org/wiki/Packaging/ScriptletSnippets

-Toshio

[Karsten Wade]

On Tue, Dec 16, 2008 at 12:08:08PM -0800, Toshio Kuratomi wrote:
>  Eric Christensen wrote:
>  > Toshio,
>  > So you basically need someone (or a group) to locate all the guidelines,
>  > make sure they represent what needs to be accomplished for a package,
>  > and then make a single page where all of the guidelines can be found
>  > with ease?
>  > 
>  Maybe.  The end goal is that a reviewer or packager can easily find all
>  the Guidelines that they need to make a quality package.  The
>  organization comes in two parts:
>  
>  1) It's not obvious where all the Guidelines are and they might not be
>  linked from obvious places.  I think the single page idea above could
>  help with that.
>  
>  2) There's so many Guidelines and they won't all apply to every package.
>   That's where the decision tree type of solution comes in.  (Or a table
>  of contents with "General Guidelines -- Check these for all packages"
>  "Libraries -- Check these if your package has a library in any language"
>  "Python -- Check these if the package is written in or interface with
>  Python") 
Table/matrix might be better.  A decision tree, especially implemented
in any hard markup (such as wiki or XML) becomes a maintenance hassle
each time a leaf node is tweaked.  Since we can anticipate the major
paths people want to take, we can probably group them together
relatively well.

If done on the wiki, this begs for a nice categorization, I think.
E.g. [[Category:Python packaging guidelines]] would be in each page
that had anything to do with Python packaging.  It could even be a
general page, so that general page appeared in *all* categories.  It
was for this kind of stuff that I think Ian looked to fedora-wiki as
the list for discussion.

However, Toshio, you skipped a third imperative:

3) Translate the guidelines.

It is the natural evolution of a document that when it is useful
enough to revitalize and care for over the long term, it is very
likely it needs to be available for translation.

We could leave this to the wiki l10n methods coming rather soon, but I
personally am quite skeptical about that.  Until it is proven and
used, it is not the normal pathway for getting content localized.

>  Right now we have the Package Review Guidelines[1]_ sort of does #1
> but
>  it isn't complete.  The Review Guidelines and Guidelines[2]_ pages kinda
>  reflect each other so they capture the main Guidelines.  But we still
>  need to add other information such as the language specific Guidelines
>  (examples: Python_ and Java_) and Scriptlets_ pages.
>  
>  Working on only one of the two issues would be helpful but eventually we
>  need something that addresses both problems. 
Another imperative is enabling the FPC to work on the guidelines
easily.  We also want to organize the content collaboratively before
committing new structure to any other markup such as XML.  It seems
like a good idea to start reorganizing content in to categories.  We
can do this in a sandbox name space perhaps?

- Karsten
-- 
Karsten 'quaid' Wade, Community Gardener
http://quaid.fedorapeople.org
AD0E0C41