Considering the name and org of this repository

[brianamarie]

Name and org of this repository

As we work to open source this manual #202, now is a good time to consider the ownership and title of this repository. Any changes we make would include some effort to make sure things are done right, but it makes sense to open source this content in the right way.

We've decided to move and rename this repository from githubtraining/training-manual to github/github-training-manual.

Here's what needs to happen to make this work:

• Prep work:
• Open pull request addressing hard coded URLs Fix hard-coded URLs #232
• Open pull request addressing redirect Configure a redirect #231
• Create repository page linking to all manuals https://github.github.com/training/
• Configure redirect from training.github.com to https://github.github.com/training/
• All at once:
  • Move this repository to github org
  • Rename this repository to github-training-manual
  • Switch the repository to public
  • Merge the PR for hard coded URLs
  • Merge the PR for redirect

Contents of post originally

Org considerations

githubtraining vs github

githubtraining 😀

Historically, this was the easiest place for this type of content because of access management. We could easily add partners or customers to this repository without fearing we were giving "too much" access. Now, there is no difference in access management. Open sourcing this repository will do most of the work there for us, regardless of the org.

• 👍 Pro: Easier installation of 3rd party apps (if needed)
• ?

github 🎉

• 👍 Pro: Brand recognition, credibility, unified message
• 👎 Con: Historical links would break
• ?

Name

training-manual vs github-for-developers-manual

training-manual 👀

It's what it's always been called.

• 👎 Con: It's vague when we consider our growing materials for other content topics
• ?

github-for-developers-manual 🚀

• 👍 Pro: It's more specific to the content
• 👎 Con: Historical links would break
• ?

Next steps

@githubtraining/githubbers @githubtraining/trainers @matthewmccullough @dcdrennen @jonlipsky @AaronKowall @amyschoen Thoughts? Are there other pros/cons that aren't considered here? Please comment below with any additional thoughts, and/or react with opinions to this original post with the emojis by the different options above.

[amyschoen]

When we expanded our internal courses, we kept the training-manual name. I had similar reasoning to what's ☝️ about breaking links since the guide's become an internal reference for a lot of students who have taken the class. It's not a perfect solution, but we ended up giving better names to the new classes like training-manual-infra and training-manual-advanced.

As for changing orgs, I have no strong feelings either way on that one. If you have manuals for other course offerings, I'd lean towards keeping them together.

[jeffmcaffer]

Do the links actually break? Typically when moving repos/orgs links get forwarded.

[amyschoen]

That’s a good point @jeffmcaffer. Repo links will get forwarded until that combination of org and repo get reused. At least from the perspective of interacting with the git repo. I’m not sure if pages links also behave that way.

[brianamarie]

@githubtraining/implementation-engineers @githubtraining/programs When you get a window of time (~5 minutes) please read this issue and vote via emoji reactions on the original post. Thank you!

[parkerbxyz]

Since this training material is used for more than developers, maybe we should stick to a more generic name.

I've liked the idea of calling it developer-training because it is more specific than training-manual and differentiates it from our other offerings. But it could also be too specific, especially considering we use the same manual and activities for our non-developer training. We call it “Git and GitHub Training” on services.github.com and ”GitHub Training for [insert role here]” in the Phoenix Catalog. It's also referred to as “GitHub Basics” in some circles. Thoughts on using the name github-training?

Source: https://services.github.com/#offerings

[parkerbxyz]

githubtraining

Historically, this was the easiest place for this type of content because of access management. We could easily add partners or customers to this repository without fearing we were giving "too much" access. Now, there is no difference in access management. Open sourcing this repository will do most of the work there for us, regardless of the org.

This will require a larger conversation outside of this issue, but I can't help but wonder if it makes sense to keep using the githubtraining organization at all considering the reason for it was created is no longer relevant. Or maybe we should move repos like this and the admin-training repo to the GitHub organization and make this the Learning Lab organization. There is a lot of crossover currently that makes it unclear what should and shouldn't be kept in this organization vs. the GitHub organization.

[whatupfoo]

I like @parkerbxyz's idea of github training; it does align with our catalog, it includes our brand and is experience-agnostic, in that it caters to both beginners and advanced git users.

[brianamarie]

Thank you all for the feedback so far!

@amyschoen @parkerbxyz @rwnfoo, what do you think about github/github-training-manual?

[whatupfoo]

That sounds good to me. 👍

[brianamarie]

Great! I appreciate the patience on this, y'all. Let's move forward with github/github-training-manual. When we do, we will need it to be a public and open source repository so those with contributor access to this repository don't lose access. I am going to rename this repo now, and move it after it is made public and the relevant issues and PRs are closed or merged. 🎉

Thank you all!

[brianamarie]

Reopening - this in fact did not redirect the github pages site. We should implement redirection before changing the name and owner. Options are:

• Rename/move this repository, and create a new training-manual repository that will link to the new one both from the github repo and from the github pages site.
• Rename/move this repository, and depend on redirection for the github repository. Find a way to redirect through ghpages from the old URL. This would be possible with Jekyll, but we specifically use .nojekyll in this repository.

