Repository navigation
Discussion- full rewrite of the training manual #395
Description
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
httptool on my machine does not support the-quietflag, which causes failures. - Username and PAT does not always load correctly
- ...etc.
- 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
Tags for exposure:
- @githubtraining/trainers
- @amyschoen
Activity
JoshuaTheMiller commentedon Feb 27, 2023
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 commentedon Feb 27, 2023
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 commentedon Mar 19, 2023
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 commentedon May 17, 2023
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
ghscripts 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
pwshandgh-cliwith 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 commentedon May 17, 2023
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 commentedon May 17, 2023
@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 commentedon May 17, 2023
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 commentedon May 17, 2023
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 commentedon Jul 5, 2023
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_TOKENenvironment variable for authentication: https://registry.terraform.io/providers/integrations/github/latest/docs#authentication