From c6a07f1ae2ef9041e069efbfe383b4566b169786 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 11 Apr 2024 16:00:29 +0200 Subject: [PATCH 1/3] Now really last commit for today --- book/_toc.yml | 1 - book/workflows/branches.md | 78 ++++++++++++++++++++++++++++++--- book/workflows/collaboration.md | 23 +++++----- book/workflows/edit_book.md | 6 +-- book/workflows/merge_request.md | 2 +- book/workflows/repositories.md | 65 --------------------------- 6 files changed, 86 insertions(+), 89 deletions(-) delete mode 100644 book/workflows/repositories.md diff --git a/book/_toc.yml b/book/_toc.yml index ed4468f..6991f20 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -17,7 +17,6 @@ parts: - file: workflows/collaboration sections: - file: workflows/milestones_issues - - file: workflows/repositories - file: workflows/branches - file: workflows/edit_book - file: workflows/check_changes_online diff --git a/book/workflows/branches.md b/book/workflows/branches.md index 874caf7..8c10211 100644 --- a/book/workflows/branches.md +++ b/book/workflows/branches.md @@ -9,12 +9,11 @@ This systematic workflow guarantees that editing the book goes smoothly. The act of making a new branch from an existing one is called *branching*. Usually, you want to branch from the `main` branch, but you can of course also choose to branch from another branch. The branch from which you create a new branch is called the *source* branch. -```````{tab-set} -``````{tab-item} User type 3 +`````````{tab-set} +````````{tab-item} User type 3 `````{tab-set} ````{tab-item} In GitLab - 1. On GitLab, navigate to the repository of your project. Under the project description, you should see a menu button with a "+" in it (see {numref}`new-branch-button`). Click this button, then click on "New branch". ```{figure} ../images/gitlab-branch.png @@ -40,17 +39,80 @@ The circled menu is the branch selection menu. ``` ```` ````{tab-item} In GitHub + ```{error} To be written ``` ```` ````` +```````` + +````````{tab-item} User type 4 and 5 + +```````{tab-set} +``````{tab-item} First time opening repository + +(cloning)= +## Find source in online repository + +`````{tab-set} +````{tab-item} From GitLab + +1. On GitLab, go to the repository of your book. Click on the blue button that says "Clone" ({numref}`gitlab-clone`), and copy the link under "Clone with SSH". + +```{figure} ../images/gitlab-clone.png +:name: gitlab-clone + +The cloning menu. +``` +```` + +````{tab-item} From GitHub + +```{error} To be written +``` + +```` + +````{tab-item} From GitHub using GitHub Desktop + +```{error} To be written +``` + +```` +````` + +## Open repository locally + +`````{tab-set} +````{tab-item} With Git in VS Code +2. Open a new VS Code window. You should be greeted with a welcome page ({numref}`vscode-welcome`). On this page, click "Clone Git Repository". Alternatively, open the Source Control menu from the left side bar, and click on "Clone Repository". + +```{figure} ../images/vscode-welcome.png +:name: vscode-welcome + +The VS Code welcome screen. +``` + +3. On the top of your screen, you should get a prompt asking you for a URL. In this field, paste the link you copied from GitLab and press enter. It will ask you to choose the location of the repository. After you've chosen a location, a final prompt will show up asking if you want to open the repository. Click on "Open". + +4. You now have a local copy of the repository. +```` + +````{tab-item} With GitHub Desktop +```{error} To be written +``` + +```` +````` + `````` -``````{tab-item} User type 4 and 5 +``````{tab-item} Using previously opened repository +(pulling)= ### Obtain newest version from online repository -If you're working on your local version of the repository, you've to make sure you're working on the most up-to-date version of your branch, pull changes from the remote repository on GitHub / GitLab into your local folder. +If you're working on your local version of the repository, you've to make sure you're working on the most up-to-date version of your branch. you can do so by `pull` changes from the remote repository on GitHub / GitLab into your local folder. `````{tab-set} ````{tab-item} With Git in VS Code @@ -65,7 +127,9 @@ If you're working on your local version of the repository, you've to make sure y ```` ````` +`````` +``````` ### Create your own version `````{tab-set} @@ -92,7 +156,7 @@ The branch selection menu, where our new branch has shown up. ``` ```` ````` -`````` -``````` +```````` +````````` Now that we've created and checked out our new branch, we can start {ref}`making and committing changes `. diff --git a/book/workflows/collaboration.md b/book/workflows/collaboration.md index f90cd3d..71c8cbb 100644 --- a/book/workflows/collaboration.md +++ b/book/workflows/collaboration.md @@ -11,31 +11,30 @@ We have previously introduced the notions of using Git in the online environment The steps involved are as follows: 1. Assign task to yourself - 2. Open the files of the repository online or locally - 3. Create your own version of the book - 4. Edit the book by: + 2. Create your own version of the book + 3. Edit the book by: `````{tab-set} ````{tab-item} User type 3 - Add or make changes to a file -- Share changes with others in Git-timeline +- Add changes to Git-timeline ```` ````{tab-item} User type 4 - Eventually solve issues with combining versions - Add or make changes to a file(s) -- Select files ready to be added to Git-Timeline -- Share changes with others in Git-timeline +- Select files ready to be added to Git-timeline +- Add changes to Git-timeline - Pushing your changes ```` ````{tab-item} User type 5 - Eventually solve issues with combining versions - Add or make changes to a file(s) -- Select files ready to be added to Git-Timeline +- Select files ready to be added to Git-timeline - Check changes in book locally -- Share changes with others in Git-timeline +- Add changes to Git-timeline - If working on a repository locally: pushing your changes ```` ````` - 5. Check changes online - 6. Repeat steps 4 and 5 until you're satisfied - 7. Reviewing, (eventually repeat steps 4 and 5) and combine your version with main draft version of book - 8. Publish changes to student version of the book \ No newline at end of file + 4. Check changes online + 5. Repeat steps 3 and 4 until you're satisfied + 6. Reviewing, (eventually repeat steps 3 and 4) and combine your version with main draft version of book + 7. Publish changes to student version of the book \ No newline at end of file diff --git a/book/workflows/edit_book.md b/book/workflows/edit_book.md index b27bfec..2897ffb 100644 --- a/book/workflows/edit_book.md +++ b/book/workflows/edit_book.md @@ -16,7 +16,7 @@ or add new file by text or upload ``````{tab-item} User type 4 and 5 ### Eventually solve issues with combining versions -First make sure you update your branch so that you've the most up-to-date version. If you collaborate on this branch, you get the updates from your colleagues as well. This might lead into a merge conflict. How to solve that? +If you collaborate with colleagues on this branch, you get the updates from your colleagues as well by pulling from GitLab/GitHub. Now your branch is up-to-date. However, this might lead into a merge conflict if you and colleagues have made incompatible changes. How to solve that? `````{tab-set} ````{tab-item} With Git in VS Code @@ -39,7 +39,7 @@ First make sure you update your branch so that you've the most up-to-date versio ``` Make some changes in for example VS Code and save them. -### Select files ready to be added to Git-Timeline +### Select files ready to be added to Git-timeline `````{tab-set} ````{tab-item} With Git in VS Code @@ -76,7 +76,7 @@ build book locally and eventually startup python server... `````` ``````` -## Share changes with others in Git-timeline +## Add changes to Git-timeline ```````{tab-set} ``````{tab-item} User type 3 diff --git a/book/workflows/merge_request.md b/book/workflows/merge_request.md index e88d82c..8854f40 100644 --- a/book/workflows/merge_request.md +++ b/book/workflows/merge_request.md @@ -6,7 +6,7 @@ Merging a branch into the main branch is also good moment to let a team-member r There is a slight difference in terminology between GitLab and GitHub. GitLab uses the term *Merge* Request while GitHub uses the term *Pull* Request. Both actions refer to the merging of a branch into the main branch. ``` -We're finished with our chapter, and now it's time to include all of our commits in the `main` branch. +We're finished with our chapter, and now it's time to include all of our commits in the `main` branch. However, it's good practise to first merge `main` into our branch, so that we can see if there are any merge conflicts. Assuming that those merge conflicts aren't there, we'll now continue this example with the following merge of our branch into `main`. `````{tab-set} ````{tab-item} In GitLab diff --git a/book/workflows/repositories.md b/book/workflows/repositories.md deleted file mode 100644 index b2b46ec..0000000 --- a/book/workflows/repositories.md +++ /dev/null @@ -1,65 +0,0 @@ -# Open files - -```````{tab-set} -``````{tab-item} User type 3 -Find your file on GitLab/GitHub ... -```{error} To be written -``` - -`````` - -``````{tab-item} User type 4 and 5 - -## Find source in online repository - -`````{tab-set} -````{tab-item} From GitLab - -1. On GitLab, go to the repository of your book. Click on the blue button that says "Clone" ({numref}`gitlab-clone`), and copy the link under "Clone with SSH". - -```{figure} ../images/gitlab-clone.png -:name: gitlab-clone - -The cloning menu. -``` -```` - -````{tab-item} From GitHub -```{error} To be written -``` - -```` - -````{tab-item} From GitHub using GitHub Desktop -```{error} To be written -``` - -```` -````` - -## Open the files locally - -`````{tab-set} -````{tab-item} With Git in VS Code -2. Open a new VS Code window. You should be greeted with a welcome page ({numref}`vscode-welcome`). On this page, click "Clone Git Repository". Alternatively, open the Source Control menu from the left side bar, and click on "Clone Repository". - -```{figure} ../images/vscode-welcome.png -:name: vscode-welcome - -The VS Code welcome screen. -``` - -3. On the top of your screen, you should get a prompt asking you for a URL. In this field, paste the link you copied from GitLab and press enter. It will ask you to choose the location of the repository. After you've chosen a location, a final prompt will show up asking if you want to open the repository. Click on "Open". - -4. You now have a local copy of the repository. -```` - -````{tab-item} With GitHub Desktop -```{error} To be written -``` - -```` -````` - -`````` -``````` From 93378a1270eba00cb8db9a2d1f7e08158288d6d2 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 11 Apr 2024 16:09:20 +0200 Subject: [PATCH 2/3] Now really last one --- book/workflows/collaboration.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/book/workflows/collaboration.md b/book/workflows/collaboration.md index 71c8cbb..752c881 100644 --- a/book/workflows/collaboration.md +++ b/book/workflows/collaboration.md @@ -22,16 +22,16 @@ The steps involved are as follows: - Eventually solve issues with combining versions - Add or make changes to a file(s) - Select files ready to be added to Git-timeline -- Add changes to Git-timeline -- Pushing your changes +- Add changes to Git-timeline locally +- Add changes to GitHub/GitLab ```` ````{tab-item} User type 5 - Eventually solve issues with combining versions - Add or make changes to a file(s) - Select files ready to be added to Git-timeline - Check changes in book locally -- Add changes to Git-timeline -- If working on a repository locally: pushing your changes +- Add changes to Git-timeline locally +- Add changes to GitHub/GitLab ```` ````` 4. Check changes online From b107b47d0608cdf371dcf30e8315169c9376a146 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 11 Apr 2024 16:56:56 +0200 Subject: [PATCH 3/3] Added full steps to overview as well --- book/workflows/branches.md | 21 +++---- book/workflows/collaboration.md | 78 +++++++++++++++++++------- book/workflows/edit_book.md | 99 +++++++++++++++++++++------------ book/workflows/merge_request.md | 2 +- 4 files changed, 132 insertions(+), 68 deletions(-) diff --git a/book/workflows/branches.md b/book/workflows/branches.md index 8c10211..0386b2a 100644 --- a/book/workflows/branches.md +++ b/book/workflows/branches.md @@ -12,6 +12,8 @@ The act of making a new branch from an existing one is called *branching*. Usual `````````{tab-set} ````````{tab-item} User type 3 +**Directly create your own version (branching) or select existing version** + `````{tab-set} ````{tab-item} In GitLab 1. On GitLab, navigate to the repository of your project. Under the project description, you should see a menu button with a "+" in it (see {numref}`new-branch-button`). Click this button, then click on "New branch". @@ -30,13 +32,14 @@ Click the highlighted button to make a new branch. We're making a new branch called `chapter-2` from the `main` branch. ``` -3. You should be sent back to an overview page of your repository. In the branch selection menu (see {numref}`new-branch-repo`), it should now say `chapter-2` instead of `main`. +3. You should be sent back to an overview page of your repository. In the branch selection menu (see {numref}`new-branch-repo`), it should now say `chapter-2` instead of `main`. Here you can also select another existing branch. ```{figure} ../images/gitlab-new-branch-repo.png :name: new-branch-repo The circled menu is the branch selection menu. ``` + ```` ````{tab-item} In GitHub @@ -49,10 +52,9 @@ The circled menu is the branch selection menu. ````````{tab-item} User type 4 and 5 ```````{tab-set} -``````{tab-item} First time opening repository +``````{tab-item} First time opening (cloning) repository -(cloning)= -## Find source in online repository +**Find source link online repository** `````{tab-set} ````{tab-item} From GitLab @@ -81,7 +83,7 @@ The cloning menu. ```` ````` -## Open repository locally +**Open repository locally (cloning)** `````{tab-set} ````{tab-item} With Git in VS Code @@ -107,10 +109,9 @@ The VS Code welcome screen. `````` -``````{tab-item} Using previously opened repository +``````{tab-item} Using previously opened (cloned) repository -(pulling)= -### Obtain newest version from online repository +**Obtain newest version from online repository (pulling)** If you're working on your local version of the repository, you've to make sure you're working on the most up-to-date version of your branch. you can do so by `pull` changes from the remote repository on GitHub / GitLab into your local folder. `````{tab-set} @@ -130,7 +131,7 @@ If you're working on your local version of the repository, you've to make sure y `````` ``````` -### Create your own version +**Create your own version (branching)** `````{tab-set} ````{tab-item} With Git in VS Code @@ -148,7 +149,7 @@ Location of the branch menu. ```{figure} ../images/git-branch-selection-menu.png :name: git-branch-selection-menu -The branch selection menu, where our new branch has shown up. +The branch selection menu, where our new branch has shown up. From this menu you can also select (checkout in git terms) another existing branch. ``` ```` ````{tab-item} With GitHub Desktop diff --git a/book/workflows/collaboration.md b/book/workflows/collaboration.md index 752c881..2fbdc26 100644 --- a/book/workflows/collaboration.md +++ b/book/workflows/collaboration.md @@ -11,30 +11,68 @@ We have previously introduced the notions of using Git in the online environment The steps involved are as follows: 1. Assign task to yourself - 2. Create your own version of the book - 3. Edit the book by: + 2. Create your own version (branching) of the book by: +```````{tab-set} +``````{tab-item} User type 3 +- directly create your own version (branching) or select existing version +`````` +``````{tab-item} User type 4 and 5 `````{tab-set} -````{tab-item} User type 3 +````{tab-item} First time opening (cloning) repository +- Find source link online repository +- Open repository locally (cloning) +- Create your own version (branching) or select existing version (checkout branch) +```` +````{tab-item} Using previously opened (cloned) repository +- Obtain newest version from online repository (pulling) +- Create your own version (branching) or select existing version (checkout branch) +````` +`````` +``````` + 3. Edit the book by: +```````{tab-set} +``````{tab-item} User type 3 - Add or make changes to a file -- Add changes to Git-timeline +- Add changes to Git-timeline (committing) +`````` +``````{tab-item} User type 4 +`````{tab-set} +````{tab-item} Brand new version (branch) +- Add or make changes to file(s) +- Select files ready to be added to Git-timeline (staging) +- Add changes to Git-timeline locally (committing) +- Add changes to GitHub/GitLab (pushing) ```` -````{tab-item} User type 4 -- Eventually solve issues with combining versions -- Add or make changes to a file(s) -- Select files ready to be added to Git-timeline -- Add changes to Git-timeline locally -- Add changes to GitHub/GitLab -```` -````{tab-item} User type 5 -- Eventually solve issues with combining versions -- Add or make changes to a file(s) -- Select files ready to be added to Git-timeline -- Check changes in book locally -- Add changes to Git-timeline locally -- Add changes to GitHub/GitLab +````{tab-item} Brand new version (branch) +- Eventually solve conflicts with combining versions (merge conflicts, emerges after pulling) +- Add or make changes to file(s) +- Select files ready to be added to Git-timeline (staging) +- Add changes to Git-timeline locally (committing) +- Add changes to GitHub/GitLab (pushing) ```` ````` +`````` +``````{tab-item} User type 5 +`````{tab-set} +````{tab-item} Brand new version (branch) +- Add or make changes to file(s) +- Check changes in book locally +- Select files ready to be added to Git-timeline (staging) +- Add changes to Git-timeline locally (committing) +- Add changes to GitHub/GitLab (pushing) +```` +````{tab-item} Brand new version (branch) +- Eventually solve conflicts with combining versions (merge conflicts, emerges after pulling) +- Add or make changes to file(s) +- Check changes in book locally +- Select files ready to be added to Git-timeline (staging) +- Add changes to Git-timeline locally (committing) +- Add changes to GitHub/GitLab (pushing) +```` +````` +`````` +``````` 4. Check changes online 5. Repeat steps 3 and 4 until you're satisfied - 6. Reviewing, (eventually repeat steps 3 and 4) and combine your version with main draft version of book - 7. Publish changes to student version of the book \ No newline at end of file + 6. Reviewing (merge request), (eventually repeat steps 3 and 4) and combine (merging) your version with main draft version of book + 7. Publish changes to student version of the book (merge request) \ No newline at end of file diff --git a/book/workflows/edit_book.md b/book/workflows/edit_book.md index 2897ffb..7711212 100644 --- a/book/workflows/edit_book.md +++ b/book/workflows/edit_book.md @@ -2,9 +2,10 @@ Suppose we are writing a new chapter, or are updating an existing chapter for our Jupyter Book. We've created a new branch on which we are going to make the changes. -## Add or make changes to a file(s) -```````{tab-set} -``````{tab-item} User type 3 +`````````{tab-set} +````````{tab-item} User type 3 + +**Add or make changes to a file** Make changes to file in text editor... or add new file by text or upload @@ -12,11 +13,19 @@ or add new file by text or upload ```{error} To be written ``` +```````` +````````{tab-item} User type 4 and 5 + +```````{tab-set} +``````{tab-item} Brand new version (branch) + +If your branch was build from main, you've the most up-to-date version. So you can just continue with the next step. Next time you come here things might be different! `````` -``````{tab-item} User type 4 and 5 +``````{tab-item} Existing version (branch) -### Eventually solve issues with combining versions -If you collaborate with colleagues on this branch, you get the updates from your colleagues as well by pulling from GitLab/GitHub. Now your branch is up-to-date. However, this might lead into a merge conflict if you and colleagues have made incompatible changes. How to solve that? +**Eventually solve conflicts with combining versions (merge conflicts, emerges after pulling)** + +If you collaborate with colleagues on this branch, you can get the updates from your colleagues as well by pulling from GitLab/GitHub. Now your branch is up-to-date. However, this might lead into a merge conflict if you and colleagues have made incompatible changes. How to solve that? `````{tab-set} ````{tab-item} With Git in VS Code @@ -33,38 +42,20 @@ If you collaborate with colleagues on this branch, you get the updates from your ```` ````` -### Make actual changes - -```{error} To be written -``` -Make some changes in for example VS Code and save them. - -### Select files ready to be added to Git-timeline - -`````{tab-set} -````{tab-item} With Git in VS Code - -For demonstration purposes, we have created a new Markdown file called `new-chapter.md`, which we want to add to the book. Since this is a new file, Git has no knowledge about its existence yet. I.e., the file is *untracked*. To add new files to our repository, we need to *stage* and *commit* them. To do this, open the Source Control menu in the left side bar. Our new file should appear in this menu: - -```{figure} ../images/git-new-file.png - -The new file appears in the Source Control menu. -``` - -Notice that there is a green letter U placed besides the file, meaning that our file is untracked. To add a file to the *staging area*, click on the + that appears when you hover over the file. -```` -````{tab-item} With GitHub Desktop -The staging GitHub Desktop assumes you want to stage all files. You can unselect some of them (unstaging them)... -```{error} To be written -``` - -```` -````` - `````` ``````` -## Check changes in book locally +**Add or make changes to file(s)** + +```{error} To be written +``` +Make some changes in for example VS Code and save them. + + +```````` +````````` + +**Check changes in book locally** ```````{tab-set} ``````{tab-item} User type 3 and 4 Not possible, unless you want to be a user type 5. Otherwise you'll see your changes later on online. @@ -76,17 +67,22 @@ build book locally and eventually startup python server... `````` ``````` -## Add changes to Git-timeline ```````{tab-set} ``````{tab-item} User type 3 `````{tab-set} ````{tab-item} In GitLab + +**Add changes to Git-timeline (committing)** + click commit in single text editor ... ```{error} To be written ``` ```` ````{tab-item} In GitHub + +**Add changes to Git-timeline (committing)** + click commit in single text editor ... ```{error} To be written ``` @@ -95,10 +91,23 @@ click commit in single text editor ... `````` ``````{tab-item} User type 4 and 5 -Now we're going the share our changes in the Git-timeline with a *commit* and to *push* our changes to the *remote* repository (the one that is on the TU Delft GitLab/GitHub), so that others can see our changes and interact with them. `````{tab-set} ````{tab-item} Using Git in VS Code + +**Select files ready to be added to Git-timeline (staging)** + +For demonstration purposes, we have created a new Markdown file called `new-chapter.md`, which we want to add to the book. Since this is a new file, Git has no knowledge about its existence yet. I.e., the file is *untracked*. To add new files to our repository, we need to *stage* and *commit* them. To do this, open the Source Control menu in the left side bar. Our new file should appear in this menu: + +```{figure} ../images/git-new-file.png + +The new file appears in the Source Control menu. +``` + +Notice that there is a green letter U placed besides the file, meaning that our file is untracked. To add a file to the *staging area*, click on the + that appears when you hover over the file. + +**Add changes to Git-timeline locally (committing)** + Next, in the field that says "Message", write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, the menu should now look something like this: ```{figure} ../images/git-file-added.png @@ -106,6 +115,8 @@ Next, in the field that says "Message", write a short description of the changes The new file has been staged, and we've written a Commit Message. ``` +**Add changes to GitHub/GitLab (pushing)** + Now, we are ready to add the changes to the repository. This is done by *committing* the staged changes. To do this, simply press the big, blue "Commit" button in the Source Control menu. In the bottom left corner, next to the branch name, click the "Synchronize Changes" button (the one that looks like this: 🔄, highlighted in the image below) to push the changes to GitLab. @@ -116,6 +127,20 @@ After committing, click the 🔄 button to push our changes to the remote reposi ```` ````{tab-item} Using GitHub Desktop + +**Select files ready to be added to Git-timeline (staging)** + +The staging GitHub Desktop assumes you want to stage all files. You can unselect some of them (unstaging them)... +```{error} To be written +``` + +**Add changes to Git-timeline locally (committing)** + +```{error} To be written +``` + +**Add changes to GitHub/GitLab (pushing)** + ```{error} To be written ``` diff --git a/book/workflows/merge_request.md b/book/workflows/merge_request.md index 8854f40..3b80377 100644 --- a/book/workflows/merge_request.md +++ b/book/workflows/merge_request.md @@ -6,7 +6,7 @@ Merging a branch into the main branch is also good moment to let a team-member r There is a slight difference in terminology between GitLab and GitHub. GitLab uses the term *Merge* Request while GitHub uses the term *Pull* Request. Both actions refer to the merging of a branch into the main branch. ``` -We're finished with our chapter, and now it's time to include all of our commits in the `main` branch. However, it's good practise to first merge `main` into our branch, so that we can see if there are any merge conflicts. Assuming that those merge conflicts aren't there, we'll now continue this example with the following merge of our branch into `main`. +We're finished with our chapter, and now it's time to include all of our commits in the `main` branch. However, it's good practise to first merge `main` into our branch, so that we can see if there are any merge conflicts. Assuming that those merge conflicts are solved before, we'll now continue this example with the following merge of our branch into `main`. `````{tab-set} ````{tab-item} In GitLab