My proposal is for the first option - but I want to open this up briefly for discussion. Does anyone have alternatives, or opinions, on how we should handle this? cc @amyschoen @parkerbxyz @rwnfoo @jeffmcaffer

[amyschoen]

After typing out my idea. I happened to realize it's basically the same as the first choice. I guess that means that's my suggestion (and that I still need more ☕ this morning). 😀 It's not a very elegant solution, but it would solve the redirect issue. I'm in agreement with you on this one @brianamarie.

I do have one suggested addition to the plan since what we're trying to do isn't that far off from how we open source projects. Once all the redirects are in place, we should archive the new repository. That way, it makes it more obvious that we don't want to be making any more changes.

[parkerbxyz]

I just created a proof of concept to handle the redirection. We'll be able to reuse this solution for other Pages repositories in this organization if/when we rename or transfer them in the future.

Here's an example of github-training-manual being redirected to training-manual: https://githubtraining.github.io/github-training-manual

[amyschoen]

That is really cool @parkerbxyz. I'm changing my vote to your new method.

[brianamarie]

That is so awesome, @parkerbxyz! General statement in case it hasn't yet been said - @parkerbxyz, please feel empowered to do any and all of these things if you can get to it before I can! There's no reason that I need to be the person to press the buttons. 😊

The next steps in my mind for all of this are to manage the rename, move of repo, and redirect. I'm not quite sure the right order of operations as not to break things. Then, we should be good to make it public and call it "done". @parkerbxyz what do you think the right order of operations is for the rename, move of repo, and redirect?

[parkerbxyz]

One thing we’ll need to address is all of the hardcoded links to this repository that exist throughout its files:

• README.md
• CONTRIBUTING.md
• script/reset-game
• script/create-repo
• docs/GH4D/index.html
• docs/GH4DJA/index.html
• docs/ja/README.md
• docs/ja/app_Day_1_activities.md

My biggest concern is the teaching scripts. We’ll need to prepare a pull request with changes to the scripts that can be merged right after the rename to avoid disrupting any customer engagements. I think that goes for the remaining steps in the rename process; we’ll likely need to make the majority (if not all) of the changes in quick succession.

[brianamarie]

I've opened two new issues to split out the tracking of:

• Implementing redirect Configure a redirect #231
• Updating hard coded links Fix hard-coded URLs #232

I've also updated the original post to show that we need to have those PRs ready to go, and the order of operations required to push this across the finish line.

[amyschoen]

#233 opened to address #232. I opened it as a WIP PR so that we don't accidentally merge it in before we're ready.

[amyschoen]

githubtraining/githubtraining.github.io#1 opened to address #231. Both WIP PRs should be good to go when we're ready.

[amyschoen]

@brianamarie, do we have a target date yet where we're going to release this publicly?

[brianamarie]

@amyschoen I want to check with @parkerbxyz about the name and URL next week, and I'm hoping we can reach a decision that will allow us to release by the end of next week. If we decide that the URL should be something other than training.github.com, that would push the release date out a significant amount. We will know more by middle of next week.

[amyschoen]

Sounds good. Let me know the final decision on the URL once you have it. I'll likely need to tweak my WIP PR for the redirect.

[parkerbxyz]

👋 I’m back from two weeks OOO and catching up on notifications and everything else as quick as I can. Just wanted to drop a quick note here to point out that the Innersource Fundamentals Learning Lab course will need to be updated to reflect a change to the name, org, and visibility of this repository: https://github.com/parkerbxyz/innersource/pull/2#issuecomment-668866877

[amyschoen]

@parkerbxyz, if you want, I can do another WIP Pr to match the two I have staged when I’m back in front of a computer tomorrow. Any other LL classes with a direct link?

[brianamarie]

Hello 👋 and welcome back @parkerbxyz. I'm now of the opinion that we should:

• Redirect training.github.com to https://github.github.com/training/, which will link to all course repositories
  • This can be done by editing line 300 in this file to point to https://github.github.com/training/.
• Move the training manual to the github org, and rename it to github-training-manual
• Redirect links from the old manual directly to the new manual OR to https://github.github.com/training/, doesn't matter so much to me

Does that sound OK to you? If so, I think we can look at the schedule for implementation engineers and as long as it won't interfere with any trainings, let's give it a shot! What do you think?

[parkerbxyz]

Thank you for that summary, @brianamarie that's super helpful! Yes, I think we should move forward with your proposal. 😊

We'll probably need to have everyone update their .trainingmanualrc files unless the redirects will work even with API requests. 🤔

[brianamarie]

Awesome! We have decisions, and a path forward! I have created this project board to track and coordinate the release steps.

@parkerbxyz, I could use your help working with the @githubtraining/implementation-engineers for awareness and coordination of the script testing in phase two (on the project board). What do you think? Should we plan to do certain steps, especially in phase 2, on a certain day?

[brianamarie]

I realize I asked a question and am about to close this issue - @parkerbxyz I leave it up to you if you'd like to comment here, open a new issue, put something in the project board directly, or ping me 😊