search

operate-first / common

Git Hub organization configuration
GNU General Public License v3.0
6 stars 64 forks source link

CREATE: training-template repository #39

Closed stefwrite closed 2 years ago

stefwrite commented 2 years ago

New Repository

training-template

Repository description

This repository will serve as the template for our development spaces for training content that will live within Operate First.

Admin access

The same as the Operate First group admins + stefwrite (swatson@redhat.com)

Write access

The same as the Operate First group admins + stefwrite (swatson@redhat.com)

quaid commented 2 years ago

This one didn't get any bot automation, not sure if that is normal or something didn't work?

So @stefwrite and team are ready for a training repository, but it's not entirely clear what is the best structure to take for that. One repository per course? One repo that is just the Lego-bucket of content? Or do this all in branches?

I'll take this out to the mailing list for some input from others for the best method.

stefwrite commented 2 years ago

Thanks for getting this conversation started, Karsten.

There is an advantage of having things in a common repository for the ease of building content modularly.

However, our team creating training content would like to see automation for certain builds, too. For example, when we build all the content for an interactive community course (using Jupyter Book, markdown, etc.), we'd like for changes committed/pushed to that content to trigger a CI process that can build and publish the course to a target location on the website.

Ideas are welcome!

-Stephanie

On Mon, Nov 15, 2021 at 9:59 AM Karsten Wade @.***> wrote:

This one didn't get any bot automation, not sure if that is normal or something didn't work?

So @stefwrite https://github.com/stefwrite and team are ready for a training repository, but it's not entirely clear what is the best structure to take for that. One repository per course? One repo that is just the Lego-bucket of content? Or do this all in branches?

I'll take this out to the mailing list for some input from others for the best method.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/operate-first/common/issues/39#issuecomment-968993757, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAYMZM4TBDFFG63ZTBJT5TUMEN3NANCNFSM5GWEBFBA . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

quaid commented 2 years ago

I dropped a summary to the mailing list with an invite for folk to come to this discussion.

Here is the email, and the body of my text:

All:

The team working on SRE training are ready to setup their repositories, and Stephanie created this issue for opening the first repository:

https://github.com/operate-first/common/issues/39

We had a meeting today with the team who is going to be working in GitHub, and we're not sure what is the best model to follow for repositories.

Please join us there to discuss what we want the repo(s) to look like. We particularly need help from people with experience around automation across multiple repositories.

Background

Stephanie and anyone else, please fix any incorrect GitHub and modularity thinking here, thanks.

As a community, we are creating a knowledge pool of modular course materials. Modular here means, creating discrete pieces of content, each explaining what, how, and why for a task. The learner might be a contributor learning or reminding how to do the task; or the learner might be a user taking a full SRE course. The same content can be used in both cases, but placed into a context specific for the different learner type. This content therefore is more than a Markdown file, it has inline or metadata (labels, etc.) that means it can be organized to appear in multiple learning pathways.

These multiple learning pathways currently are: SRE Learners, Open Source Developers, Project Contributors, and Data Scientists and Data Engineers.

So if combining the pool with the number of learning path options, it could be four separate learning paths with e.g. twelve modules per path. Those modules would comprise existing modular content, combined with content specific to the module that shapes the relationship to the learner persona. An example of a single module might be, "How to use GitOps to make changes to a live production cloud." It could have the how-to and sparse-why content (useful for Project Contributors and Open Source Developers) from one location (a repo?), which can be combined with the full what/how/why of a beginner's viewpoint into a single ready-to-teach module.

That's already 48 unique combinations to cover four pathways, and within those modules it might be 3x to 5x more when combining pieces to form a specific module.

Is this a repos problem? A branching problem? A nesting folders problem? Or something else?

HumairAK commented 2 years ago

I'm unfamiliar with this initiative so I'm looking for a bit of clarification here...

So @stefwrite and team are ready for a training repository, but it's not entirely clear what is the best structure to take for that. One repository per course? One repo that is just the Lego-bucket of content? Or do this all in branches?

What is the training content composed of? If it's jupyterbook/notebooks/markdown, why do we need separate branches or repos? Why not one repo with a directory structure for organization of different course content? e.g. openshift-labs.

Also why do we need another separate repo?

Will these training modules be using content completely in isolation from our other documentation? Example like here? If so then I suppose a separate repository make sense. If there's overlap, then I'd argue this content should be in the same repository for maintainability. Otherwise we're just going to have duplication of content being written by different folks.

Also...who are the target contributor demographic for these training modules? As an ops focused contributor, am I expected to take part here? If so I'd rather have this content alongside our other documentation under a separate training directory, so we have less repos to make PRs to when a procedure changes and it needs to be reflected in a 'how-to' style doc.

stefwrite commented 2 years ago

I'll see if I can clear some things up for you and others who aren't familiar with the project:

I hope this helps clear up a few things about the project itself.

Right now, our immediate question is whether working out of a single repository is even possible. Courses will be built and maintained as separate units, each with its own life cycle. Thus, regardless of where the source content lives, we should probably use separate build pipelines for each course to avoid having to build an entire catalog just to fix a small issue in one course. Can we have multiple build pipelines based on the same repository's contents? Is that a good idea or something we should avoid?

-Stephanie

On Mon, Nov 15, 2021 at 2:19 PM Humair @.***> wrote:

