From d93b26575783a41fc75fc5f42b16675596066aa3 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Mon, 26 Sep 2022 12:05:41 -0600 Subject: [PATCH 1/9] Add TODO --- TODO.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 TODO.md diff --git a/TODO.md b/TODO.md new file mode 100644 index 0000000..4bc880d --- /dev/null +++ b/TODO.md @@ -0,0 +1,79 @@ +# Make the structure/order of the materials more clear + +* How should people use these training materials? In what order? + +* How should NSIDC deliver these trainings to users? (e.g. tiny bites? 1 tutorial + 1 +discussion in a session?) + +* Should there be a way of indicating materials that you can get by without? e.g. you +don't _need_ to understand the history as a DAG but it may help some learners. + + +## Guided learning + +### Discussion: What is Git / what is Git for? + +* Who is Git for? What can Git do for me? +* Why should I use Git and not Google Docs / MS Office? +* When should I not use Git? + + +### Tutorial 1a: Intro to Git through GitHub GUI + +* Creating repositories with the GUI +* Contributing to repositories with the GUI +* Reviewing changes in GitHub CLI + +NOTE: Using GitHub GUI features first, or CLI first? + + +### Tutorial 1b: Intro to Git at the CLI / `git` commands + +* Cloning a repository from GitHub / `init` on local computer +* Adding changes, committing +* Log, diffing +* Authenticating to push +* Pushing + +NOTE: How to make "pushing" part easiest? All methods seem non-trivial and require +install of something (e.g. `openssh` not necessarily installed). [GH +docs](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/about-authentication-to-github#authenticating-with-the-command-line) +describe using GitHub CLI, using the `git` program with a Personal Access Token, using +Git Credential Manager, or using SSH keys. + + +### Discussion: Understanding Git's history with graph theory + +* Git's history is a Directed Acyclic Graph + +NOTE: Should this be before the branching/merging tutorial or after? + + +### Tutorial 2: Branching and merging at the CLI + + +### Discussion: Merge strategies + +* Fast-forward +* ... + + +### Tutorial 3: Pull requests + +* How do I open a PR? +* What do I do after I open a pull request? +* What do I do after I'm asked to review a PR? + + +### Tutorial 4: Forks / upstreams + +* What does it mean to fork? +* How to fork? +* Remotes and having multiple (e.g. `origin` and `upstream`) + + +## Reference + +* Dedicated section for workflow-focused cheat sheets? The "How-to" section currently + contains that material. +* Cheat sheets paired with tutorial contents? From 4c1f57bbc85e4458c908c950acf257000d2c85dc Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Mon, 26 Sep 2022 12:07:12 -0600 Subject: [PATCH 2/9] TODO: Move to GitHub --- TODO.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/TODO.md b/TODO.md index 4bc880d..fd65ad9 100644 --- a/TODO.md +++ b/TODO.md @@ -1,3 +1,10 @@ +# Move to GitHub + +We're shifting our focus towards GitHub in other areas. We should not confuse these +materials with BitBucket stuff. Worth noting where BitBucket does/does not offer similar +features to GitHub in materials. + + # Make the structure/order of the materials more clear * How should people use these training materials? In what order? From d0724f4d881a0e95fc0058eea08b7f228c092aa8 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Mon, 26 Sep 2022 12:18:15 -0600 Subject: [PATCH 3/9] Add thoughts about "symbology" doc --- TODO.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/TODO.md b/TODO.md index fd65ad9..25f24e2 100644 --- a/TODO.md +++ b/TODO.md @@ -84,3 +84,6 @@ NOTE: Should this be before the branching/merging tutorial or after? * Dedicated section for workflow-focused cheat sheets? The "How-to" section currently contains that material. * Cheat sheets paired with tutorial contents? +* A "style guide" or "symbology" page? Would be useful to document re-usable elements + like BitBucket/GitLab compatibility notes, authors' notes, warnings, format standards + for images/captions, etc. From 7eba4dc62d0f3ac1c48135ff9257a6a6558c1fc6 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Mon, 26 Sep 2022 12:26:16 -0600 Subject: [PATCH 4/9] Flesh out tutorial 2 --- TODO.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/TODO.md b/TODO.md index 25f24e2..6dd42ec 100644 --- a/TODO.md +++ b/TODO.md @@ -58,11 +58,16 @@ NOTE: Should this be before the branching/merging tutorial or after? ### Tutorial 2: Branching and merging at the CLI +* What do branches do for me? +* What are conflicts? How do I resolve conflicts? + ### Discussion: Merge strategies * Fast-forward -* ... +* Squash + +NOTE: Integrate this information into branching/merging tutorial? ### Tutorial 3: Pull requests From beef35db2e57ccb406b700964a36e27ac50dee77 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Mon, 26 Sep 2022 12:37:44 -0600 Subject: [PATCH 5/9] Add thoughts about landing page --- TODO.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/TODO.md b/TODO.md index 6dd42ec..de74e04 100644 --- a/TODO.md +++ b/TODO.md @@ -18,6 +18,11 @@ don't _need_ to understand the history as a DAG but it may help some learners. ## Guided learning +The most attention-drawing thing a user sees when they first load the page should be an +outline of the materials suggesting where to start and how to progress. The sidebar can +provide similar quick-navigation once the user has left the front page. + + ### Discussion: What is Git / what is Git for? * Who is Git for? What can Git do for me? From a2e0442fbbe8854d640333be44cd29ca81f27fa0 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Mon, 26 Sep 2022 13:54:37 -0600 Subject: [PATCH 6/9] Fix typo --- TODO.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/TODO.md b/TODO.md index de74e04..3376b15 100644 --- a/TODO.md +++ b/TODO.md @@ -34,7 +34,7 @@ provide similar quick-navigation once the user has left the front page. * Creating repositories with the GUI * Contributing to repositories with the GUI -* Reviewing changes in GitHub CLI +* Reviewing changes in GitHub GUI NOTE: Using GitHub GUI features first, or CLI first? From c1b4492da2d6506c785de5d584c1006bacda335e Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Mon, 26 Sep 2022 14:27:33 -0600 Subject: [PATCH 7/9] Stub out suggested learning path --- doc/home.rst | 39 +++++++++++++------ doc/index.rst | 2 +- .../01-create-a-new-repo.md | 0 .../02-create-some-content.md | 0 .../03-first-commit.md | 0 .../04-more-commits.md | 0 .../05-time-travel.md | 0 .../06-tag.md | 0 .../07-branch.md | 0 .../08-fix-main.md | 0 .../09-diff.md | 0 .../10-merge.md | 0 .../99-conclusion.md | 0 .../index.rst | 8 ++-- doc/tutorial/working-with-others/index.rst | 2 +- 15 files changed, 33 insertions(+), 18 deletions(-) rename doc/tutorial/{working-locally => 1b-intro-to-git-cli}/01-create-a-new-repo.md (100%) rename doc/tutorial/{working-locally => 1b-intro-to-git-cli}/02-create-some-content.md (100%) rename doc/tutorial/{working-locally => 1b-intro-to-git-cli}/03-first-commit.md (100%) rename doc/tutorial/{working-locally => 1b-intro-to-git-cli}/04-more-commits.md (100%) rename doc/tutorial/{working-locally => 1b-intro-to-git-cli}/05-time-travel.md (100%) rename doc/tutorial/{working-locally => 1b-intro-to-git-cli}/06-tag.md (100%) rename doc/tutorial/{working-locally => 1b-intro-to-git-cli}/07-branch.md (100%) rename doc/tutorial/{working-locally => 1b-intro-to-git-cli}/08-fix-main.md (100%) rename doc/tutorial/{working-locally => 1b-intro-to-git-cli}/09-diff.md (100%) rename doc/tutorial/{working-locally => 1b-intro-to-git-cli}/10-merge.md (100%) rename doc/tutorial/{working-locally => 1b-intro-to-git-cli}/99-conclusion.md (100%) rename doc/tutorial/{working-locally => 1b-intro-to-git-cli}/index.rst (83%) diff --git a/doc/home.rst b/doc/home.rst index f7da302..1d1895e 100644 --- a/doc/home.rst +++ b/doc/home.rst @@ -11,22 +11,37 @@ NSIDC Git Training :alt: Git logo -.. include:: what-to-expect.md - :parser: myst_parser.sphinx_ +Ensure you have the right software installed: :doc:`/reference/prerequisites` + +The following is the recommended order to tackle this material: + +* **Discussion**: :doc:`./discussion/about-git` + +* **Tutorial**: Basic usage. Choose one based on your preferred interface: + * [TODO] Intro to using Git through GitHub GUI + * :doc:`/tutorial/1b-intro-to-git-cli/index` + +* Working with others using Git: + * **Discussion**: [TODO] Understanding Git history through Graph Theory -How to use these materials --------------------------- + * **Tutorial**: [TODO] Branching and merging with Git CLI -- Ensure you have the right things installed: :doc:`/reference/prerequisites` + * **Discussion**: [TODO] Merge strategies -- Learn about what Git is for: :doc:`./discussion/about-git` + * **Tutorial**: [TODO] Pull requests -- Do the beginner tutorial: :doc:`/tutorial/working-locally/index` + * **Tutorial**: [TODO] Forks -- See the "How To"s on the left nav-bar. They can be used as a Git cheat sheet! -- Selected reference materials: - - :doc:`./reference/glossary` - - :doc:`./reference/best-practices-and-good-habits` - - :doc:`./reference/external-resources` + +* See the "How To"s on the left nav-bar. They can be used as a Git cheat sheet! + +* Selected reference materials: + * :doc:`./reference/glossary` + * :doc:`./reference/best-practices-and-good-habits` + * :doc:`./reference/external-resources` + + +.. include:: what-to-expect.md + :parser: myst_parser.sphinx_ diff --git a/doc/index.rst b/doc/index.rst index 2a0520c..69e6719 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -18,7 +18,7 @@ :numbered: :hidden: - tutorial/working-locally/index.rst + tutorial/1b-intro-to-git-cli/index.rst tutorial/working-with-others/index.rst diff --git a/doc/tutorial/working-locally/01-create-a-new-repo.md b/doc/tutorial/1b-intro-to-git-cli/01-create-a-new-repo.md similarity index 100% rename from doc/tutorial/working-locally/01-create-a-new-repo.md rename to doc/tutorial/1b-intro-to-git-cli/01-create-a-new-repo.md diff --git a/doc/tutorial/working-locally/02-create-some-content.md b/doc/tutorial/1b-intro-to-git-cli/02-create-some-content.md similarity index 100% rename from doc/tutorial/working-locally/02-create-some-content.md rename to doc/tutorial/1b-intro-to-git-cli/02-create-some-content.md diff --git a/doc/tutorial/working-locally/03-first-commit.md b/doc/tutorial/1b-intro-to-git-cli/03-first-commit.md similarity index 100% rename from doc/tutorial/working-locally/03-first-commit.md rename to doc/tutorial/1b-intro-to-git-cli/03-first-commit.md diff --git a/doc/tutorial/working-locally/04-more-commits.md b/doc/tutorial/1b-intro-to-git-cli/04-more-commits.md similarity index 100% rename from doc/tutorial/working-locally/04-more-commits.md rename to doc/tutorial/1b-intro-to-git-cli/04-more-commits.md diff --git a/doc/tutorial/working-locally/05-time-travel.md b/doc/tutorial/1b-intro-to-git-cli/05-time-travel.md similarity index 100% rename from doc/tutorial/working-locally/05-time-travel.md rename to doc/tutorial/1b-intro-to-git-cli/05-time-travel.md diff --git a/doc/tutorial/working-locally/06-tag.md b/doc/tutorial/1b-intro-to-git-cli/06-tag.md similarity index 100% rename from doc/tutorial/working-locally/06-tag.md rename to doc/tutorial/1b-intro-to-git-cli/06-tag.md diff --git a/doc/tutorial/working-locally/07-branch.md b/doc/tutorial/1b-intro-to-git-cli/07-branch.md similarity index 100% rename from doc/tutorial/working-locally/07-branch.md rename to doc/tutorial/1b-intro-to-git-cli/07-branch.md diff --git a/doc/tutorial/working-locally/08-fix-main.md b/doc/tutorial/1b-intro-to-git-cli/08-fix-main.md similarity index 100% rename from doc/tutorial/working-locally/08-fix-main.md rename to doc/tutorial/1b-intro-to-git-cli/08-fix-main.md diff --git a/doc/tutorial/working-locally/09-diff.md b/doc/tutorial/1b-intro-to-git-cli/09-diff.md similarity index 100% rename from doc/tutorial/working-locally/09-diff.md rename to doc/tutorial/1b-intro-to-git-cli/09-diff.md diff --git a/doc/tutorial/working-locally/10-merge.md b/doc/tutorial/1b-intro-to-git-cli/10-merge.md similarity index 100% rename from doc/tutorial/working-locally/10-merge.md rename to doc/tutorial/1b-intro-to-git-cli/10-merge.md diff --git a/doc/tutorial/working-locally/99-conclusion.md b/doc/tutorial/1b-intro-to-git-cli/99-conclusion.md similarity index 100% rename from doc/tutorial/working-locally/99-conclusion.md rename to doc/tutorial/1b-intro-to-git-cli/99-conclusion.md diff --git a/doc/tutorial/working-locally/index.rst b/doc/tutorial/1b-intro-to-git-cli/index.rst similarity index 83% rename from doc/tutorial/working-locally/index.rst rename to doc/tutorial/1b-intro-to-git-cli/index.rst index d9ac758..3d92362 100644 --- a/doc/tutorial/working-locally/index.rst +++ b/doc/tutorial/1b-intro-to-git-cli/index.rst @@ -1,5 +1,5 @@ -Working with Git locally -======================== +Intro to Git through CLI commands +================================= In this tutorial, you will create a Git repository, make and track several changes, create and work on independent {term}`branches`, and merge work from different @@ -15,8 +15,8 @@ files and directories in your operating system of choice. .. toctree:: - :name: Tutorial #1 steps - :caption: Tutorial #1 steps + :name: Tutorial #1b steps + :caption: Tutorial #1b steps :maxdepth: 1 :glob: diff --git a/doc/tutorial/working-with-others/index.rst b/doc/tutorial/working-with-others/index.rst index ed79903..e938ec0 100644 --- a/doc/tutorial/working-with-others/index.rst +++ b/doc/tutorial/working-with-others/index.rst @@ -16,7 +16,7 @@ commits from Bitbucket and :code:`pull` your main branch up-to-date with those c Before starting this tutorial, you should have completed the first tutorial -:doc:`/tutorial/working-locally/index`. +:doc:`/tutorial/1b-intro-to-git-cli/index`. .. note:: If you're looking for quick help with specific tasks, check out the How-Tos instead! From 8fdb2ed9d20c54866927adc1b37330d8c7ace217 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Mon, 26 Sep 2022 15:43:46 -0600 Subject: [PATCH 8/9] TODO done: move to GitHub --- TODO.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/TODO.md b/TODO.md index 3376b15..66b76ee 100644 --- a/TODO.md +++ b/TODO.md @@ -1,10 +1,3 @@ -# Move to GitHub - -We're shifting our focus towards GitHub in other areas. We should not confuse these -materials with BitBucket stuff. Worth noting where BitBucket does/does not offer similar -features to GitHub in materials. - - # Make the structure/order of the materials more clear * How should people use these training materials? In what order? From 1001d90dac3b25abb50aecaf22c7866303fdc46a Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Mon, 26 Sep 2022 18:17:06 -0600 Subject: [PATCH 9/9] Add troubleshooting of readthedocs integration --- README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index b1ea287..661d1ba 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,11 @@ After running either of these scripts, you can open the file ## Troubleshooting -TODO +### ReadTheDocs build status is not showing up in GitHub + +If you're sure, following RTD's instructions, that the relevant GitHub permissions are +correct, sometimes the only way to fix this problem is to delete and recreate the +project in RTD. ## License