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 diff --git a/TODO.md b/TODO.md new file mode 100644 index 0000000..66b76ee --- /dev/null +++ b/TODO.md @@ -0,0 +1,92 @@ +# 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 + +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? +* 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 GUI + +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 + +* 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 + +* 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? +* 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. 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!