3:24 p.m.
Folks,
Looking at the new FDLIBS, I'm noticing that there's not a narrative
description of the image required or provided anywhere that I can find.
Clearly one is needed for users. So, here's a proposal:
New Required LABELs:
USAGE: single command line giving usage example
for invoking the container; will be "N/A" for
some containers.
DESCRIPTION: Narrative description incuding:
* What service/software it provides
* What specific purpose it fulfills, if required
* Notes on how to use it, if not covered by USAGE,
such as how to supply configuration files
* Depedencies on other images (e.g. "requires a database")
* Links to documentation for the Software, if any
--
--
Josh Berkus
Project Atomic
Red Hat OSAS
12:33 p.m.
*Bump*
Sans feedback, I'm going to assume that everyone approves of this pretty
soon ...
On 12/13/2016 01:24 PM, Josh Berkus wrote:
Folks,
Looking at the new FDLIBS, I'm noticing that there's not a narrative
description of the image required or provided anywhere that I can find.
Clearly one is needed for users. So, here's a proposal:
New Required LABELs:
USAGE: single command line giving usage example
for invoking the container; will be "N/A" for
some containers.
DESCRIPTION: Narrative description incuding:
* What service/software it provides
* What specific purpose it fulfills, if required
* Notes on how to use it, if not covered by USAGE,
such as how to supply configuration files
* Depedencies on other images (e.g. "requires a database")
* Links to documentation for the Software, if any
--
--
Josh Berkus
Project Atomic
Red Hat OSAS
12:41 p.m.
On Tue, Jan 10, 2017 at 10:33:05AM -0800, Josh Berkus wrote:
> USAGE: single command line giving usage example
> for invoking the container; will be "N/A" for
> some containers.
Why N/A? What circumstances would this be?
--
Matthew Miller
<mattdm(a)fedoraproject.org>
Fedora Project Leader
12:44 p.m.
On 01/10/2017 10:41 AM, Matthew Miller wrote:
On Tue, Jan 10, 2017 at 10:33:05AM -0800, Josh Berkus wrote:
>> USAGE: single command line giving usage example
>> for invoking the container; will be "N/A" for
>> some containers.
Why N/A? What circumstances would this be?
CNI Networking container for Kubernetes, for example. A bunch of
"infra" containers only get invoked by other containers and/or the
orchestration system.
--
--
Josh Berkus
Project Atomic
Red Hat OSAS
12:52 p.m.
On Tue, Jan 10, 2017 at 10:44:03AM -0800, Josh Berkus wrote:
> On Tue, Jan 10, 2017 at 10:33:05AM -0800, Josh Berkus wrote:
>>> USAGE: single command line giving usage example
>>> for invoking the container; will be "N/A" for
>>> some containers.
>
> Why N/A? What circumstances would this be?
CNI Networking container for Kubernetes, for example. A bunch of
"infra" containers only get invoked by other containers and/or the
orchestration system.
Could we develop standard wording for that? Like
USAGE: Invoked by $OTHERCONTAINER
or
USAGE: Invoked by Kubernetes when $WHATEVERTRIGGERS
or are there too many possibilities?
--
Matthew Miller
<mattdm(a)fedoraproject.org>
Fedora Project Leader
1:47 p.m.
On 01/10/2017 10:52 AM, Matthew Miller wrote:
On Tue, Jan 10, 2017 at 10:44:03AM -0800, Josh Berkus wrote:
>> On Tue, Jan 10, 2017 at 10:33:05AM -0800, Josh Berkus wrote:
>>>> USAGE: single command line giving usage example
>>>> for invoking the container; will be "N/A" for
>>>> some containers.
>>
>> Why N/A? What circumstances would this be?
> CNI Networking container for Kubernetes, for example. A bunch of
> "infra" containers only get invoked by other containers and/or the
> orchestration system.
Could we develop standard wording for that? Like
USAGE: Invoked by $OTHERCONTAINER
or
USAGE: Invoked by Kubernetes when $WHATEVERTRIGGERS
or are there too many possibilities?
I don't think there are. I'd suggest:
---------------
USAGE: Invoked by $SOMEPROCESS. Not for direct use.
"$SOMEPROCESS" should be the name of the infrastructure tool, container,
or other utility which consumes this container.
---------------
--
--
Josh Berkus
Project Atomic
Red Hat OSAS
2:17 p.m.
On Tue, Jan 10, 2017 at 1:47 PM, Josh Berkus <jberkus(a)redhat.com> wrote:
On 01/10/2017 10:52 AM, Matthew Miller wrote:
> On Tue, Jan 10, 2017 at 10:44:03AM -0800, Josh Berkus wrote:
>>> On Tue, Jan 10, 2017 at 10:33:05AM -0800, Josh Berkus wrote:
>>>>> USAGE: single command line giving usage example
>>>>> for invoking the container; will be "N/A" for
>>>>> some containers.
>>>
>>> Why N/A? What circumstances would this be?
>> CNI Networking container for Kubernetes, for example. A bunch of
>> "infra" containers only get invoked by other containers and/or the
>> orchestration system.
>
> Could we develop standard wording for that? Like
>
> USAGE: Invoked by $OTHERCONTAINER
>
> or
>
> USAGE: Invoked by Kubernetes when $WHATEVERTRIGGERS
>
> or are there too many possibilities?
I don't think there are. I'd suggest:
---------------
USAGE: Invoked by $SOMEPROCESS. Not for direct use.
"$SOMEPROCESS" should be the name of the infrastructure tool, container,
or other utility which consumes this container.
---------------
+1 - I like that idea, makes it very clear to the user.
-AdamM
> --
> --
> Josh Berkus
> Project Atomic
> Red Hat OSAS
> _______________________________________________
> cloud mailing list -- cloud(a)lists.fedoraproject.org
> To unsubscribe send an email to cloud-leave(a)lists.fedoraproject.org
7:12 a.m.
On Jan 10, 2017 15:17, "Adam Miller" <maxamillion(a)fedoraproject.org>
wrote:
On Tue, Jan 10, 2017 at 1:47 PM, Josh Berkus <jberkus(a)redhat.com> wrote:
On 01/10/2017 10:52 AM, Matthew Miller wrote:
> On Tue, Jan 10, 2017 at 10:44:03AM -0800, Josh Berkus wrote:
>>> On Tue, Jan 10, 2017 at 10:33:05AM -0800, Josh Berkus wrote:
>>>>> USAGE: single command line giving usage example
>>>>> for invoking the container; will be "N/A" for
>>>>> some containers.
>>>
>>> Why N/A? What circumstances would this be?
>> CNI Networking container for Kubernetes, for example. A bunch of
>> "infra" containers only get invoked by other containers and/or the
>> orchestration system.
>
> Could we develop standard wording for that? Like
>
> USAGE: Invoked by $OTHERCONTAINER
>
> or
>
> USAGE: Invoked by Kubernetes when $WHATEVERTRIGGERS
>
> or are there too many possibilities?
I don't think there are. I'd suggest:
---------------
USAGE: Invoked by $SOMEPROCESS. Not for direct use.
"$SOMEPROCESS" should be the name of the infrastructure tool, container,
or other utility which consumes this container.
---------------
+1 - I like that idea, makes it very clear to the user.
-AdamM
I disagree that the usage should be limited to "used by another container".
Even though that is the intended use, the usage description should be
uniform and state what capability or function is provided.
Actual usage pattern for code is always more interesting than intended use.
9:34 a.m.
On Wed, Jan 11, 2017 at 08:12:53AM -0500, Subhendu Ghosh wrote:
I disagree that the usage should be limited to "used by another
container".
To be clear, I'm only suggesting that when it is meant to be used in
that way, and as more helpful than N/A. This line is meant to be a
brief statement....
Even though that is the intended use, the usage description should
be
uniform and state what capability or function is provided.
Actual usage pattern for code is always more interesting than intended use.
... and doesn't the "description" cover that detail?
--
Matthew Miller
<mattdm(a)fedoraproject.org>
Fedora Project Leader
12:40 p.m.
On Tue, Dec 13, 2016 at 3:24 PM, Josh Berkus <jberkus(a)redhat.com> wrote:
Folks,
Looking at the new FDLIBS, I'm noticing that there's not a narrative
description of the image required or provided anywhere that I can find.
Clearly one is needed for users. So, here's a proposal:
New Required LABELs:
USAGE: single command line giving usage example
for invoking the container; will be "N/A" for
some containers.
DESCRIPTION: Narrative description incuding:
* What service/software it provides
* What specific purpose it fulfills, if required
* Notes on how to use it, if not covered by USAGE,
such as how to supply configuration files
* Depedencies on other images (e.g. "requires a database")
* Links to documentation for the Software, if any
+1 - I like this, it follows nicely with the upstream guidelines[0]
referenced in Fedora's that I'd like to further adopt as all of this
evolves in Fedora space.
I'd also at some point like to discuss the labels needed for atomic
app install/uninstall and OpenShift guidelines[1] that we should at
least provide information on how to offer the 'atomic install' and
OpenShift deployment functionality for a container to users.
-AdamM
[0] - https://github.com/projectatomic/ContainerApplicationGenericLabels
[1] -
https://docs.openshift.org/latest/creating_images/guidelines.html#openshi...
> --
> --
> Josh Berkus
> Project Atomic
> Red Hat OSAS
> _______________________________________________
> cloud mailing list -- cloud(a)lists.fedoraproject.org
> To unsubscribe send an email to cloud-leave(a)lists.fedoraproject.org
2:54 p.m.
On Tue, Jan 10, 2017 at 12:40:27PM -0600, Adam Miller wrote:
+1 - I like this, it follows nicely with the upstream guidelines[0]
referenced in Fedora's that I'd like to further adopt as all of this
evolves in Fedora space.
I see that these guidelines use all lower case; we should probably
follow a consistent convention.
Also, looks like instead of "usage", that recommends:
help Command to run the help command of the image
run Command to run the image
--
Matthew Miller
<mattdm(a)fedoraproject.org>
Fedora Project Leader
2659
days inactive
2688
days old
10 comments
4 participants
participants (4)
-
Adam Miller -
Josh Berkus -
Matthew Miller -
Subhendu Ghosh