First draft, definitions of Pulp's core concepts #3244

asmacdo · 2017-12-14T14:51:51Z

This document is intended to be a base language so we can be internally consistent with how we write about and discuss Pulp.

daviddavis · 2017-12-15T17:44:51Z

I'm wondering if we should use the term "RepositoryVersion" given that we use "Repository" instead of "Repo". In Katello there was mixed usage of "Repo" and "Repository" and it was a huge pain. Thoughts?

daviddavis · 2017-12-15T17:47:33Z

docs/contributing/language_guide.rst

+Definitions
+-----------
+
+[``ContentUnit``, **plugin**, ``type``, ``Artifact``]


👍 to ContentUnit

asmacdo · 2017-12-15T20:26:43Z

@daviddavis +1 to RepositoryVersion.

bmbouter · 2017-12-18T17:40:42Z

docs/contributing/language_guide.rst

+    ``pulpcore`` is a generalized backend with a REST API and a plugin API. You will also need at
+    least one **plugin** to manage content.  Each **plugin** defines at least one ``type`` of
+    ``ContentUnit`` (like .rpm or .deb), which is the smallest set of data that can be managed by
+    Pulp. (The plural form of ``ContentUnit`` is a ``ContentUnits``, rather than Content or Units).


s/is a/is/
Also this sentence probably doesn't need parentheses.

bmbouter · 2017-12-18T17:43:17Z

docs/contributing/language_guide.rst

+    ``ContentUnit`` (like .rpm or .deb), which is the smallest set of data that can be managed by
+    Pulp. (The plural form of ``ContentUnit`` is a ``ContentUnits``, rather than Content or Units).
+    Files that belong to a ``ContentUnit`` are called ``Artifacts``, and each ``ContentUnit`` can
+    have 0 or many ``Artifacts``.  ``ContentUnits`` can share ``Artifacts``.


The last sentence is confusing to me. Maybe talking about it from the Artifact side would be an idea. Something like: An Artifact can be shared by multiple ContentUnits.

bmbouter · 2017-12-18T17:45:06Z

docs/contributing/language_guide.rst

+    have 0 or many ``Artifacts``.  ``ContentUnits`` can share ``Artifacts``.
+
+[``Repository``, **add**, **remove**, **RepoVersion**]
+    ``ContentUnits`` in Pulp are organized by their membership in ``Repositories``. You can **add**


The first two sentences need updating with repo versions.

I changed this a little bit, (added "over time"), but that change doesn't address your concerns. My thinking was that we will still talk about "adding ContentUnits to a "Repository", and that RepositoryVersions are /how/ that is done.

bmbouter · 2017-12-18T17:45:53Z

docs/contributing/language_guide.rst

+[``Repository``, **add**, **remove**, **RepoVersion**]
+    ``ContentUnits`` in Pulp are organized by their membership in ``Repositories``. You can **add**
+    or **remove** ``ContentUnits`` to/from a ``Repository``. Pulp provides deduplication of
+    ``ContentUnits`` and ``Artifacts`` so you don’t need be concerned about **adding** a


I don't understand the sentence starting from "so you don't ..."

bmbouter · 2017-12-18T17:46:27Z

docs/contributing/language_guide.rst

+    or **remove** ``ContentUnits`` to/from a ``Repository``. Pulp provides deduplication of
+    ``ContentUnits`` and ``Artifacts`` so you don’t need be concerned about **adding** a
+    ``ContentUnit`` to too many ``Repositories``.  ``Repositories`` are versioned, and you can
+    **add** or **remove** ``ContentUnits`` to a ``Repository`` by creating a new ``RepoVersion``


They only associate with a RepoVersion, not a Repository anymore.

Same as above.

bmbouter · 2017-12-18T17:48:34Z

docs/contributing/language_guide.rst

+    and specifying the ``ContentUnits`` to **add** or **remove**.
+
+[**upload**]
+    ``ContentUnits`` can be created in Pulp manually. You will need to specify the ``Artifacts``


In places where it says "you" maybe that should be "the user" and then the possessives that refer to them like "your" be "the user's", etc. If this is for language clarity the reader could be a variety of roles.

bmbouter · 2017-12-18T17:48:59Z

docs/contributing/language_guide.rst

+    **added** to a ``Repository`` manually by creating a new ``RepoVersion``.
+
+[**external source**, **sync**]
+    You can fetch ``ContentUnits`` and **add** them to your ``Repository`` by **syncing** with an


Similar with the "user" language here, and similar throughout the doc.

bmbouter

@asmacdo I read it line for line, and it's going to be a good improvement for our docs. I left some feedback on it. See what you think of the ideas.

asmacdo · 2018-01-02T21:35:38Z

@bmbouter, let me know if these changes fit how you want to think/talk about Repositories and RepositoryVersions.

bmbouter · 2018-01-03T20:30:07Z

docs/contributing/language_guide.rst

+[**upload**]
+    ``ContentUnits`` can be created in Pulp manually. Users specify the ``Artifacts`` that belong
+    to the ``ContentUnit`` and the **plugin** that defines the ``ContentUnit`` ``type``.
+    ``Artifacts`` that are not already managed by Pulp should be **uploaded** to Pulp prior to


What about s/managed/known/

bmbouter · 2018-01-03T20:32:55Z

docs/contributing/language_guide.rst

+    **external source**.)
+
+[``hosted``, **metdata**, ``Publisher``, ``Publication``, ``Distribution``]
+    All ``ContentUnits`` that are managed by Pulp are **hosted** as part of the ``pulpcore`` REST


s/are/can be/

Also I think it's s/REST API/Content App/ because the content app is it's own distinct webservice from the REST API.

