Discussion- full rewrite of the training manual

[JoshuaTheMiller]

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:

• Less error prone- SDKs have the benefit of syntax completion and error checking built-in at writing time
• Consistent development and running experience- the runtimes of the SDKs handle a lot for us. I've seen many issues popping up over the last few years using this training manual along the lines of, "this works on Mac, but not on PC."
• More exposure of the official SDKs
• Truly cross-platform
  • The existing scripts make a LOT of assumptions around tools that are installed... For example, I've recently run into issues due to the fact that the version of the http tool on my machine does not support the -quiet flag, which causes failures.
  • Username and PAT does not always load correctly
  • ...etc.

Tags for exposure:

• @githubtraining/trainers
• @amyschoen

[JoshuaTheMiller]

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]

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]

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]

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]

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]

@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]

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]

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:

• Leveraging the CLI in these bash scripts would be a marked improvement, but it still wouldn't easily solve the problem of cross-platform compatibility. I love the thought of using Codespaces as well, but I still want to be able to run stuff locally with no-pain when possible.

[riezebosch]

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