githubtraining / training-manual

Home of the words in the GitHub Training Manual and teaching scripts.
https://githubtraining.github.io/training-manual
Creative Commons Attribution 4.0 International
269 stars 273 forks source link

Discussion- full rewrite of the training manual #395

Open JoshuaTheMiller opened 1 year ago

JoshuaTheMiller commented 1 year ago

Hey all!

I am starting this Issue in the hopes of having a productive conversation around rewriting the entire Training Manual to leverage one of the official GitHub SDKs.

Benefits:

Tags for exposure:

JoshuaTheMiller commented 1 year ago

Full disclosure- I have toyed with the idea of rewriting this entire project using the NodeJS SDK myself. I would utilize Typescript for an enhanced writing-time experience though.

amyschoen commented 1 year ago

For the record, I advised Josh to post here. If we're going to do a rewrite, it makes sense to start with the open source version and then port things down to our local version. I can work in pretty much any language, so I'm good with whatever the official GitHub folks and instructors at other companies decide.

JoshuaTheMiller commented 1 year ago

I'll be teaching this course in 2 weeks. I do hope to revisit this Issue afterwards and potentially start on a rewrite if this community thinks doing so would be valuable as per my rationale listed above 😀

jessehouwing commented 1 year ago

I'd be in favor of scripting using the gh cli, but against node or the official SDK. I've had to debug issues in the labs of this class many a times in the past 3 years and fixes have never truly been easy.

I suspect that template repos with a github actions script that runs on "repo created" would make it a lot easier. People would use the template, it would trigger a workflow to create issues and conflicts ad the like with a couple of simple gh scripts and would prevent having to invite people. assign them permissions etc.

I'd also LOVE it if the labs themselves would be in a Codespace and wouldn't rely on the local user's configuration. We've had to fix many a client who is taking part in this class on github public, but their enterprise uses EMU, causing auth issues, signing issues, proxy, VPN, and more madness.

Being able to leverage codespaces (from a template repo) together with prebuilds would help a LOT.

Personally, I'd probably use pwsh and gh-cli with a few extensions, as I've come to hate Node. Being a windows user Node often doesn't exactly do as promised or has platform dependent features...

amyschoen commented 1 year ago

This class is used for both .com and GHES (soon to have GHEC added). I like the idea of adding codespaces as an option, but we do need to allow for being able to do the labs locally as well.

amyschoen commented 1 year ago

@jessehouwing, @JoshuaTheMiller is also a Windows user. He might be able to give you some pointers. I have both Mac and Windows but typically stick to Mac for running the class scripts. I'll teach from both. It depends on what type of computers the majority of my students have.

jessehouwing commented 1 year ago

I run everything in the CodeSpace now. Which it's why it's imperative that thing keeps working.

It would be good if prebuilds were setup so at least someone is notified when things break.

JoshuaTheMiller commented 1 year ago

Ohmygosh, a mini-celebrity commented on my Issue 🤩

Now that that's out of the way, @jessehouwing- I'd be curious to discuss your concerns more. I pose that leveraging the SDK would still be better than leveraging the GH CLI 😀

With that being said, my intent is to ALSO include the comparable CLI commands in the scripts themselves so folks can learn about both at the same time.

As a more concrete piece of rationale:

riezebosch commented 1 year ago

Another option to consider: https://registry.terraform.io/providers/integrations/github/latest/docs

Regarding infrastructure-as-code I've come to learn that the declarative nature of terraform outweighs any imperative approach when it comes to maintenance.

Just started on this one: https://github.com/riezebosch/training-manual

Use the GITHUB_TOKEN environment variable for authentication: https://registry.terraform.io/providers/integrations/github/latest/docs#authentication