I'm unfamiliar with this initiative so I'm looking for a bit of clarification here...

So @stefwrite https://github.com/stefwrite and team are ready for a training repository, but it's not entirely clear what is the best structure to take for that. One repository per course? One repo that is just the Lego-bucket of content? Or do this all in branches?

What is the training content composed of? If it's jupyterbook/notebooks/markdown, why do we need separate branches or repos? Why not one repo with a directory structure for organization of different course content? e.g. openshift-labs https://github.com/openshift-labs/learn-katacoda.

Also why do we need another separate repo?

Will these training modules be using content completely in isolation from our other documentation? Example like here https://github.com/operate-first/apps/tree/master/docs? If so then I suppose a separate repository make sense. If there's overlap, then I'd argue this content should be in the same repository for maintainability. Otherwise we're just going to have duplication of content being written by different folks.

Also...who are the target contributor demographic for these training modules? As an ops focused contributor, am I expected to take part here? If so I'd rather have this content alongside our other documentation under a separate training directory, so we have less repos to make PRs to when a procedure changes and it needs to be reflected in a 'how-to' style doc.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/operate-first/common/issues/39#issuecomment-969237942, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAYMZIHFOFNKB6H6IMKJRDUMFMNTANCNFSM5GWEBFBA . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

HumairAK commented 2 years ago

@stefwrite Thank you @stefwrite that clears up a lot of things!

Yeah if you're looking for 1 jupyterbook for 1 course, then in this case a repo per course is the easiest way to get started.

Can we have multiple build pipelines based on the same repository's contents?

ATM I believe we have 1 repo -> 1 build pipeline. @tumido @harshad16 can verify.

Though imho, having them all in one repo as part of the longer term roadmap makes a lot more sense to me. If for example, one link changes, having to make pr's to 10-15 repos sounds like a nightmare. And as you said, referencing across courses would be easier.

quaid commented 2 years ago
  • It's certainly possible to put everything into one repository (including all the graphics and audio that we typically include). The upside is that we can easily reference other content across the repository. The downside is that each new course we add will grow that repository and create for larger checkouts over time. At the moment, we're certain we'll produce 10-15 courses from our team, and we hope others will follow the model we set up to create even more.

One of the strange magics of git is how small a checkout is despite how large and old the repository is, right?

So it's possible that 15 - 30 courses is not that large of an initial checkout. Wherever possible, git is only tracking the difference between different commits and across branches, so each commit and new branch is not very large.

If you have a lot of large media assets (and especially if they are unique for each module), maybe there's some kind of lookaside cache that can be used, so the repo only holds pointers the actual asset in the cache?

HumairAK commented 2 years ago

I confirmed with @harshad16 that it is actually possible to have multiple build pipelines associated with one repo, e.g. https://github.com/thoth-station/solver/blob/master/.aicoe-ci.yaml

durandom commented 2 years ago

I suggest to start with one repo and see how complex it gets building multiple JupyterBooks.

Is operate-first/training a good name? If so @HumairAK can you create the repo and setup bot automation for it?

durandom commented 2 years ago

And for access I suggest to create a training team

stefwrite commented 2 years ago

Yes, I think a united single repository should just be "training".

On Wed, Nov 17, 2021 at 4:07 AM Marcel Hild @.***> wrote:

I suggest to start with one repo and see how complex it gets building multiple JupyterBooks.

Is operate-first/training a good name? If so @HumairAK https://github.com/HumairAK can you create the repo and setup bot automation for it?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/operate-first/common/issues/39#issuecomment-971377686, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAYMZJREIWC6OUENOCSK73UMNWGHANCNFSM5GWEBFBA . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

-- Stephanie Watson, RHCE

she/her/hers | Program Manager, PnT Associate Experience @.** | M: 919-333-5050 Subscribe to stay informed about the latest PnT training opportunities: pntae-training-announce http://post-office.corp.redhat.com/mailman/listinfo/pntae-training-notifications* https://red.ht/sig

quaid commented 2 years ago

And for access I suggest to create a training team

And an associated group of humans who meet regularly and drive progress transparently in the community, following whatever organizational structure we create in the coming weeks.

HumairAK commented 2 years ago

Hey guys, I've added some docs on:

  1. how to add a repo
  2. how to join/create a team/get access to a repo

Anyone willing to try to provision this repo themselves using these instructions, would also find the feedback on the docs useful, so we can improve them :)

quaid commented 2 years ago

@coghlanRH and I are going to create this new repo training, thanks @HumairAK for the docs.

HumairAK commented 2 years ago

New repo created, thanks for the PR @coghlanRH ! https://github.com/operate-first/training

If you guys need admin access to this repo, you'll need to be in a GH team that has admin rights to the repo: https://github.com/operate-first/common/blob/main/docs/add_gh_member_and_access.md

quaid commented 2 years ago

New repo created, thanks for the PR @coghlanRH ! https://github.com/operate-first/training

If you guys need admin access to this repo, you'll need to be in a GH team that has admin rights to the repo: https://github.com/operate-first/common/blob/main/docs/add_gh_member_and_access.md

Great, and thank you for the link to the docs!

@stefwrite has volunteered to do the updated to the OWNERS file, and we will probably also touch the README and contributors.md files.

stefwrite commented 2 years ago

We have the repo we need, and the OWNERS file is up-to-date. Closing this out.