bmbouter · 2018-01-03T20:34:44Z

docs/contributing/language_guide.rst

+
+[``hosted``, **metdata**, ``Publisher``, ``Publication``, ``Distribution``]
+    All ``ContentUnits`` that are managed by Pulp are **hosted** as part of the ``pulpcore`` REST
+    API.  A ``Publication`` referes to the **metadata** (flat files) for the set of


Somehow this needs to also include Artifacts because a Publication is made of both PublishedMetadata and PublishedArtifact objects. Also the metadata does not entirely have to describe content, it is content, just not the kind that has an Artifact backing it. I'm not sure how to best bring this in.

bmbouter · 2018-01-05T20:14:57Z

docs/contributing/language_guide.rst

+    ``ContentUnits`` can be created in Pulp manually. Users specify the ``Artifacts`` that belong
+    to the ``ContentUnit`` and the **plugin** that defines the ``ContentUnit`` ``type``.
+    ``Artifacts`` that are not already known by Pulp should be **uploaded** to Pulp prior to
+    creating a new ``ContentUnit``. ``ContentUnits`` are manually **added** to a


s/are/can be/

bmbouter · 2018-01-05T20:15:03Z

docs/contributing/language_guide.rst

+    to the ``ContentUnit`` and the **plugin** that defines the ``ContentUnit`` ``type``.
+    ``Artifacts`` that are not already known by Pulp should be **uploaded** to Pulp prior to
+    creating a new ``ContentUnit``. ``ContentUnits`` are manually **added** to a
+    ``Repository`` manually by creating a new ``RepositoryVersion``.


and then on the next line. s/manually//

bmbouter · 2018-01-05T20:15:45Z

docs/contributing/language_guide.rst

+    **external source**.)
+
+[``hosted``, **metdata**, ``Publisher``, ``Publication``, ``Distribution``]
+    All ``ContentUnits`` that are managed by Pulp are **hosted** as part of the ``pulpcore``


s/are/can be/

bmbouter · 2018-01-05T20:16:45Z

docs/contributing/language_guide.rst

+[``hosted``, **metdata**, ``Publisher``, ``Publication``, ``Distribution``]
+    All ``ContentUnits`` that are managed by Pulp are **hosted** as part of the ``pulpcore``
+    Content App. **plugin** defined ``Publishers`` generate ``Publications``, which
+    refer to the **metadata** and ``Artifacts`` of the ``ContentUnits`` in a ``RepositoryVersion``


How is **metadata** different from PublishedMetadata as a formal software object? I think introducing both PublishedMetadata and PublishedArtifacts may be good. What do you think?

I wanted to avoid defining any objects that aren't user facing, since they wont be semantically versioned.

What about plugin writers as a form of user? Those two objects are in the plugin API so they would be semver governed by the plugin API version. If it's just for users that is OK too, but I figured it would be in the user guide, not the contributor guide.

I'm thinking of this as a contributor guide for how to write about user facing concepts. I am +1 on creating a second document in this style in the plugin writers guide

Sounds good to me. I'm +1 to merge with the other small grammar fixes.

dralley · 2018-01-12T14:24:52Z

ok test

daviddavis · 2018-01-16T14:40:20Z

👍

daviddavis reviewed Dec 15, 2017

View reviewed changes

bmbouter reviewed Dec 18, 2017

View reviewed changes

Create definitions for Pulp's core concepts

f7922a0

asmacdo force-pushed the language-guide-starter branch from ee4889a to f7922a0 Compare January 2, 2018 21:30

bmbouter reviewed Jan 3, 2018

View reviewed changes

bmbouter reviewed Jan 5, 2018

View reviewed changes

PR comments

1583c52

asmacdo force-pushed the language-guide-starter branch from 4134ddb to 1583c52 Compare January 8, 2018 13:34

dralley approved these changes Jan 12, 2018

View reviewed changes

asmacdo merged commit 06df0bd into pulp:3.0-dev Jan 16, 2018

First draft, definitions of Pulp's core concepts #3244

First draft, definitions of Pulp's core concepts #3244

asmacdo commented Dec 14, 2017 •

edited

daviddavis commented Dec 15, 2017 •

edited

daviddavis Dec 15, 2017

asmacdo commented Dec 15, 2017

bmbouter Dec 18, 2017

bmbouter Dec 18, 2017

bmbouter Dec 18, 2017

asmacdo Jan 2, 2018

bmbouter Dec 18, 2017

bmbouter Dec 18, 2017

asmacdo Jan 2, 2018

bmbouter Dec 18, 2017

bmbouter Dec 18, 2017

bmbouter left a comment

asmacdo commented Jan 2, 2018

bmbouter Jan 3, 2018

bmbouter Jan 3, 2018

bmbouter Jan 3, 2018

bmbouter Jan 5, 2018

bmbouter Jan 5, 2018

bmbouter Jan 5, 2018

bmbouter Jan 5, 2018

asmacdo Jan 5, 2018

bmbouter Jan 5, 2018

asmacdo Jan 5, 2018

bmbouter Jan 5, 2018

dralley commented Jan 12, 2018

daviddavis commented Jan 16, 2018

First draft, definitions of Pulp's core concepts #3244

First draft, definitions of Pulp's core concepts #3244

Conversation

asmacdo commented Dec 14, 2017 • edited

daviddavis commented Dec 15, 2017 • edited

Choose a reason for hiding this comment

asmacdo commented Dec 15, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bmbouter left a comment

Choose a reason for hiding this comment

asmacdo commented Jan 2, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dralley commented Jan 12, 2018

daviddavis commented Jan 16, 2018

asmacdo commented Dec 14, 2017 •

edited

daviddavis commented Dec 15, 2017 •

edited