Contributing Guide and Getting Started #6

vsoch · 2019-02-23T22:59:08Z

Signed-off-by: Vanessa Sochat vsochat@stanford.edu

This pull request (again!) will add the early start to:

a contribution guide
a "getting started with containers" documentation base

Once the repository is set up, other containernerds can contribute their knowledge, and we can use the framework as a starting base for contribution. I suspect we might want to also move the oci-contribution repo to fall somewhere under the organization. The general idea is that we want a central place for issue tracking, and keeping templates to help with contribution.

GitHub pages will need to be turned on for this to deploy! Oh please robot overlords don't get angry about the signing thing... :)

Signed-off-by: Vanessa Sochat <vsochat@stanford.edu>

jonjohnsonjr

This is awesome. I scanned through it and left some comments (mostly a bunch of typo nits).

docs/introduction/distribution.md

index.md

docs/about.md

docs/introduction/introduction.md

docs/introduction/oci-types.md

docs/introduction/digests.md

docs/introduction/distribution.md

docs/contributing/contributing.md

Signed-off-by: Vanessa Sochat <vsochat@stanford.edu>

zendril · 2019-02-26T02:48:11Z

Can we move the /security.md and /code-of-conduct.md into docs as they are sort of orphaned at the root.
Also consider adding the frontmatter to both of them so that they will appear on the left nav and be ordered towards the bottom.

vsoch · 2019-02-26T02:49:49Z

Definitely! This would make sense to integrate into the front matter. I didn't touch those docs because they were in the original repo content, but happy to do this with @vbatts blessing!

zendril · 2019-02-26T03:00:04Z

Definitely! This would make sense to integrate into the front matter. I didn't touch those docs because they were in the original repo content, but happy to do this with @vbatts blessing!

Yeah, I figured as much (why you left them). I would make the case to Mr. @vbatts that they are more compelling in a home with the rest of docs all tied into a cohesive flow now.

docs/introduction/container-images.md

zendril · 2019-02-26T03:18:22Z

docs/introduction/introduction.md

+
+A container is generally an encapsulated environment that is created from one or more binaries (images) to provide some form of isolation. Read more about [containers here]({{ site.baseurl }}docs/introduction/container-images/).
+
+## What is OCI?


I would say omit this section as you have already laid out a basic navigation in the index (and left nav) to be:

About

Introductory Material

Contributing

These sections are the topics for the introductory material:

Container Images

What is OCI

Specification Types

Content Addressability

Distribution

The children of "Introductory material" one level up at:

About

Introductory Material

Contributing

I would suggest that we keep an organizational structure under Introductory Material, because it's likely to grow and even need further sub topics. Is there a better title / order for this list, or just a rephrasing of the container image section, so you don't feel it is redundant?

I agree that the structure should be essentially

About

Introductory Material

Container Images

What is OCI --> Links to /About

Specification Types

Content Addressability

Distribution

Contributing

My comment was more that this one little paragraph "What is OCI" then just linked back to a top level 'About'. Seemingly redundant or circular.. Perhaps there is no top level /About or else we need to figure out what content should go into "What is OCI" that is different than /About

Oh, good call! You are saying that "About this web interface thing you are looking at" is a different beastie than "About OCI under the docs." I completely agree. Right now it links to the "About this site" page, and I think we should likely have a more verbosely written "This is what OCI is all about, history" under the docs. I think this detail is out of scope for this first go, but important!

docs/introduction/container-images.md

zendril · 2019-02-26T03:36:30Z

docs/introduction/container-images.md

+It's because the linux containers API is pretty compiicated. Containers in linux are controlled by
+a Kernel API, and I found a good summary and diagram in the talk [here](https://www.youtube.com/watch?v=YsYzMPptB-k#t=18m10s) picture at 18 minutes, 10 seconds. There is quite some (people-based) history behind 
+the underlying API. Watch the same [talk a bit later](https://www.youtube.com/watch?v=YsYzMPptB-k#t=24m45s) for another useful picture. Generally, there are two components under discussion:
+


I can buy these as the primary 2 topics, but I would also throw in the union filesystem as the third leg that rounds out the core concepts people need to understand.

Would you be able and willing to add this via PR after merge?

Absolutely. This is why I'm eager for the PR to get at least merged in, even if not totally 'done'. Otherwise I'm manually working off of your personal repo which I can't then contribute to here.

Me too! See here #9 for the move into the "docs" folder we discussed in the call.

vbatts · 2019-02-26T14:03:46Z

Can we move the /security.md and /code-of-conduct.md into docs as they are sort of orphaned at the root.
Also consider adding the frontmatter to both of them so that they will appear on the left nav and be ordered towards the bottom.

the CoC is a canonical document, not to be confused with a projects docs IMO. I see it like having a LICENSE sitting at the root path.

The security.md needs to be in a folder for security process handling. There are more documents forthcoming about security disclosure process and templates for communication. So again, not just docs.

vsoch · 2019-02-26T14:07:10Z

How about a CODE_OF_CONDUCT.md in a .github folder so it’s detected by the repo, and a security folder for forthcoming security docs?

vbatts · 2019-02-26T14:10:14Z

How about a CODE_OF_CONDUCT.md in a .github folder so it’s detected by the repo

Maybe fine? I don't want it hidden, and every other project (image-spec, runtime-spec, runc, etc.) will need to link and reference it.

security folder for forthcoming security docs?

yes

Signed-off-by: Vanessa Sochat <vsochat@stanford.edu>

vsoch · 2019-02-26T15:01:50Z

@vbatts the code of conduct in the distribution spec is in reference to the one in the opencontainers/tob repository (see here) is this correct / incorrect, should it be changed to the one here? The same is true for runtime and image spec. Are there different ones?

vbatts · 2019-02-26T16:59:35Z

On 26/02/19 15:01 +0000, Vanessasaurus wrote: @vbatts the code of conduct in the distribution spec is in reference to the one in the opencontainers/tob repository (see [here](https://github.com/opencontainers/distribution-spec/blob/master/README.md)) is this correct / incorrect, should it be changed to the one here? The same is true for runtime and image spec. Are there different ones?

the tob CoC is moved to here. And they all ought to point here.

vsoch · 2019-02-26T17:01:00Z

okay, I'll fix this.

vsoch · 2019-02-26T17:15:51Z

Okay just updated the runtime-spec, distribution-spec, and image-spec to link to the (updated location in .github/CODE_OF_CONDUCT.md) to be merged here:

vsoch · 2019-02-26T17:18:54Z

I haven't been using that style to format links of putting them at the bottom - I like it! I think I'll do this from now on, e.g.,:

[charter]: https://www.opencontainers.org/about/governance
[code-of-conduct]: https://github.com/opencontainers/org/blob/master/.github/CODE_OF_CONDUCT.md
[issues]: https://github.com/opencontainers/distribution-spec/issues
[mailing-list]: https://groups.google.com/a/opencontainers.org/forum/#!forum/dev

It's so neat and tidy.

vbatts · 2019-02-26T18:02:37Z

On 26/02/19 17:15 +0000, Vanessasaurus wrote: Okay just updated the runtime-spec, distribution-spec, and image-spec to link to the (updated location in .github/CODE_OF_CONDUCT.md) to be merged here: - opencontainers/image-spec#762 - opencontainers/runtime-spec#1001 - opencontainers/distribution-spec#57

Related to #3 ;-)

vsoch · 2019-02-26T18:07:34Z

Ah, there is more to be done - I'm on it! Let me just eat these avocados first :)

vbatts · 2019-02-26T19:34:50Z

docs/introduction/container-images.md

+Here! Each cgroup is separately mountable. 
+
+```bash
+ls -l /sys/fs/cgroup


this won't age well :-)
Cgroup v2 is coming imminently and has a different layout.

Let' cut it out then.

vbatts · 2019-02-26T19:35:31Z

docs/introduction/container-images.md

+dr-xr-xr-x 6 root root  0 Aug 29 15:00 systemd
+```
+
+Each of these is a folder, and the simplest one is "freezer." The way we control cgroups is via file system calls.


perhaps some of this can just defer to the runtime-spec, as it will also vary for platform (i.e. windows)

…ec repo Signed-off-by: Vanessa Sochat <vsochat@stanford.edu>

vbatts · 2019-02-27T22:12:25Z

split the PR into two things: 1) move the CoC and security; 2) the web render for contributions

vsoch · 2019-02-27T22:28:20Z

move the CoC and security: renaming code of conduct and creating security folder #8

vbatts · 2019-02-27T22:30:21Z

ty!

vsoch · 2019-02-27T22:49:13Z

Moved documentation for contribution into docs subfolder moving contributing docs into subfolder, docs #9

Trying again, with -s so its signed.

0a1b64d

Signed-off-by: Vanessa Sochat <vsochat@stanford.edu>

jonjohnsonjr reviewed Feb 25, 2019

View reviewed changes

fixing up typos and other small errors

11a9430

Signed-off-by: Vanessa Sochat <vsochat@stanford.edu>

vbatts self-assigned this Feb 25, 2019

Open Containers -> Open Container

60a6abe

Signed-off-by: Vanessa Sochat <vsochat@stanford.edu>

zendril reviewed Feb 26, 2019

View reviewed changes

docs/introduction/container-images.md Outdated Show resolved Hide resolved

zendril reviewed Feb 26, 2019

View reviewed changes

docs/introduction/container-images.md Show resolved Hide resolved

zendril reviewed Feb 26, 2019

View reviewed changes

docs/introduction/container-images.md Outdated Show resolved Hide resolved

zendril reviewed Feb 26, 2019

View reviewed changes

docs/introduction/container-images.md Outdated Show resolved Hide resolved

zendril reviewed Feb 26, 2019

View reviewed changes

vsoch added 2 commits February 26, 2019 09:47

reorganizing security.md into folder, contributing into .github

902d3c9

Signed-off-by: Vanessa Sochat <vsochat@stanford.edu>

fixing up container images history page

05916a4

Signed-off-by: Vanessa Sochat <vsochat@stanford.edu>

vsoch mentioned this pull request Feb 26, 2019

updating CoC link and security link opencontainers/go-digest#42

Merged

vbatts reviewed Feb 26, 2019

View reviewed changes

moving examples for namespaces and cgroups, adding link to runtime-sp…

8a1fad9

…ec repo Signed-off-by: Vanessa Sochat <vsochat@stanford.edu>

vsoch mentioned this pull request Feb 27, 2019

renaming code of conduct and creating security folder #8

Merged

vsoch mentioned this pull request Feb 27, 2019

moving contributing docs into subfolder, docs #9

Merged

vsoch mentioned this pull request Feb 27, 2019

updating link to code of conduct in org repository opencontainers/distribution-spec#57

Merged

vbatts closed this Mar 7, 2019

vsoch deleted the add/contributing-guide-again branch March 7, 2019 20:11

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Contributing Guide and Getting Started #6

Contributing Guide and Getting Started #6

vsoch commented Feb 23, 2019

jonjohnsonjr left a comment

zendril commented Feb 26, 2019

vsoch commented Feb 26, 2019

zendril commented Feb 26, 2019

zendril Feb 26, 2019

vsoch Feb 26, 2019

zendril Feb 27, 2019

vsoch Feb 27, 2019

zendril Feb 26, 2019

vsoch Feb 26, 2019

zendril Feb 27, 2019

vsoch Feb 27, 2019

vbatts commented Feb 26, 2019

vsoch commented Feb 26, 2019

vbatts commented Feb 26, 2019

vsoch commented Feb 26, 2019

vbatts commented Feb 26, 2019 via email

vsoch commented Feb 26, 2019

vsoch commented Feb 26, 2019

vsoch commented Feb 26, 2019

vbatts commented Feb 26, 2019 via email

vsoch commented Feb 26, 2019

vbatts Feb 26, 2019

vsoch Feb 26, 2019

vbatts Feb 26, 2019

vsoch Feb 26, 2019

vbatts commented Feb 27, 2019

vsoch commented Feb 27, 2019

vbatts commented Feb 27, 2019

vsoch commented Feb 27, 2019


		A container is generally an encapsulated environment that is created from one or more binaries (images) to provide some form of isolation. Read more about [containers here]({{ site.baseurl }}docs/introduction/container-images/).

		## What is OCI?

Contributing Guide and Getting Started #6

Contributing Guide and Getting Started #6

Conversation

vsoch commented Feb 23, 2019

jonjohnsonjr left a comment

Choose a reason for hiding this comment

zendril commented Feb 26, 2019

vsoch commented Feb 26, 2019

zendril commented Feb 26, 2019

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

vbatts commented Feb 26, 2019

vsoch commented Feb 26, 2019

vbatts commented Feb 26, 2019

vsoch commented Feb 26, 2019

vbatts commented Feb 26, 2019 via email

vsoch commented Feb 26, 2019

vsoch commented Feb 26, 2019

vsoch commented Feb 26, 2019

vbatts commented Feb 26, 2019 via email

vsoch commented Feb 26, 2019

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

vbatts commented Feb 27, 2019

vsoch commented Feb 27, 2019

vbatts commented Feb 27, 2019

vsoch commented Feb 27, 2019