compare the texts of Constitutions around the world.. Including using diffs (just like git does) to understand changes. e.g., changes in Algeria’s constitution (diff 1989 2020). “Constitute was developed by the Comparative Constitutions Project at the University of Texas at Austin and the University of Chicago, directed by Zachary Elkins and Tom Ginsburg.”
-
-
9.2 Exercise: Note-taking via google docs
+
+
8.4 Exercise: Note-taking via google docs
You will be placed into groups of 3 (not sitting near each other):
Create a google doc and share it
@@ -401,7 +400,6 @@
4.3 What is “source”?
-
+
diff --git a/docs/current/search.json b/docs/current/search.json
index 5a2de76..fbc3ff6 100644
--- a/docs/current/search.json
+++ b/docs/current/search.json
@@ -402,12 +402,23 @@
"8Governance"
]
},
+ {
+ "objectID": "insights/governance.html#how-do-open-source-projects-make-decisions",
+ "href": "insights/governance.html#how-do-open-source-projects-make-decisions",
+ "title": "8 Governance",
+ "section": "8.2 How do open source projects make decisions?",
+ "text": "8.2 How do open source projects make decisions?\nWorking in a project requires many decisions, e.g.,:\n\nChoosing a project name\nDeciding whether to add a color scheme\nChoosing whether to use UK or US spelling rules\nDeciding when to release a new version\n\nProjects have a wide range of ways that they make these decisions (including avoiding having to make decisions!). We call these “governance models”.\nOutside open source there are also many governance models, including very well known ones:\n\nDemocracy (direct and representative)\nDictatorship\nCorporate hierarchy\nConsensus",
+ "crumbs": [
+ "Insights",
+ "8Governance"
+ ]
+ },
{
"objectID": "insights/governance.html#recent-innovations-in-decision-making",
"href": "insights/governance.html#recent-innovations-in-decision-making",
"title": "8 Governance",
- "section": "9.1 Recent innovations in decision making",
- "text": "9.1 Recent innovations in decision making\nWhile we may think the process of creating new models of decision making in groups has stopped or slowed, recent innovations abound:\n\nOccupy Wall Street Hand signals used during discussion at https://en.wikipedia.org/wiki/General_assembly_(Occupy_movement)\n\n\n\nNew constitutions written by countries. e.g., Chile’s new constitution process 2022\n\nStudents and faculty at the University of Texas are involved with a project (and software) to compare the texts of Constitutions around the world.. Including using diffs (just like git does) to understand changes. e.g., changes in Algeria’s constitution (diff 1989 2020). “Constitute was developed by the Comparative Constitutions Project at the University of Texas at Austin and the University of Chicago, directed by Zachary Elkins and Tom Ginsburg.”",
+ "section": "8.3 Recent innovations in decision making",
+ "text": "8.3 Recent innovations in decision making\nWhile we may think the process of creating new models of decision making in groups has stopped or slowed, recent innovations abound:\n\nOccupy Wall Street Hand signals used during discussion at https://en.wikipedia.org/wiki/General_assembly_(Occupy_movement)\n\n\n\nNew constitutions written by countries. e.g., Chile’s new constitution process 2022\n\nStudents and faculty at the University of Texas are involved with a project (and software) to compare the texts of Constitutions around the world.. Including using diffs (just like git does) to understand changes. e.g., changes in Algeria’s constitution (diff 1989 2020). “Constitute was developed by the Comparative Constitutions Project at the University of Texas at Austin and the University of Chicago, directed by Zachary Elkins and Tom Ginsburg.”",
"crumbs": [
"Insights",
"8Governance"
@@ -417,8 +428,8 @@
"objectID": "insights/governance.html#exercise-note-taking-via-google-docs",
"href": "insights/governance.html#exercise-note-taking-via-google-docs",
"title": "8 Governance",
- "section": "9.2 Exercise: Note-taking via google docs",
- "text": "9.2 Exercise: Note-taking via google docs\nYou will be placed into groups of 3 (not sitting near each other):\n\nCreate a google doc and share it\n\nFor next 2 steps follow two rules:\n\nYou may not talk to each other\nYou may not write instructions to each other in the Google doc (or elsewhere, e.g., chat)\n\n\nWorking in this mode: produce a 2 page summary of:\n\nRoss Gardler & Gabriel Hanganu. (2013). Governance models. OSS-Watch.ac.uk. http://oss-watch.ac.uk/resources/governancemodels\n\nContinuing to work in this mode: include within your text three comparisons with the work linked below (comparisons could include that the work agrees, disagrees, extends, adds example, etc.):\n\nKarl Fogel. (2020). Chapter 8: Managing Participants. In “Producing OSS” Book. https://producingoss.com/en/managing-participants.html\n\nCreate a final heading, “Reflections on working without talking”. Move to sit next to each other. Ironically, you can talk to each other as you write down at least 3 bullet points about your experience doing this note-taking.",
+ "section": "8.4 Exercise: Note-taking via google docs",
+ "text": "8.4 Exercise: Note-taking via google docs\nYou will be placed into groups of 3 (not sitting near each other):\n\nCreate a google doc and share it\n\nFor next 2 steps follow two rules:\n\nYou may not talk to each other\nYou may not write instructions to each other in the Google doc (or elsewhere, e.g., chat)\n\n\nWorking in this mode: produce a 2 page summary of:\n\nRoss Gardler & Gabriel Hanganu. (2013). Governance models. OSS-Watch.ac.uk. http://oss-watch.ac.uk/resources/governancemodels\n\nContinuing to work in this mode: include within your text three comparisons with the work linked below (comparisons could include that the work agrees, disagrees, extends, adds example, etc.):\n\nKarl Fogel. (2020). Chapter 8: Managing Participants. In “Producing OSS” Book. https://producingoss.com/en/managing-participants.html\n\nCreate a final heading, “Reflections on working without talking”. Move to sit next to each other. Ironically, you can talk to each other as you write down at least 3 bullet points about your experience doing this note-taking.",
"crumbs": [
"Insights",
"8Governance"
@@ -693,7 +704,7 @@
"href": "skills/branching.html",
"title": "15 Local branching with Git",
"section": "",
- "text": "15.1 Warmup exercise\nUse the terminal to create a new git repo so that when you run our git viz command you see this output:\nRemember that for a new git repo you may have to provide a username and email address. These commands will help (you don’t need to change the names but can if you want)\nThe git viz command is long, so you can create a short cut for it on the commandline:\nThen you will only need to type:",
+ "text": "15.1 Warmup exercise\nUse the terminal to create a new git repo so that when you run our git viz command you see this output:\nRemember that for a new git repo you may have to provide a username and email address. These commands will help (you don’t need to change the names but can if you want)",
"crumbs": [
"Skills",
"15Local branching with Git"
@@ -704,7 +715,7 @@
"href": "skills/branching.html#warmup-exercise",
"title": "15 Local branching with Git",
"section": "",
- "text": "Some weird git errors can come when we accidentally have git repos inside other git repos. In particular this can happen if we accidentally make our home folder into a git repo. See discussion and fixes in Section A.2 You can find additional help in the FAQ section: Appendix A\n\n\nbranching_warmup % git log --oneline --abbrev-commit --all --graph --decorate --color \n* 50590c5 (HEAD -> main) Wednesday\n* 39f89db Tuesday\n* 1b2162e Monday\n\ngit config --global user.email \"you@example.com\"\ngit config --global user.name \"Your Name\"\n\ngit config alias.viz 'log --oneline --abbrev-commit --all --graph --decorate --color'\n\ngit viz",
+ "text": "Some weird git errors can come when we accidentally have git repos inside other git repos. In particular this can happen if we accidentally make our home folder into a git repo. See discussion and fixes in Section A.2 You can find additional help in the FAQ section: Appendix A\n\n\nbranching_warmup % git viz\n* 50590c5 (HEAD -> main) Wednesday\n* 39f89db Tuesday\n* 1b2162e Monday\n\ngit config --global user.email \"you@example.com\"\ngit config --global user.name \"Your Name\"",
"crumbs": [
"Skills",
"15Local branching with Git"
@@ -715,7 +726,7 @@
"href": "skills/branching.html#branching-with-local-git",
"title": "15 Local branching with Git",
"section": "15.2 Branching with local git",
- "text": "15.2 Branching with local git\nBranching (and merging) is a useful way to keep different tasks organized and synchronized, even when working locally with git. Below we will work through a scenario for git branching, showing the commands and two different vizualizations. Eventually branching becomes a key part of working with github and shared repositories, but it is useful to approach it separately first.\n\n15.2.1 A scenario\nImagine you are running a coffee roaster. You have code that produces a daily report that is emailed to your team. Each day the point of sale system makes new data available. Each night your computer executes a script (report_script.Rmd) to access the data, create, and email the report.\nWe are going to manage a situation where we want to:\n\nexperiment and break things\nkeep things running\n\nIt is very hard to do these things at the same time. Branching helps us to do this.\nOne option might be to maintain different versions of files using different file names (report_script.Rmd and new_report_script.Rmd. This becomes very messy when we have many files and folders involved (/images and /new_images???). This is even worse when we have multiple experiments and attempts going on in parallel and entirely hopeless when we move online and are working with groups of people.\nRecall, though, that git enables us to “swap out” our working directory. Until now we’ve kept this linear, each new version added after the last. But branching enables us to keep parallel lines of commits (as though we had two lines of trays with on our paper plane repository table).\n\n\n15.2.2 Coordinating new work while keeping old work running\nCurrently the report is pretty simple, it’s just a table of sales divided up between in-store and online. Each day’s sales are added as a new row in the table.\ncd ~\nmkdir scratch_branching\ncd scratch_branching\ngit init\nInitialized empty Git repository in scratch_branching/.git/\nWe can now add the reporting script and the data for monday. To simulate editing a file using an editor we can use some fancy syntax so you can copy and paste it.\necho \"# Initial code for table report\" >> reporting_script.Rmd\ngit add reporting_script.Rmd\ngit commit -m \"starting setup\"\n[master (root-commit) 24bcda4] starting setup\n 2 files changed, 0 insertions(+), 0 deletions(-)\n create mode 100644 data_monday.csv\n create mode 100644 reporting_script.Rmd\n\n\n\n\nThe scripts runs normally on Monday night.\nOne Tuesday morning you decide that the data would be better presented as a chart. You have some ideas but rightly decide it will take more than a day or two to get that working.\nIn the meantime you still have to produce the report. So you create a branch called towards_chart and begin working there, leaving the master branch untouched to produce the Tuesday night report.\ngit branch towards_chart\ngit checkout towards_chart\nAgain we can simulate editing the file.\necho \"# Work towards charts\" >> reporting_script.Rmd \ngit status\nOn branch towards_chart\nChanges not staged for commit:\n (use \"git add <file>...\" to update what will be committed)\n (use \"git restore <file>...\" to discard changes in working directory)\n modified: reporting_script.Rmd\n\nno changes added to commit (use \"git add\" and/or \"git commit -a\")\ngit add reporting_script.Rmd\ngit commit -m \"Worked towards charts\"\n[towards_chart acc3f42] Worked towards charts\n 1 file changed, 1 insertion(+)\nOn Tuesday you see that the report ran fine (using the code in master) and you continue to work on the charts.\necho \"# More work towards charts\" >> reporting_script.Rmd \ngit add reporting_script.Rmd\ngit commit -m \"More work towards charts\"\n[towards_chart acc3f42] Worked towards charts\n 1 file changed, 1 insertion(+)\nOn Wednesday morning, though, you get an error from your reporting script. The online sales system updated and the data files now include a new column saying whether a sale was cash or credit. You know how to get things working again, but you still aren’t ready to launch your chart system. You don’t want to wait until your chart work is finished to get the report going again.\nSo you switch to master, edit the reporting file to handle the new column, then add and commit the change.\ngit checkout master\nSwitched to branch 'master'\nNow we are back on the master branch and we won’t see our work towards the charts at all. So over on the towards_chart branch we can work away without upsetting the working code on master.\nCheck the current content of the script (will show nothing about charts)\ncat reporting_script.Rmd\nInitial code for table report\nSo now we can, without involving our work towards the chart, make the bugfix on master.\necho \"# Fix to match new data format\" >> reporting_script.Rmd\ngit add reporting_script.Rmd\ngit commit -m \"A fix to match new data format\"\nNow if we run our git viz command:\ngit log --oneline --abbrev-commit --all --graph --decorate --color\nwe will see our branching starting to show up:\njlh5498@educcomp04:~/scratch_branching$ git log --oneline --abbrev-commit --all --graph --decorate --color\n* 48afd7c (HEAD -> master) A fix to match new data format\n| * 5c7fc76 (towards_chart) More work towards charts\n| * c72d745 Worked towards charts\n|/ \n* c434df6 starting setup\nHappily the report runs fine on Wednesday night.\nThursday morning you switch back to the towards_chart branch and are pleased to get things working.\ngit checkout towards_chart\necho \"# Code to finalize the charts\" >> reporting_script.Rmd \ngit add reporting_script.Rmd\ngit commit -m \"Finished up the charts\"\nYou are ready to add the chart into the report by moving the code to the master branch.\nBut if you just merge the code back to master you may find that the code for the chart doesn’t work with the change to handle the updated data files. So you may have some merging to do. But you don’t know if you can get that done before the report has to run, and you don’t want to get caught fiddling with master because if the report tries to run you could end up with nothing going out that night.\nSo you first merge master over to your towards_chart branch, and ensure that things work well and the two pieces of work done in parallel work well together (charts and dealing with the new column).\nFirst confirm which branch you are in, this command lists the branches and the one highlighted with the * is the current branch. git status can also show you.\ngit branch -v \ngit branch -v\n master 576bc90 A fix to match new data format\n* towards_chart bef7b72 Finished up the charts\nThen merge over the master branch into the towards_chart branch.\ngit merge master\nAuto-merging reporting_script.Rmd\nCONFLICT (content): Merge conflict in reporting_script.Rmd\nAutomatic merge failed; fix conflicts and then commit the result.\nAh, good thing we did this on the branch because we do end up with a conflict. Git can resolve some conflicts but not all. Git shows conflicts by adding special lines of text into the file (using >>>>>> and <<<<< as indicators. To resolve them we remove those lines and leve the file the way we want it to be.\n# Initial code for table report\n<<<<<<< HEAD\n# Work towards charts\n# More work towards charts\n# Code to finalize the charts\n=======\n# Fix to match new data format\n>>>>>>> master\nThe parts separated by ======== show edits that conflict. Looking at this we can see that we want all the lines, so we edit the file to show:\n# Initial code for table report\n# Fix to match new data format\n# Work towards charts\n# More work towards charts\n# Code to finalize the charts\nNow we can save that file. Git knows that we are fixing a conflict, so git status shows:\nOn branch towards_chart\nYou have unmerged paths.\n (fix conflicts and run \"git commit\")\n (use \"git merge --abort\" to abort the merge)\n\nUnmerged paths:\n (use \"git add <file>...\" to mark resolution)\n both modified: reporting_script.Rmd\n\nno changes added to commit (use \"git add\" and/or \"git commit -a\")\nAnd now we can add and commit to finish the merge.\ngit add reporting_script.Rmd\ngit commit -m \"merged bug fix with charts code\"\n[towards_chart e420a05] merged bug fix with charts code\n(Git can only flag syntactical conflicts, not semantic conflicts, so one would also try running some test reports to make sure things are all working).\nSo once you’ve resolved all issues, then you can merge the towards_chart branch back to master, signalling that you are ready to launch your new report with charts.\ngit checkout master\ngit merge towards_chart\nSwitched to branch 'master'\nUpdating 576bc90..e420a05\nFast-forward\n reporting_script.Rmd | 3 +++\n 1 file changed, 3 insertions(+)\nFinally we can visualize this branching, editing, and merging in two ways. First we can use this handy command to see a visualization in the command line.\ngit log --oneline --abbrev-commit --all --graph --decorate --color \nWhich will show us this (using an image here because the color doesn’t copy):\n\nWe can also see this visually using learngitbranching, see the short video below.",
+ "text": "15.2 Branching with local git\nBranching (and merging) is a useful way to keep different tasks organized and synchronized, even when working locally with git. Below we will work through a scenario for git branching, showing the commands and two different vizualizations. Eventually branching becomes a key part of working with github and shared repositories, but it is useful to approach it separately first.\n\n15.2.1 A scenario\nImagine you are running a coffee roaster. You have code that produces a daily report that is emailed to your team. Each day the point of sale system makes new data available. Each night your computer executes a script (report_script.Rmd) to access the data, create, and email the report.\nWe are going to manage a situation where we want to:\n\nexperiment and break things\nkeep things running\n\nIt is very hard to do these things at the same time. Branching helps us to do this.\nOne option might be to maintain different versions of files using different file names (report_script.Rmd and new_report_script.Rmd. This becomes very messy when we have many files and folders involved (/images and /new_images???). This is even worse when we have multiple experiments and attempts going on in parallel and entirely hopeless when we move online and are working with groups of people.\nRecall, though, that git enables us to “swap out” our working directory. Until now we’ve kept this linear, each new version added after the last. But branching enables us to keep parallel lines of commits (as though we had two lines of trays with on our paper plane repository table).\n\n\n15.2.2 Coordinating new work while keeping old work running\nCurrently the report is pretty simple, it’s just a table of sales divided up between in-store and online. Each day’s sales are added as a new row in the table.\ncd ~\nmkdir scratch_branching\ncd scratch_branching\ngit init\nInitialized empty Git repository in scratch_branching/.git/\nWe can now add the reporting script and the data for monday. To simulate editing a file using an editor we can use some fancy syntax so you can copy and paste it.\necho \"# Initial code for table report\" >> reporting_script.Rmd\ngit add reporting_script.Rmd\ngit commit -m \"starting setup\"\n[master (root-commit) 24bcda4] starting setup\n 2 files changed, 0 insertions(+), 0 deletions(-)\n create mode 100644 data_monday.csv\n create mode 100644 reporting_script.Rmd\n\n\n\n\nThe scripts runs normally on Monday night.\nOne Tuesday morning you decide that the data would be better presented as a chart. You have some ideas but rightly decide it will take more than a day or two to get that working.\nIn the meantime you still have to produce the report. So you create a branch called towards_chart and begin working there, leaving the master branch untouched to produce the Tuesday night report.\ngit branch towards_chart\ngit checkout towards_chart\nAgain we can simulate editing the file.\necho \"# Work towards charts\" >> reporting_script.Rmd \ngit status\nOn branch towards_chart\nChanges not staged for commit:\n (use \"git add <file>...\" to update what will be committed)\n (use \"git restore <file>...\" to discard changes in working directory)\n modified: reporting_script.Rmd\n\nno changes added to commit (use \"git add\" and/or \"git commit -a\")\ngit add reporting_script.Rmd\ngit commit -m \"Worked towards charts\"\n[towards_chart acc3f42] Worked towards charts\n 1 file changed, 1 insertion(+)\nOn Tuesday you see that the report ran fine (using the code in master) and you continue to work on the charts.\necho \"# More work towards charts\" >> reporting_script.Rmd \ngit add reporting_script.Rmd\ngit commit -m \"More work towards charts\"\n[towards_chart acc3f42] Worked towards charts\n 1 file changed, 1 insertion(+)\nOn Wednesday morning, though, you get an error from your reporting script. The online sales system updated and the data files now include a new column saying whether a sale was cash or credit. You know how to get things working again, but you still aren’t ready to launch your chart system. You don’t want to wait until your chart work is finished to get the report going again.\nSo you switch to master, edit the reporting file to handle the new column, then add and commit the change.\ngit checkout master\nSwitched to branch 'master'\nNow we are back on the master branch and we won’t see our work towards the charts at all. So over on the towards_chart branch we can work away without upsetting the working code on master.\nCheck the current content of the script (will show nothing about charts)\ncat reporting_script.Rmd\nInitial code for table report\nSo now we can, without involving our work towards the chart, make the bugfix on master.\necho \"# Fix to match new data format\" >> reporting_script.Rmd\ngit add reporting_script.Rmd\ngit commit -m \"A fix to match new data format\"\nNow if we run our git viz command:\ngit viz\nwe will see our branching starting to show up:\njlh5498@educcomp04:~/scratch_branching$ git viz\n* 48afd7c (HEAD -> master) A fix to match new data format\n| * 5c7fc76 (towards_chart) More work towards charts\n| * c72d745 Worked towards charts\n|/ \n* c434df6 starting setup\nHappily the report runs fine on Wednesday night.\nThursday morning you switch back to the towards_chart branch and are pleased to get things working.\ngit checkout towards_chart\necho \"# Code to finalize the charts\" >> reporting_script.Rmd \ngit add reporting_script.Rmd\ngit commit -m \"Finished up the charts\"\nYou are ready to add the chart into the report by moving the code to the master branch.\nBut if you just merge the code back to master you may find that the code for the chart doesn’t work with the change to handle the updated data files. So you may have some merging to do. But you don’t know if you can get that done before the report has to run, and you don’t want to get caught fiddling with master because if the report tries to run you could end up with nothing going out that night.\nSo you first merge master over to your towards_chart branch, and ensure that things work well and the two pieces of work done in parallel work well together (charts and dealing with the new column).\nFirst confirm which branch you are in, this command lists the branches and the one highlighted with the * is the current branch. git status can also show you.\ngit branch -v \ngit branch -v\n master 576bc90 A fix to match new data format\n* towards_chart bef7b72 Finished up the charts\nThen merge over the master branch into the towards_chart branch.\ngit merge master\nAuto-merging reporting_script.Rmd\nCONFLICT (content): Merge conflict in reporting_script.Rmd\nAutomatic merge failed; fix conflicts and then commit the result.\nAh, good thing we did this on the branch because we do end up with a conflict. Git can resolve some conflicts but not all. Git shows conflicts by adding special lines of text into the file (using >>>>>> and <<<<< as indicators. To resolve them we remove those lines and leve the file the way we want it to be.\n# Initial code for table report\n<<<<<<< HEAD\n# Work towards charts\n# More work towards charts\n# Code to finalize the charts\n=======\n# Fix to match new data format\n>>>>>>> master\nThe parts separated by ======== show edits that conflict. Looking at this we can see that we want all the lines, so we edit the file to show:\n# Initial code for table report\n# Fix to match new data format\n# Work towards charts\n# More work towards charts\n# Code to finalize the charts\nNow we can save that file. Git knows that we are fixing a conflict, so git status shows:\nOn branch towards_chart\nYou have unmerged paths.\n (fix conflicts and run \"git commit\")\n (use \"git merge --abort\" to abort the merge)\n\nUnmerged paths:\n (use \"git add <file>...\" to mark resolution)\n both modified: reporting_script.Rmd\n\nno changes added to commit (use \"git add\" and/or \"git commit -a\")\nAnd now we can add and commit to finish the merge.\ngit add reporting_script.Rmd\ngit commit -m \"merged bug fix with charts code\"\n[towards_chart e420a05] merged bug fix with charts code\n(Git can only flag syntactical conflicts, not semantic conflicts, so one would also try running some test reports to make sure things are all working).\nSo once you’ve resolved all issues, then you can merge the towards_chart branch back to master, signalling that you are ready to launch your new report with charts.\ngit checkout master\ngit merge towards_chart\nSwitched to branch 'master'\nUpdating 576bc90..e420a05\nFast-forward\n reporting_script.Rmd | 3 +++\n 1 file changed, 3 insertions(+)\nFinally we can visualize this branching, editing, and merging in two ways. First we can use this handy command to see a visualization in the command line.\ngit viz\nWhich will show us this (using an image here because the color doesn’t copy):\n\nWe can also see this visually using learngitbranching, see the short video below.",
"crumbs": [
"Skills",
"15Local branching with Git"
@@ -953,11 +964,33 @@
]
},
{
- "objectID": "skills/git_cherrypick_split_pr.html#split-before-submit",
- "href": "skills/git_cherrypick_split_pr.html#split-before-submit",
+ "objectID": "skills/git_cherrypick_split_pr.html#learngitbranching-exercise",
+ "href": "skills/git_cherrypick_split_pr.html#learngitbranching-exercise",
"title": "18 Split a Pull Request",
- "section": "",
- "text": "18.1.1 LearnGitBranching exercise\nWe can see an example of the overall workflow for splitting a PR using the LearnGitBranching Visualizer, I have created a level called Split Pull Request.\n\n\n18.1.2 Cherry-pick via commandline git\nYou can see a situation like this in this repo on GitHub. Bring that to your working space with:\ncd ~\ngit clone https://github.com/jameshowison/i320d-needs-split.git\ncd i320d-needs-split\nIf you then run our gitviz command (see Section A.3 for how to set up a short cut for that)\nYou will see both our apple and orange edits all together on the main branch.\njlh5498@educcomp04:~/github_repos/i320d-needs-split$ git log --oneline --abbrev-commit --all --graph --decorate --color\n* c70df5a (HEAD -> main) orange2\n* 423ad05 apple2\n* 4f1fe99 orange1\n* 91abdfb apple1\n* 8e35b12 branch here\n* ea4d580 main1\n* 252ff3f Initial commit\nWe eventually want this to look like our first graph above, with two new branches (apple_branch and orange_branch):\njlh5498@educcomp04:~/github_repos/i320d-needs-split$ git log --oneline --abbrev-commit --all --graph --decorate --color\n* 09d5482 (HEAD -> orange_branch) orange2\n* 2137500 orange1\n| * c8fd64d (apple_branch) apple2\n| * 1a5ac49 apple1\n|/ \n* 158f2c4 (main) branch here\n* 96d65c3 main2\n* 7036c11 main 1\n* 252ff3f Initial commit\nTo get there we will take three steps:\n\nCreate a new branch, specifying the starting point\nMove the relevant commits to the new branch\nPush to the fork, create a new pull request\n\ngit checkout -b apple_branch 8e35b12\nThe 8e35b12 here is the commit id of the point at which we want the branch to start. Until now when we’ve created a branch we have done so while sitting at HEAD but git allows us to create a branch back in time. Git does this by adding metadata to the earlier commit (labeling it with a branch label).\nThen we can move the commits using git cherry-pick. Note that this doesn’t move them from the main branch, but creates new commits with the same content. This is very much like copying files from one directory into another directory (except we are moving commits from a branch to another branch).\ngit cherry-pick 91abdfb 423ad05\nAgain the strings 91abdfb and 423ad05 identify specific commits. We can provide a list (like above), just one, and it is also possible to provide a range if you want a full sequence of commits.\nAfter the cherry-pick we see:\njlh5498@educcomp04:~/github_repos/i320d-needs-split$ git cherry-pick 91abdfb 423ad05\n[apple_branch 9ca623a] apple1\n Date: Wed Mar 1 15:31:38 2023 -0600\n 1 file changed, 1 insertion(+)\n[apple_branch 2b82f41] apple2\n Date: Wed Mar 1 15:31:38 2023 -0600\n 1 file changed, 1 insertion(+)\njlh5498@educcomp04:~/github_repos/i320d-needs-split$ git log --oneline --abbrev-commit --all --graph --decorate --color\n* 2b82f41 (HEAD -> apple_branch) apple2\n* 9ca623a apple1\n| * c70df5a (origin/main, origin/HEAD, main) orange2\n| * 423ad05 apple2\n| * 4f1fe99 orange1\n| * 91abdfb apple1\n|/ \n* 8e35b12 branch here\n* ea4d580 main1\n* 252ff3f Initial commit\nWe can then use git push as normal to push the apple_branch up to the fork and make a pull request.\n\n\n\n\n\n\nNote\n\n\n\nMoving around commits using cherry-pick shows us why it is so important to understand commits as full copies of the state of the working directory, as full snapshots of our files. If commits were just the changes (just a bunch of diffs) then we would have to apply them in the order they were created, otherwise we’d get nonsense results.\nBut because commits are full copies of everything, we can move them around without any logical problems. Think of reordering the trays with the paper planes we used in the first class.\nIn fact, all that git is doing is re-writing the parent for each commit.\nAnd branches are just like little post-its added to some commits, they are just metadata pointers. Neat, isn’t it?\nSee more about this on the GitHub blog https://github.blog/2020-12-17-commits-are-snapshots-not-diffs/\n\n\n\n\n18.1.3 Exercises\n\n18.1.3.1 Individual Exercises\n\nNow you work to get the orange_branch organized.\n\n\n\n18.1.3.2 Group Exercise\nGroups of 3. Nominate Maintainer, Contributor A, and Contributor B.\n\nMaintainer creates a repo on Github.\nMaintainer adds 2 commits and pushes.\nContributor A and Contributor B fork and clone (and add upstream).\nContributor A and Contributor B create a feature branch called will_need_split.\nContributor A and Contributor B add four commits of four files on will_need_split\nContributor A and Contributor B create a pull request to upstream from their will_need_split branch (including all four commits).\nMaintainer rejects the pull request, closing it and commenting “please split this up” (and direct which files go together, probably 2 in each.)\nContributor A and Contributor B follow procedure above to end up with two new branches split_branch_1 and split_branch_2 send through separate pull requests with only the right commits/files in them.\nMaintainer eventually accepts each of the four split up pull requests.",
+ "section": "18.2 LearnGitBranching exercise",
+ "text": "18.2 LearnGitBranching exercise\nWe can see an example of the overall workflow for splitting a PR using the LearnGitBranching Visualizer, I have created a level called Split Pull Request.",
+ "crumbs": [
+ "Skills",
+ "18Split a Pull Request"
+ ]
+ },
+ {
+ "objectID": "skills/git_cherrypick_split_pr.html#cherry-pick-via-commandline-git",
+ "href": "skills/git_cherrypick_split_pr.html#cherry-pick-via-commandline-git",
+ "title": "18 Split a Pull Request",
+ "section": "18.3 Cherry-pick via commandline git",
+ "text": "18.3 Cherry-pick via commandline git\nYou can see a situation like this in this repo on GitHub. Bring that to your working space with:\ncd ~\ngit clone https://github.com/jameshowison/i320d-needs-split.git\ncd i320d-needs-split\nIf you then run our git viz command (see Section A.3 for how to set up a short cut for that)\nYou will see both our apple and orange edits all together on the main branch.\njlh5498@educcomp04:~/github_repos/i320d-needs-split$ git viz\n* c70df5a (HEAD -> main) orange2\n* 423ad05 apple2\n* 4f1fe99 orange1\n* 91abdfb apple1\n* 8e35b12 branch here\n* ea4d580 main1\n* 252ff3f Initial commit\nWe eventually want this to look like our first graph above, with two new branches (apple_branch and orange_branch):\njlh5498@educcomp04:~/github_repos/i320d-needs-split$ git viz\n* 09d5482 (HEAD -> orange_branch) orange2\n* 2137500 orange1\n| * c8fd64d (apple_branch) apple2\n| * 1a5ac49 apple1\n|/ \n* 158f2c4 (main) branch here\n* 96d65c3 main2\n* 7036c11 main 1\n* 252ff3f Initial commit\nTo get there we will take three steps:\n\nCreate a new branch, specifying the starting point\nMove the relevant commits to the new branch\nPush to the fork, create a new pull request\n\ngit checkout -b apple_branch 8e35b12\nThe 8e35b12 here is the commit id of the point at which we want the branch to start. Until now when we’ve created a branch we have done so while sitting at HEAD but git allows us to create a branch back in time. Git does this by adding metadata to the earlier commit (labeling it with a branch label).\nThen we can move the commits using git cherry-pick. Note that this doesn’t move them from the main branch, but creates new commits with the same content. This is very much like copying files from one directory into another directory (except we are moving commits from a branch to another branch).\ngit cherry-pick 91abdfb 423ad05\nAgain the strings 91abdfb and 423ad05 identify specific commits. We can provide a list (like above), just one, and it is also possible to provide a range if you want a full sequence of commits.\nAfter the cherry-pick we see:\njlh5498@educcomp04:~/github_repos/i320d-needs-split$ git cherry-pick 91abdfb 423ad05\n[apple_branch 9ca623a] apple1\n Date: Wed Mar 1 15:31:38 2023 -0600\n 1 file changed, 1 insertion(+)\n[apple_branch 2b82f41] apple2\n Date: Wed Mar 1 15:31:38 2023 -0600\n 1 file changed, 1 insertion(+)\njlh5498@educcomp04:~/github_repos/i320d-needs-split$ git viz\n* 2b82f41 (HEAD -> apple_branch) apple2\n* 9ca623a apple1\n| * c70df5a (origin/main, origin/HEAD, main) orange2\n| * 423ad05 apple2\n| * 4f1fe99 orange1\n| * 91abdfb apple1\n|/ \n* 8e35b12 branch here\n* ea4d580 main1\n* 252ff3f Initial commit\nWe can then use git push as normal to push the apple_branch up to the fork and make a pull request.\n\n\n\n\n\n\nNote\n\n\n\nMoving around commits using cherry-pick shows us why it is so important to understand commits as full copies of the state of the working directory, as full snapshots of our files. If commits were just the changes (just a bunch of diffs) then we would have to apply them in the order they were created, otherwise we’d get nonsense results.\nBut because commits are full copies of everything, we can move them around without any logical problems. Think of reordering the trays with the paper planes we used in the first class.\nIn fact, all that git is doing is re-writing the parent for each commit.\nAnd branches are just like little post-its added to some commits, they are just metadata pointers. Neat, isn’t it?\nSee more about this on the GitHub blog https://github.blog/2020-12-17-commits-are-snapshots-not-diffs/",
+ "crumbs": [
+ "Skills",
+ "18Split a Pull Request"
+ ]
+ },
+ {
+ "objectID": "skills/git_cherrypick_split_pr.html#exercises",
+ "href": "skills/git_cherrypick_split_pr.html#exercises",
+ "title": "18 Split a Pull Request",
+ "section": "18.4 Exercises",
+ "text": "18.4 Exercises\n\n18.4.1 Individual Exercises\n\nNow you work to get the orange_branch organized.\n\n\n\n18.4.2 Group Exercise\nGroups of 3. Nominate Maintainer, Contributor A, and Contributor B.\n\nMaintainer creates a repo on Github.\nMaintainer adds 2 commits and pushes.\nContributor A and Contributor B fork and clone (and add upstream).\nContributor A and Contributor B create a feature branch called will_need_split.\nContributor A and Contributor B add four commits of four files on will_need_split\nContributor A and Contributor B create a pull request to upstream from their will_need_split branch (including all four commits).\nMaintainer rejects the pull request, closing it and commenting “please split this up” (and direct which files go together, probably 2 in each.)\nContributor A and Contributor B follow procedure above to end up with two new branches split_branch_1 and split_branch_2 send through separate pull requests with only the right commits/files in them.\nMaintainer eventually accepts each of the four split up pull requests.",
"crumbs": [
"Skills",
"18Split a Pull Request"
@@ -985,12 +1018,23 @@
"19Rebase for synchronizing work"
]
},
+ {
+ "objectID": "skills/git_rebase.html#rebase-exercise",
+ "href": "skills/git_rebase.html#rebase-exercise",
+ "title": "19 Rebase for synchronizing work",
+ "section": "19.2 Rebase Exercise",
+ "text": "19.2 Rebase Exercise\nIn groups of three, a Maintainer and two contributors, begin by setting up the collaboration network (a new repo, forks, clones and setting upstream). Then work together to implement these steps:\n\nMaintainer makes two commits to the main branch, contributors use git pull upstream main to synchronize.\nEach contributor creates a feature branch, and adds two commits to a file with their name.\nContributors create PRs that the Maintainer sees on the upstream/sahred repository.\nMaintainer can accept one, merging to main.\nMaintainer then asks the other contributor to rebase their contribution.\nThe contributor doing the rebase first does a git pull upstream main to get the new work onto the main branch in their local git.\nThen the contributor uses rebase and squash (as above) and uses git push -f to get their fork syncrhonized with their rebase.\nMaintainer should then check the PR and they will find only a single commit (the two previous ones squashed together), now looking as though it branched off main after the first contributor’s work. Maintainer can then accept the rebased PR.\nBoth contributors should sychronize (git pull upstream main and then git push to sync their forks.)",
+ "crumbs": [
+ "Skills",
+ "19Rebase for synchronizing work"
+ ]
+ },
{
"objectID": "skills/git_delete_history.html",
"href": "skills/git_delete_history.html",
"title": "20 Removing something from history entirely",
"section": "",
- "text": "The purpose of git is to retain all of your history, so that you can go back to any point in development and recover (as well as experiment while not breaking the mainline of development). Simultaneously when we are working in the open that means that anyone can view any file that was ever in a repository. With that in mind it is not too surprising that if you accidentally add something to git and then push it to github you can have trouble putting “the genie back in the bottle.”\nLet’s say that we create a repo and add a README, then add a SPECIAL_SECRET file with the password “swordfish” in it. Note that I use git add * below which is a very common way to accidentally add a problematic file, try to get into the habit of adding files one by one.\n$ cd practice_history_edit/\ngit init\nInitialized empty Git repository in /Users/howison/Documents/UTexas/Courses/PeerProduction/practice_history_edit/.git/\nvi README\ngit status\nOn branch main\n\nNo commits yet\n\nUntracked files:\n (use \"git add <file>...\" to include in what will be committed)\n\n README\n\nnothing added to commit but untracked files present (use \"git add\" to track)\ngit add README\ngit commit -m \"now we have a README\"\n[main (root-commit) f4878b0] now we have a README\n 1 file changed, 1 insertion(+)\n create mode 100644 README\nvi SPECIAL_SECRET\ngit add *\ngit commit -m \"whoops added secret\"\n[main 018f6b5] whoops added secret\n 1 file changed, 1 insertion(+)\n create mode 100644 SPECIAL_SECRET\ngit log --oneline --abbrev-commit --all --graph --decorate --color\n* 018f6b5 (HEAD -> main) whoops added secret\n* f4878b0 now we have a README\nNow I’ll go ahead and make one more edit to README\nvi README\ngit add READMEgit commit -m \"README edit 2\"[main 4d51f91] README edit 2\n 1 file changed, 1 insertion(+)\ngit log --oneline --abbrev-commit --all --graph --decorate --color* 4d51f91 (HEAD -> main) README edit 2\n* 018f6b5 whoops added secret\n* f4878b0 now we have a README\nls\nREADME SPECIAL_SECRET\ncat SPECIAL_SECRET\nswordfish\nOk, so we realize that the password file got into git and we swing into action and delete it from git.\ngit rm SPECIAL_SECRET\nrm 'SPECIAL_SECRET'\ngit commit -m \"phew removed it, or did we\"\n[main ff229ba] phew removed it, or did we\n 1 file changed, 1 deletion(-)\n delete mode 100644 SPECIAL_SECRET\nls\nREADME\nSo now the file is not there. Or rather it is not in our working directory. The problem is that it is still inside out .git folder and we can get it out easily.\ngit checkout HEAD~1\nNote: checking out 'HEAD~1'.\n\nYou are in 'detached HEAD' state. You can look around, make experimental\nchanges and commit them, and you can discard any commits you make in this\nstate without impacting any branches by performing another checkout.\n\nIf you want to create a new branch to retain commits you create, you may\ndo so (now or later) by using -b with the checkout command again. Example:\n\n git checkout -b <new-branch-name>\n\nHEAD is now at 4d51f91... README edit 2\nlsREADME SPECIAL_SECRET\ncat SPECIAL_SECRET\nswordfish\nHere I just used git checkout HEAD~1 which goes one commit back in time, to before we deleted the SPECIAL_SECRET file. Even if we were far ahead, or over on other branches etc, I could always get back by asking to see the code just after the commit that added the file git checkout 018f6b5 (btw, to get out of DETACHED HEAD state just checkout the branch again, we’re working on main so it would be git checkout main).\nSo using git rm removes a file from the working directories but it doesn’t remove it from the git history. And that’s a sensible thing, usually you want to be able to go back in time. But sometimes you want to remove something from the history entirely. You can do that using the approaches outlined by Github here: Removing sensitive data from a repository\nThe process is a bit complex (as it should be) but simplified with the bfg tool, as described at the link above. First you have to download the tool (which requires Java to run) then follow the instructions step by step.\nKeep in mind that if you had pushed this sensitive info to a repo on github and others had then forked or cloned it then that info is not going to be deleted from the clones, so passwords should definitely be changed and you should ask everyone to delete forks/clones and start again.\nThere are a set of approaches to avoid uploading sensitive data. A good starting point is discipline around using .gitignore which will prevent adding files that should not be added. Another approach is to become familiar with using environment variables to hold secrets. This is an evolving area, so ask others in your organization how they handle secrets (usually access credentials) when using git. One recent approach (specific to GitHub is https://docs.github.com/en/actions/security-guides/encrypted-secrets)",
+ "text": "The purpose of git is to retain all of your history, so that you can go back to any point in development and recover (as well as experiment while not breaking the mainline of development). Simultaneously when we are working in the open that means that anyone can view any file that was ever in a repository. With that in mind it is not too surprising that if you accidentally add something to git and then push it to github you can have trouble putting “the genie back in the bottle.”\nLet’s say that we create a repo and add a README, then add a SPECIAL_SECRET file with the password “swordfish” in it. Note that I use git add * below which is a very common way to accidentally add a problematic file, try to get into the habit of adding files one by one.\n$ cd practice_history_edit/\ngit init\nInitialized empty Git repository in /Users/howison/Documents/UTexas/Courses/PeerProduction/practice_history_edit/.git/\nvi README\ngit status\nOn branch main\n\nNo commits yet\n\nUntracked files:\n (use \"git add <file>...\" to include in what will be committed)\n\n README\n\nnothing added to commit but untracked files present (use \"git add\" to track)\ngit add README\ngit commit -m \"now we have a README\"\n[main (root-commit) f4878b0] now we have a README\n 1 file changed, 1 insertion(+)\n create mode 100644 README\nvi SPECIAL_SECRET\ngit add *\ngit commit -m \"whoops added secret\"\n[main 018f6b5] whoops added secret\n 1 file changed, 1 insertion(+)\n create mode 100644 SPECIAL_SECRET\ngit viz\n* 018f6b5 (HEAD -> main) whoops added secret\n* f4878b0 now we have a README\nNow I’ll go ahead and make one more edit to README\nvi README\ngit add READMEgit commit -m \"README edit 2\"[main 4d51f91] README edit 2\n 1 file changed, 1 insertion(+)\ngit viz\n* 4d51f91 (HEAD -> main) README edit 2\n* 018f6b5 whoops added secret\n* f4878b0 now we have a README\nls\nREADME SPECIAL_SECRET\ncat SPECIAL_SECRET\nswordfish\nOk, so we realize that the password file got into git and we swing into action and delete it from git.\ngit rm SPECIAL_SECRET\nrm 'SPECIAL_SECRET'\ngit commit -m \"phew removed it, or did we\"\n[main ff229ba] phew removed it, or did we\n 1 file changed, 1 deletion(-)\n delete mode 100644 SPECIAL_SECRET\nls\nREADME\nSo now the file is not there. Or rather it is not in our working directory. The problem is that it is still inside out .git folder and we can get it out easily.\ngit checkout HEAD~1\nNote: checking out 'HEAD~1'.\n\nYou are in 'detached HEAD' state. You can look around, make experimental\nchanges and commit them, and you can discard any commits you make in this\nstate without impacting any branches by performing another checkout.\n\nIf you want to create a new branch to retain commits you create, you may\ndo so (now or later) by using -b with the checkout command again. Example:\n\n git checkout -b <new-branch-name>\n\nHEAD is now at 4d51f91... README edit 2\nlsREADME SPECIAL_SECRET\ncat SPECIAL_SECRET\nswordfish\nHere I just used git checkout HEAD~1 which goes one commit back in time, to before we deleted the SPECIAL_SECRET file. Even if we were far ahead, or over on other branches etc, I could always get back by asking to see the code just after the commit that added the file git checkout 018f6b5 (btw, to get out of DETACHED HEAD state just checkout the branch again, we’re working on main so it would be git checkout main).\nSo using git rm removes a file from the working directories but it doesn’t remove it from the git history. And that’s a sensible thing, usually you want to be able to go back in time. But sometimes you want to remove something from the history entirely. You can do that using the approaches outlined by Github here: Removing sensitive data from a repository\nThe process is a bit complex (as it should be) but simplified with the bfg tool, as described at the link above. First you have to download the tool (which requires Java to run) then follow the instructions step by step.\nKeep in mind that if you had pushed this sensitive info to a repo on github and others had then forked or cloned it then that info is not going to be deleted from the clones, so passwords should definitely be changed and you should ask everyone to delete forks/clones and start again.\nThere are a set of approaches to avoid uploading sensitive data. A good starting point is discipline around using .gitignore which will prevent adding files that should not be added. Another approach is to become familiar with using environment variables to hold secrets. This is an evolving area, so ask others in your organization how they handle secrets (usually access credentials) when using git. One recent approach (specific to GitHub is https://docs.github.com/en/actions/security-guides/encrypted-secrets)",
"crumbs": [
"Skills",
"20Removing something from history entirely"
@@ -1122,7 +1166,18 @@
"href": "skills/packaging.html",
"title": "23 Packages to distibute code",
"section": "",
- "text": "24 What is needed for package management?\nPackages are ways of distributing software. We discussed packages in the material on Stack, Streak and Ecosystem: Chapter 10\nPackages enable us to build on the work of others, when we install packages and import them into our code.\nBut eventually we will have code that we want to distribute to others, whether that be classmates or others within our organization, or perhaps the world at large.\nThere are a few ways that we can distribute code, all with pros and cons.\nCopy and paste. We can send code to others by simply copying and pasting, then sending perhaps by Slack or even through email. A slightly more advanced approach is to use a gist or pastebin such as https://gist.github.com/ or http://pastebin.com. Copy and pasting is quick but it is limited. We then have no way of updating the code, or of knowing where it is used.\nWe can, of course, share code via GitHub or GitLab. Here we can publish a repository, either publicly or within our Organization, and give people the URL. Then people can clone the code into their individual workspaces. At least then the potential user can re-visit for updates and our user would know where they could contact people for issues or even to share improvements.\nBut GitHub on its own does not offer much to manage the complexities of developing software and keeping things up to date over time. For that we must turn to packaging and to package distribution systems which provides the python packages that can be installed by pip. These offer much greater effectiveness: the package publisher can provide updates, bugfixes or improvements, and the user can get informed about when updates are available and have them automatically downloaded.\nPackages and package management offer a few other important advantages:\nPackaging can be thought about in four steps:\nDifferent languages and software ecosystems implement these steps themselves.\nIn Python, for examples, Encapsulation is done with directories, which have files inside with the code (“regular” some_code_name.py files. Metadata is done with additional files inside the directories. The tool pip handles both installation and dependency resolution. For the server that hosts the packages there is one broad public server called PyPI (which stands for the PYthon Package Index), but it is also possible for individual organizations to run a version “behind the firewall” to manage packages within their organization.\nIn R, encapsulation is also done thorugh directories, metadata through files. Package installation is done within the R base software. In R there are a few important central repositories, including CRAN (Comprehensive R Archive Network) and Bioconductor (a separate package manager focused on biology packages, an example of convergent evolution). There are lots of different mirrors for CRAN.\nPackage management “behind the firewall” is so important to firms, that the company that builds Rstudio now offers package management for both R and Python https://packagemanager.posit.co/client/#/ both publically and within companies. Similarly Anaconda a company based in Austin offers package management across an eve wider set of languages.",
+ "text": "23.1 What is needed for package management?\nPackages are ways of distributing software. We discussed packages in the material on Stack, Streak and Ecosystem: Chapter 10\nPackages enable us to build on the work of others, when we install packages and import them into our code.\nBut eventually we will have code that we want to distribute to others, whether that be classmates or others within our organization, or perhaps the world at large.\nThere are a few ways that we can distribute code, all with pros and cons.\nCopy and paste. We can send code to others by simply copying and pasting, then sending perhaps by Slack or even through email. A slightly more advanced approach is to use a gist or pastebin such as https://gist.github.com/ or http://pastebin.com. Copy and pasting is quick but it is limited. We then have no way of updating the code, or of knowing where it is used.\nWe can, of course, share code via GitHub or GitLab. Here we can publish a repository, either publicly or within our Organization, and give people the URL. Then people can clone the code into their individual workspaces. At least then the potential user can re-visit for updates and our user would know where they could contact people for issues or even to share improvements.\nBut GitHub on its own does not offer much to manage the complexities of developing software and keeping things up to date over time. For that we must turn to packaging and to package distribution systems which provides the python packages that can be installed by pip. These offer much greater effectiveness: the package publisher can provide updates, bugfixes or improvements, and the user can get informed about when updates are available and have them automatically downloaded.\nPackages and package management offer a few other important advantages:\nPackaging can be thought about in four steps:\nDifferent languages and software ecosystems implement these steps themselves.\nIn Python, for examples, Encapsulation is done with directories, which have files inside with the code (“regular” some_code_name.py files. Metadata is done with additional files inside the directories. The tool pip handles both installation and dependency resolution. For the server that hosts the packages there is one broad public server called PyPI (which stands for the PYthon Package Index), but it is also possible for individual organizations to run a version “behind the firewall” to manage packages within their organization.\nIn R, encapsulation is also done thorugh directories, metadata through files. Package installation is done within the R base software. In R there are a few important central repositories, including CRAN (Comprehensive R Archive Network) and Bioconductor (a separate package manager focused on biology packages, an example of convergent evolution). There are lots of different mirrors for CRAN.\nPackage management “behind the firewall” is so important to firms, that the company that builds Rstudio now offers package management for both R and Python https://packagemanager.posit.co/client/#/ both publically and within companies. Similarly Anaconda a company based in Austin offers package management across an eve wider set of languages.",
+ "crumbs": [
+ "Skills",
+ "23Packages to distibute code"
+ ]
+ },
+ {
+ "objectID": "skills/packaging.html#what-is-needed-for-package-management",
+ "href": "skills/packaging.html#what-is-needed-for-package-management",
+ "title": "23 Packages to distibute code",
+ "section": "",
+ "text": "Encapsulating code in a chunk that can be moved around\nMetadata that describes the package, including authorship, licensing and, crucially, dependencies.\nAn installation tool that can bring packages from the server into local environments, and check and manage dependencies.\nA server location to which packages can be published",
"crumbs": [
"Skills",
"23Packages to distibute code"
@@ -1132,8 +1187,8 @@
"objectID": "skills/packaging.html#from-code-to-published-package-in-python",
"href": "skills/packaging.html#from-code-to-published-package-in-python",
"title": "23 Packages to distibute code",
- "section": "24.1 From code to published package in Python",
- "text": "24.1 From code to published package in Python\nFor these materials we will work through a Data Camp course (which you are welcome to finish), called Developing Python Packages.\nThe course shows how to take code and wrap it in a directory with special files, then how to publish it to PyPI (using a special repository just for testing).",
+ "section": "23.2 From code to published package in Python",
+ "text": "23.2 From code to published package in Python\nFor these materials we will work through a Data Camp course (which you are welcome to finish), called Developing Python Packages.\nThe course shows how to take code and wrap it in a directory with special files, then how to publish it to PyPI (using a special repository just for testing).",
"crumbs": [
"Skills",
"23Packages to distibute code"
@@ -1176,8 +1231,8 @@
"objectID": "skills/skills_faq.html#sec-gitviz",
"href": "skills/skills_faq.html#sec-gitviz",
"title": "Appendix A — Skills faq",
- "section": "A.3 Vizualizing git trees (aka gitviz)",
- "text": "A.3 Vizualizing git trees (aka gitviz)\nIn this course we are using a command that I usually call “gitviz” for short:\ngit log --oneline --abbrev-commit --all --graph --decorate --color\nThis produces reasonably readable graphs (especially for the teaching repos used in this course).\nThey look like this:\njlh5498@educcomp04:~/github_repos/i320_test3,,\\n git log --oneline --abbrev-commit --all --graph --decorate --color\n* d8ab2c1 (HEAD -> main, origin/main, origin/HEAD) Merge pull request #1 from jameshowison/new-feature\n|\\ \n| * ffb601d (origin/new-feature, new-feature) added extra\n|/ \n* f256ee7 Added line to README\n* 093fb0c Initial commit\nOr as an image (with coloring as on Edupod Rstudio):\n\n\n\nImage showing output of gitviz command shown as text above\n\n\nYou can read a little more about how to read these graphs here https://stackoverflow.com/questions/22313343/git-graph-what-do-the-lines-and-asteriks-denote\nLong story short:\n\nThe asterisk characters (*) show a single commit\nThe lines formed with characters like (| \\ /) help us follow which branches a commit was on.\nThe words in parens show branch names, and can include the names of remotes (e.g., origin/new-feature means the new-feature branch on the origin remote)\n\nIt is a long command, so you can either keep it handy in a pastebin (I use Typinator) or you can register it as a command alias for git itself:\ngit config --global alias.viz 'log --oneline --abbrev-commit --all --graph --decorate --color'\nSo then you can just type:\ngit viz",
+ "section": "A.3 Vizualizing git trees (aka git viz)",
+ "text": "A.3 Vizualizing git trees (aka git viz)\nIn this course we are using a command that I usually call “git viz” for short:\ngit log --oneline --abbrev-commit --all --graph --decorate --color\nInstructions for creating the convenient alias git viz are in Git basic workflow.\nThis produces reasonably readable graphs (especially for the teaching repos used in this course).\nThey look like this:\njlh5498@educcomp04:~/github_repos/i320_test3,,\\n git viz\n* d8ab2c1 (HEAD -> main, origin/main, origin/HEAD) Merge pull request #1 from jameshowison/new-feature\n|\\ \n| * ffb601d (origin/new-feature, new-feature) added extra\n|/ \n* f256ee7 Added line to README\n* 093fb0c Initial commit\nOr as an image (with coloring as on Edupod Rstudio):\n\n\n\nImage showing output of git viz command shown as text above\n\n\nYou can read a little more about how to read these graphs here https://stackoverflow.com/questions/22313343/git-graph-what-do-the-lines-and-asteriks-denote\nLong story short:\n\nThe asterisk characters (*) show a single commit\nThe lines formed with characters like (| \\ /) help us follow which branches a commit was on.\nThe words in parens show branch names, and can include the names of remotes (e.g., origin/new-feature means the new-feature branch on the origin remote)\n\nIt is a long command, so you can either keep it handy in a pastebin (I use Typinator) or you can register it as a command alias for git itself:\ngit config --global alias.viz 'log --oneline --abbrev-commit --all --graph --decorate --color'\nSo then you can just type:\ngit viz",
"crumbs": [
"Appendices",
"ASkills faq"
diff --git a/docs/current/skills/branching.html b/docs/current/skills/branching.html
index 5e2a38a..9bf3eb8 100644
--- a/docs/current/skills/branching.html
+++ b/docs/current/skills/branching.html
@@ -396,17 +396,13 @@
Some weird git errors can come when we accidentally have git repos inside other git repos. In particular this can happen if we accidentally make our home folder into a git repo. See discussion and fixes in Section A.2 You can find additional help in the FAQ section: Appendix A
Use the terminal to create a new git repo so that when you run our git viz command you see this output:
Remember that for a new git repo you may have to provide a username and email address. These commands will help (you don’t need to change the names but can if you want)
15.2.2 Coordinating new work while keeping old work running
Currently the report is pretty simple, it’s just a table of sales divided up between in-store and online. Each day’s sales are added as a new row in the table.
-
cd ~
-mkdir scratch_branching
-cd scratch_branching
-git init
+
cd ~
+mkdir scratch_branching
+cd scratch_branching
+git init
Initialized empty Git repository in scratch_branching/.git/
We can now add the reporting script and the data for monday. To simulate editing a file using an editor we can use some fancy syntax so you can copy and paste it.
echo"# Work towards charts">> reporting_script.Rmd
-git status
+
echo"# Work towards charts">> reporting_script.Rmd
+git status
On branch towards_chart
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
@@ -458,53 +454,53 @@
-
git add reporting_script.Rmd
-git commit -m"Worked towards charts"
+
git add reporting_script.Rmd
+git commit -m"Worked towards charts"
[towards_chart acc3f42] Worked towards charts
1 file changed, 1 insertion(+)
On Tuesday you see that the report ran fine (using the code in master) and you continue to work on the charts.
-
echo"# More work towards charts">> reporting_script.Rmd
-git add reporting_script.Rmd
-git commit -m"More work towards charts"
+
echo"# More work towards charts">> reporting_script.Rmd
+git add reporting_script.Rmd
+git commit -m"More work towards charts"
[towards_chart acc3f42] Worked towards charts
1 file changed, 1 insertion(+)
On Wednesday morning, though, you get an error from your reporting script. The online sales system updated and the data files now include a new column saying whether a sale was cash or credit. You know how to get things working again, but you still aren’t ready to launch your chart system. You don’t want to wait until your chart work is finished to get the report going again.
So you switch to master, edit the reporting file to handle the new column, then add and commit the change.
-
git checkout master
+
git checkout master
Switched to branch 'master'
Now we are back on the master branch and we won’t see our work towards the charts at all. So over on the towards_chart branch we can work away without upsetting the working code on master.
Check the current content of the script (will show nothing about charts)
-
cat reporting_script.Rmd
+
cat reporting_script.Rmd
Initial code for table report
So now we can, without involving our work towards the chart, make the bugfix on master.
-
echo"# Fix to match new data format">> reporting_script.Rmd
-git add reporting_script.Rmd
-git commit -m"A fix to match new data format"
+
echo"# Fix to match new data format">> reporting_script.Rmd
+git add reporting_script.Rmd
+git commit -m"A fix to match new data format"
jlh5498@educcomp04:~/scratch_branching$ git log --oneline--abbrev-commit--all--graph--decorate--color
-* 48afd7c (HEAD-> master)A fix to match new data format
-|* 5c7fc76 (towards_chart)More work towards charts
-|* c72d745 Worked towards charts
-|/
-* c434df6 starting setup
+
jlh5498@educcomp04:~/scratch_branching$ git viz
+* 48afd7c (HEAD-> master)A fix to match new data format
+|* 5c7fc76 (towards_chart)More work towards charts
+|* c72d745 Worked towards charts
+|/
+* c434df6 starting setup
Happily the report runs fine on Wednesday night.
Thursday morning you switch back to the towards_chart branch and are pleased to get things working.
-
git checkout towards_chart
-echo"# Code to finalize the charts">> reporting_script.Rmd
-git add reporting_script.Rmd
-git commit -m"Finished up the charts"
+
git checkout towards_chart
+echo"# Code to finalize the charts">> reporting_script.Rmd
+git add reporting_script.Rmd
+git commit -m"Finished up the charts"
You are ready to add the chart into the report by moving the code to the master branch.
But if you just merge the code back to master you may find that the code for the chart doesn’t work with the change to handle the updated data files. So you may have some merging to do. But you don’t know if you can get that done before the report has to run, and you don’t want to get caught fiddling with master because if the report tries to run you could end up with nothing going out that night.
So you first merge master over to your towards_chart branch, and ensure that things work well and the two pieces of work done in parallel work well together (charts and dealing with the new column).
First confirm which branch you are in, this command lists the branches and the one highlighted with the * is the current branch. git status can also show you.
-
git branch -v
+
git branch -v
git branch -v
master 576bc90 A fix to match new data format
* towards_chart bef7b72 Finished up the charts
Then merge over the master branch into the towards_chart branch.
-
git merge master
+
git merge master
Auto-merging reporting_script.Rmd
CONFLICT (content): Merge conflict in reporting_script.Rmd
Automatic merge failed; fix conflicts and then commit the result.
@@ -535,20 +531,20 @@
And now we can add and commit to finish the merge.
[towards_chart e420a05] merged bug fix with charts code
(Git can only flag syntactical conflicts, not semantic conflicts, so one would also try running some test reports to make sure things are all working).
So once you’ve resolved all issues, then you can merge the towards_chart branch back to master, signalling that you are ready to launch your new report with charts.
Finally we can visualize this branching, editing, and merging in two ways. First we can use this handy command to see a visualization in the command line.
Which will show us this (using an image here because the color doesn’t copy):
We can also see this visually using learngitbranching, see the short video below.
@@ -565,10 +561,10 @@
Do exercises 2 and 3 (“Branching in Git” and “Merging in Git”)
Shift back to the terminal and replicate the “Merging in Git” lesson. You will need to start with these commands (to create a new, empty, repo):
-
cd ~
-mkdir replicate_learngitbranching
-cd replicate_learngitbranching
-git init
+
cd ~
+mkdir replicate_learngitbranching
+cd replicate_learngitbranching
+git init
Remember that when we are working in the terminal it is different from learngitbranching because we have to actually create, edit, and save files before we can commit. We also have to use git commit -m 'some message' rather than just git commit.
We can see an example of the overall workflow for splitting a PR using the LearnGitBranching Visualizer, I have created a level called Split Pull Request.
-
-
18.1.2 Cherry-pick via commandline git
+
+
18.3 Cherry-pick via commandline git
You can see a situation like this in this repo on GitHub. Bring that to your working space with:
cd ~git clone https://github.com/jameshowison/i320d-needs-split.gitcd i320d-needs-split
-
If you then run our gitviz command (see Section A.3 for how to set up a short cut for that)
+
If you then run our git viz command (see Section A.3 for how to set up a short cut for that)
You will see both our apple and orange edits all together on the main branch.
Ignore the remote branch (origin/pie_chart_branch), and focus only on the local branch (HEAD -> pie_chart_branch). Instead of all three commits, we now only see a single commit (c367b8a).
Note that in these examples we did not encounter any conflicts (because edits were all on different files). In reality, though, when commits are moved around, rebased, and squashed, sometimes those operations result in conflicts (just as happens with merge). In that case git add the conflict symbols (<<<<<< and ========== and >>>>>>>>>) which all need to be removed, then the files added and finally we run git rebase --continue. Git does provide useful messages through that process with guidance on the likely next steps.
-
-
20 Rebase Exercise
+
+
19.2 Rebase Exercise
In groups of three, a Maintainer and two contributors, begin by setting up the collaboration network (a new repo, forks, clones and setting upstream). Then work together to implement these steps:
Maintainer makes two commits to the main branch, contributors use git pull upstream main to synchronize.
Packages can provide an appropriate location for running tests
Packages provide a way to scale up software. Data Scientists often develop code in a Notebook … which is very convenient for the analyst but not something that can be made into a web API which thousands of developers or products can use in real time. When we build packages they can be deployed in the cloud, and turned into microservices using services like Kubernetes.
-
-
24 What is needed for package management?
+
+
23.1 What is needed for package management?
Packaging can be thought about in four steps:
Encapsulating code in a chunk that can be moved around
@@ -364,13 +362,13 @@
24 What is neede
In Python, for examples, Encapsulation is done with directories, which have files inside with the code (“regular” some_code_name.py files. Metadata is done with additional files inside the directories. The tool pip handles both installation and dependency resolution. For the server that hosts the packages there is one broad public server called PyPI (which stands for the PYthon Package Index), but it is also possible for individual organizations to run a version “behind the firewall” to manage packages within their organization.
In R, encapsulation is also done thorugh directories, metadata through files. Package installation is done within the R base software. In R there are a few important central repositories, including CRAN (Comprehensive RArchive Network) and Bioconductor (a separate package manager focused on biology packages, an example of convergent evolution). There are lots of different mirrors for CRAN.
Package management “behind the firewall” is so important to firms, that the company that builds Rstudio now offers package management for both R and Python https://packagemanager.posit.co/client/#/ both publically and within companies. Similarly Anaconda a company based in Austin offers package management across an eve wider set of languages.
-
-
24.1 From code to published package in Python
+
+
+
23.2 From code to published package in Python
For these materials we will work through a Data Camp course (which you are welcome to finish), called Developing Python Packages.
The course shows how to take code and wrap it in a directory with special files, then how to publish it to PyPI (using a special repository just for testing).
Now you could cd backup_home_git and use that folder as a git repo. But probably you are about to clone from github (in which case a new folder will be created) or you are about to use git init to create a new local repo (in which case you should create a folder first, cd into it, then run git init.
-
A.3 Vizualizing git trees (aka gitviz)
-
In this course we are using a command that I usually call “gitviz” for short:
+
A.3 Vizualizing git trees (aka git viz)
+
In this course we are using a command that I usually call “git viz” for short:
diff --git a/quarto_course/_freeze/skills/skills_faq/execute-results/html.json b/quarto_course/_freeze/skills/skills_faq/execute-results/html.json
index e818e70..f288c4f 100644
--- a/quarto_course/_freeze/skills/skills_faq/execute-results/html.json
+++ b/quarto_course/_freeze/skills/skills_faq/execute-results/html.json
@@ -1,8 +1,8 @@
{
- "hash": "c5194ecbd06fd6da6481a51160e0cc80",
+ "hash": "8927179b4a9a24681f1240152cdb4552",
"result": {
"engine": "knitr",
- "markdown": "---\nengine: knitr\nexecute:\n freeze: auto # re-render only when source changes\n---\n\n\n# Skills faq {#sec-skills-faq}\n\n## git issues\n\n### Set my name and email\n\ngit wants to add your name and email to commits. These are distinct from your `github` account (remember `git` can be used independently of an online service or with online services other than github).\n\nIf you are seeing messages that end like this:\n\n``` \nYou can suppress this message by setting them explicitly. Run the\nfollowing command and follow the instructions in your editor to edit\nyour configuration file:\n\n git config --global --edit\n\nAfter doing this, you may fix the identity used for this commit with:\n\n git commit --amend --reset-author\n```\n\nThen you can run these commands to set a username and email. Note that these can be anything, they aren't a login or checked against anything, they are just metadata attached to your commits. Nonetheless having them make sense for your identity makes sense when sharing code publically. They can easily be a made up identifier (pseudonym/handle/accountname).\n\n``` bash\ngit config --global user.name \"John Doe\"\ngit config --global user.email johndoe@example.com\n```\n\n### Login to GitHub {#sec-github-login}\n\nOn the commandline we have to use the username/PAT combination. The password that works to log into GitHub on the web will not work.\n\nIf you see this message:\n\n```\nremote: No anonymous write access.\nfatal: Authentication failed for \n```\n\nThen you need to log in, but first reset the credential cache:\n\n```sh\ngit config --global credential.helper 'cache --timeout=10000000'\n```\n\nThen repeat the command that failed (hit the up-arrow twice usually brings it up).\n\nWhen you see this prompt, use your GitHub username (not the email address)\n\n```\nUsername for 'https://github.com': \n```\n\nWhen you see this prompt, even though it says \"password\" you must use your PAT token:\n\n```\nPassword for 'https://@github.com': \n```\n\nOn windows you may have to use the right-click context menu to paste into the terminal.\n\n### Password pop-up repeats too often {#sec-pass-popup}\n\nThe username/password pop-up can come up too often. Especially with GitHub requiring a PAT (and not the same password used on the website) this can be a hassle, since the PAT is not configurable and has to be copy/pasted.\n\nRstudio is generating that pop-up, but the frequency is controlled by a gitconfig variable. The default without configuration is 15m so if we don't run a git command for 15m it expires the cache and pops up again. We can make it show up less with:\n\n``` sh\ngit config --global credential.helper 'cache --timeout=10000000'\n```\n\nThat means that the cache won't expire for 10,000,000 seconds (which is 16 weeks).\n\nThanks to and the Rstudio community forums for helping me with that \n\n### Shortcut to find GitHub URL {#sec-find-github-url}\n\nA short cut to find the URL is `git remote -v`\n\n```sh\n~/workspace/i320d-testing2024$ git remote -v\norigin https://github.com/jameshowison/i320d-testing2024.git (fetch)\norigin https://github.com/jameshowison/i320d-testing2024.git (push)\n```\n\nAnd then copy the URL (with or without the .git at the end). On windows you may need to use the right-click context menu for copy and paste in a terminal.\n\n### git commit throws me into a weird mode {#sec-vim}\n\nIf you type `git commit` just on its own rather than `git commit -m \"Some message\"` you will see something like this:\n\n``` bash\n\n# Please enter the commit message for your changes. Lines starting\n# with '#' will be ignored, and an empty message aborts the commit.\n#\n# On branch master\n# Your branch is up to date with 'origin/master'.\n```\n\ngit needs a commit message. When you don't provide one it throws you into a text editor, expecting you to type a small novel.\n\nThe editor that you go into by default is the `vi` or `vim` editor. It can be confusing because it has multiple modes (ie typing doesn't always just produce text).\n\nThe best option is to:\n\n1. Hit `esc` twice: EscEsc\\\n2. Type `:q!` and hit Enter\n3. Redo your commit using \\`git commit -m \"Some message\"\n\nSee \n\n**The option below does not work in Rstudio because Rstudio captures the** Ctrl key commands\n\nYou can also configure git to use another editor: \n\nFor example, the `nano` editor is easier to use. You can set that run running\n\n``` bash\ngit config --global core.editor \"nano\"\n```\n\nIn `nano` we can type a commit message as usual. The bottom of the screen shows commands. Nano uses the `^` symbol to represent the Ctrl key. We have to save the file and then exit Nano. So to save the message and return to the commandline we use:\n\nCtrl + O\n\nThen:\n\nCtrl + X\n\n## I accidentally made my home folder a git repo {#sec-faq-home-git-folder}\n\nIf you are in your home folder but `git status` doesn't give a \"fatal error\" then you've accidentially made your home folder into a git repository (probably by running `git init` in that folder).\n\nIn this case we need to undo this. We can't delete our home folder, because it has everything else inside it. We have to somehow tell the computer that the home folder should not be a git repo. Happily, then only thing that makes it a git repo is that it has a `.git` folder inside it. You can confirm by running:\n\n``` sh\nls -lah\n```\n\nThe `-a` flag to `ls` makes it show all files and folders, even the hidden ones that start with a dot.\n\nTo fix this we could just delete the `.git` folder but we might lose data that way (if we had already added work to that repo). So safest thing is to make a new folder inside our home folder, and then move the `.git` there.\n\n``` sh\nmkdir backup_home_git\nmv ./.git ./backup_home_git\n```\n\nNow you could `cd backup_home_git` and use that folder as a git repo. But probably you are about to clone from github (in which case a new folder will be created) or you are about to use `git init` to create a new local repo (in which case you should create a folder first, `cd` into it, then run `git init`.\n\n## Vizualizing git trees (aka gitviz) {#sec-gitviz}\n\nIn this course we are using a command that I usually call \"gitviz\" for short:\n\n``` sh\ngit log --oneline --abbrev-commit --all --graph --decorate --color\n```\n\nThis produces reasonably readable graphs (especially for the teaching repos used in this course).\n\nThey look like this:\n\n``` bash\njlh5498@educcomp04:~/github_repos/i320_test3,,\\n git log --oneline --abbrev-commit --all --graph --decorate --color\n* d8ab2c1 (HEAD -> main, origin/main, origin/HEAD) Merge pull request #1 from jameshowison/new-feature\n|\\ \n| * ffb601d (origin/new-feature, new-feature) added extra\n|/ \n* f256ee7 Added line to README\n* 093fb0c Initial commit\n```\n\nOr as an image (with coloring as on Edupod Rstudio):\n\n\n\nYou can read a little more about how to read these graphs here \n\nLong story short:\n\n- The asterisk characters (`*`) show a single commit\n- The lines formed with characters like (`| \\ /`) help us follow which branches a commit was on.\n- The words in parens show branch names, and can include the names of remotes (e.g., `origin/new-feature` means the `new-feature` branch on the `origin` remote)\n\nIt is a long command, so you can either keep it handy in a pastebin (I use Typinator) or you can register it as a command alias for git itself:\n\n``` sh\ngit config --global alias.viz 'log --oneline --abbrev-commit --all --graph --decorate --color'\n```\n\nSo then you can just type:\n\n``` sh\ngit viz\n```\n\n## Seeing a merge conflict using git log\n\nIn one assignment students have to submit a repo showing a resolved merge conflict when accepting a PR. This raised the question of whether I could see this looking at the repo. Student questions helped me figure that our, leading me to which highlighted this as an issue in presenting merge conflicts for review. The most recent answer, led me to discover a new feature in `git`\n\n``` sh\ngit log --remerge-diff\n```\n\nThis enables one to see the files with the `<<<<<<` type conflict markers shown.\n\n\n::: {.cell}\n\n```{.sh .cell-code}\nrm -rf merge-conflict-example\ngit clone https://github.com/jameshowison/merge-conflict-example.git\ncd merge-conflict-example\ngit log -1 --skip 1 --remerge-diff\n## Cloning into 'merge-conflict-example'...\n## commit 50911dc2232965238790ad8ca3fdcabe56b41639\n## Merge: 57c1c6c 99b328f\n## Author: pablo-carbajo1 <99198265+pablo-carbajo1@users.noreply.github.com>\n## Date: Thu Mar 2 18:06:57 2023 -0600\n## \n## Merge branch 'main' into patch-1\n## \n## diff --git a/animals.txt b/animals.txt\n## remerge CONFLICT (content): Merge conflict in animals.txt\n## index f9970b6..f07b36e 100644\n## --- a/animals.txt\n## +++ b/animals.txt\n## @@ -1,8 +1,5 @@\n## -<<<<<<< 57c1c6c (Update animals.txt)\n## lion Contributor B\n## -=======\n## lion contributor A\n## ->>>>>>> 99b328f (Merge pull request #4 from lisahyuniko/patch-1)\n## tiger \n## leopard \n## turtle\n```\n:::\n\n::: {.cell}\n\n:::\n\n\n## Gathering the code as though the PR had been accepted {#sec-fetch-pr}\n\nSometimes it is useful to be able to work with the code that would result if the PR was accepted, but without actually accepting the PR. Sometimes this is called \"previewing the PR\". It is useful when working with PRs from others, and can also be useful when working on our own branches, but where we don't want to merge that branch to main (which is a difficult operation to undo).\n\nOn GitHub (and other online repositories like Gitlab or BitBucket) we can do this because the pull requests are added to the online repository, somewhat like branches. [We can access these](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally) using the git `fetch` command pointing to the `pull` part of the repository.\n\n```sh\ngit fetch origin pull/123/head:pr-123\ngit checkout pr-123\n```\n\nThis obtains the code **as though the PR had been accepted** and then makes a new _local branch_ that we can work with. Notice, though, that thje new local branch is not the same branch that the PR is for ... it is a local copy. Therefore we would not push that new local branch back up to GitHub, preferring to work with the PR itself (and [here is documentation about how to allow others to edit your PRs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork)). \n\n\n# How to add an image using quarto on edupod\n\nQuarto is like html in that the main `.qmd` document references separate image files, rather than incorporates them inside the main file itself. You have to place the images separetely (and also `git add` the image files separately).\n\nOn Edupod getting figures into your quarto document takes two steps:\n\n1. Upload the file to the server\n\n\n\n2. Use the Visual mode in the quarto file editor to insert the picture.\n\n\n\nUsing the Render button will confirm that your images are found.\n\nThen don't forget to `git add` the image files as well. Run a `git status` to check which files are included.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n",
+ "markdown": "---\nengine: knitr\nexecute:\n freeze: auto # re-render only when source changes\n---\n\n\n\n\n# Skills faq {#sec-skills-faq}\n\n## git issues\n\n### Set my name and email\n\ngit wants to add your name and email to commits. These are distinct from your `github` account (remember `git` can be used independently of an online service or with online services other than github).\n\nIf you are seeing messages that end like this:\n\n``` \nYou can suppress this message by setting them explicitly. Run the\nfollowing command and follow the instructions in your editor to edit\nyour configuration file:\n\n git config --global --edit\n\nAfter doing this, you may fix the identity used for this commit with:\n\n git commit --amend --reset-author\n```\n\nThen you can run these commands to set a username and email. Note that these can be anything, they aren't a login or checked against anything, they are just metadata attached to your commits. Nonetheless having them make sense for your identity makes sense when sharing code publically. They can easily be a made up identifier (pseudonym/handle/accountname).\n\n``` bash\ngit config --global user.name \"John Doe\"\ngit config --global user.email johndoe@example.com\n```\n\n### Login to GitHub {#sec-github-login}\n\nOn the commandline we have to use the username/PAT combination. The password that works to log into GitHub on the web will not work.\n\nIf you see this message:\n\n```\nremote: No anonymous write access.\nfatal: Authentication failed for \n```\n\nThen you need to log in, but first reset the credential cache:\n\n```sh\ngit config --global credential.helper 'cache --timeout=10000000'\n```\n\nThen repeat the command that failed (hit the up-arrow twice usually brings it up).\n\nWhen you see this prompt, use your GitHub username (not the email address)\n\n```\nUsername for 'https://github.com': \n```\n\nWhen you see this prompt, even though it says \"password\" you must use your PAT token:\n\n```\nPassword for 'https://@github.com': \n```\n\nOn windows you may have to use the right-click context menu to paste into the terminal.\n\n### Password pop-up repeats too often {#sec-pass-popup}\n\nThe username/password pop-up can come up too often. Especially with GitHub requiring a PAT (and not the same password used on the website) this can be a hassle, since the PAT is not configurable and has to be copy/pasted.\n\nRstudio is generating that pop-up, but the frequency is controlled by a gitconfig variable. The default without configuration is 15m so if we don't run a git command for 15m it expires the cache and pops up again. We can make it show up less with:\n\n``` sh\ngit config --global credential.helper 'cache --timeout=10000000'\n```\n\nThat means that the cache won't expire for 10,000,000 seconds (which is 16 weeks).\n\nThanks to and the Rstudio community forums for helping me with that \n\n### Shortcut to find GitHub URL {#sec-find-github-url}\n\nA short cut to find the URL is `git remote -v`\n\n```sh\n~/workspace/i320d-testing2024$ git remote -v\norigin https://github.com/jameshowison/i320d-testing2024.git (fetch)\norigin https://github.com/jameshowison/i320d-testing2024.git (push)\n```\n\nAnd then copy the URL (with or without the .git at the end). On windows you may need to use the right-click context menu for copy and paste in a terminal.\n\n### git commit throws me into a weird mode {#sec-vim}\n\nIf you type `git commit` just on its own rather than `git commit -m \"Some message\"` you will see something like this:\n\n``` bash\n\n# Please enter the commit message for your changes. Lines starting\n# with '#' will be ignored, and an empty message aborts the commit.\n#\n# On branch master\n# Your branch is up to date with 'origin/master'.\n```\n\ngit needs a commit message. When you don't provide one it throws you into a text editor, expecting you to type a small novel.\n\nThe editor that you go into by default is the `vi` or `vim` editor. It can be confusing because it has multiple modes (ie typing doesn't always just produce text).\n\nThe best option is to:\n\n1. Hit `esc` twice: EscEsc\\\n2. Type `:q!` and hit Enter\n3. Redo your commit using \\`git commit -m \"Some message\"\n\nSee \n\n**The option below does not work in Rstudio because Rstudio captures the** Ctrl key commands\n\nYou can also configure git to use another editor: \n\nFor example, the `nano` editor is easier to use. You can set that run running\n\n``` bash\ngit config --global core.editor \"nano\"\n```\n\nIn `nano` we can type a commit message as usual. The bottom of the screen shows commands. Nano uses the `^` symbol to represent the Ctrl key. We have to save the file and then exit Nano. So to save the message and return to the commandline we use:\n\nCtrl + O\n\nThen:\n\nCtrl + X\n\n## I accidentally made my home folder a git repo {#sec-faq-home-git-folder}\n\nIf you are in your home folder but `git status` doesn't give a \"fatal error\" then you've accidentially made your home folder into a git repository (probably by running `git init` in that folder).\n\nIn this case we need to undo this. We can't delete our home folder, because it has everything else inside it. We have to somehow tell the computer that the home folder should not be a git repo. Happily, then only thing that makes it a git repo is that it has a `.git` folder inside it. You can confirm by running:\n\n``` sh\nls -lah\n```\n\nThe `-a` flag to `ls` makes it show all files and folders, even the hidden ones that start with a dot.\n\nTo fix this we could just delete the `.git` folder but we might lose data that way (if we had already added work to that repo). So safest thing is to make a new folder inside our home folder, and then move the `.git` there.\n\n``` sh\nmkdir backup_home_git\nmv ./.git ./backup_home_git\n```\n\nNow you could `cd backup_home_git` and use that folder as a git repo. But probably you are about to clone from github (in which case a new folder will be created) or you are about to use `git init` to create a new local repo (in which case you should create a folder first, `cd` into it, then run `git init`.\n\n## Vizualizing git trees (aka git viz) {#sec-gitviz}\n\nIn this course we are using a command that I usually call \"git viz\" for short:\n\n``` sh\ngit log --oneline --abbrev-commit --all --graph --decorate --color\n```\n\nInstructions for creating the convenient alias `git viz` are in [Git basic workflow](git_basic_workflow.qmd).\n\nThis produces reasonably readable graphs (especially for the teaching repos used in this course).\n\nThey look like this:\n\n``` bash\njlh5498@educcomp04:~/github_repos/i320_test3,,\\n git viz\n* d8ab2c1 (HEAD -> main, origin/main, origin/HEAD) Merge pull request #1 from jameshowison/new-feature\n|\\ \n| * ffb601d (origin/new-feature, new-feature) added extra\n|/ \n* f256ee7 Added line to README\n* 093fb0c Initial commit\n```\n\nOr as an image (with coloring as on Edupod Rstudio):\n\n\n\nYou can read a little more about how to read these graphs here \n\nLong story short:\n\n- The asterisk characters (`*`) show a single commit\n- The lines formed with characters like (`| \\ /`) help us follow which branches a commit was on.\n- The words in parens show branch names, and can include the names of remotes (e.g., `origin/new-feature` means the `new-feature` branch on the `origin` remote)\n\nIt is a long command, so you can either keep it handy in a pastebin (I use Typinator) or you can register it as a command alias for git itself:\n\n``` sh\ngit config --global alias.viz 'log --oneline --abbrev-commit --all --graph --decorate --color'\n```\n\nSo then you can just type:\n\n``` sh\ngit viz\n```\n\n## Seeing a merge conflict using git log\n\nIn one assignment students have to submit a repo showing a resolved merge conflict when accepting a PR. This raised the question of whether I could see this looking at the repo. Student questions helped me figure that our, leading me to which highlighted this as an issue in presenting merge conflicts for review. The most recent answer, led me to discover a new feature in `git`\n\n``` sh\ngit log --remerge-diff\n```\n\nThis enables one to see the files with the `<<<<<<` type conflict markers shown.\n\n\n\n\n::: {.cell}\n\n```{.sh .cell-code}\nrm -rf merge-conflict-example\ngit clone https://github.com/jameshowison/merge-conflict-example.git\ncd merge-conflict-example\ngit log -1 --skip 1 --remerge-diff\n## Cloning into 'merge-conflict-example'...\n## commit 50911dc2232965238790ad8ca3fdcabe56b41639\n## Merge: 57c1c6c 99b328f\n## Author: pablo-carbajo1 <99198265+pablo-carbajo1@users.noreply.github.com>\n## Date: Thu Mar 2 18:06:57 2023 -0600\n## \n## Merge branch 'main' into patch-1\n## \n## diff --git a/animals.txt b/animals.txt\n## remerge CONFLICT (content): Merge conflict in animals.txt\n## index f9970b6..f07b36e 100644\n## --- a/animals.txt\n## +++ b/animals.txt\n## @@ -1,8 +1,5 @@\n## -<<<<<<< 57c1c6c (Update animals.txt)\n## lion Contributor B\n## -=======\n## lion contributor A\n## ->>>>>>> 99b328f (Merge pull request #4 from lisahyuniko/patch-1)\n## tiger \n## leopard \n## turtle\n```\n:::\n\n::: {.cell}\n\n:::\n\n\n\n\n## Gathering the code as though the PR had been accepted {#sec-fetch-pr}\n\nSometimes it is useful to be able to work with the code that would result if the PR was accepted, but without actually accepting the PR. Sometimes this is called \"previewing the PR\". It is useful when working with PRs from others, and can also be useful when working on our own branches, but where we don't want to merge that branch to main (which is a difficult operation to undo).\n\nOn GitHub (and other online repositories like Gitlab or BitBucket) we can do this because the pull requests are added to the online repository, somewhat like branches. [We can access these](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally) using the git `fetch` command pointing to the `pull` part of the repository.\n\n```sh\ngit fetch origin pull/123/head:pr-123\ngit checkout pr-123\n```\n\nThis obtains the code **as though the PR had been accepted** and then makes a new _local branch_ that we can work with. Notice, though, that thje new local branch is not the same branch that the PR is for ... it is a local copy. Therefore we would not push that new local branch back up to GitHub, preferring to work with the PR itself (and [here is documentation about how to allow others to edit your PRs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork)). \n\n\n# How to add an image using quarto on edupod\n\nQuarto is like html in that the main `.qmd` document references separate image files, rather than incorporates them inside the main file itself. You have to place the images separetely (and also `git add` the image files separately).\n\nOn Edupod getting figures into your quarto document takes two steps:\n\n1. Upload the file to the server\n\n\n\n2. Use the Visual mode in the quarto file editor to insert the picture.\n\n\n\nUsing the Render button will confirm that your images are found.\n\nThen don't forget to `git add` the image files as well. Run a `git status` to check which files are included.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n",
"supporting": [
"skills_faq_files"
],
diff --git a/quarto_course/insights/governance.qmd b/quarto_course/insights/governance.qmd
index 6ef9310..570ab0b 100644
--- a/quarto_course/insights/governance.qmd
+++ b/quarto_course/insights/governance.qmd
@@ -15,7 +15,7 @@
Extra optional reading: Podcast on "Learning from Open Source": . We will have readings from this later in the course, so useful to do now.
-# How do open source projects make decisions?
+## How do open source projects make decisions?
Working in a project requires many decisions, e.g.,:
diff --git a/quarto_course/skills/branching.qmd b/quarto_course/skills/branching.qmd
index 663104c..05e5eaa 100644
--- a/quarto_course/skills/branching.qmd
+++ b/quarto_course/skills/branching.qmd
@@ -35,7 +35,7 @@ Some weird git errors can come when we accidentally have git repos inside other
Use the terminal to create a new git repo so that when you run our git viz command you see this output:
``` bash
-branching_warmup % git log --oneline --abbrev-commit --all --graph --decorate --color
+branching_warmup % git viz
* 50590c5 (HEAD -> main) Wednesday
* 39f89db Tuesday
* 1b2162e Monday
@@ -48,18 +48,6 @@ git config --global user.email "you@example.com"
git config --global user.name "Your Name"
```
-The git viz command is long, so you can create a short cut for it on the commandline:
-
-```bash
-git config alias.viz 'log --oneline --abbrev-commit --all --graph --decorate --color'
-```
-
-Then you will only need to type:
-
-```bash
-git viz
-```
-
## Branching with local git
Branching (and merging) is a useful way to keep different tasks organized and synchronized, even when working locally with git. Below we will work through a scenario for git branching, showing the commands and two different vizualizations. Eventually branching becomes a key part of working with github and shared repositories, but it is useful to approach it separately first.
@@ -198,13 +186,13 @@ git commit -m "A fix to match new data format"
Now if we run our git viz command:
```sh
-git log --oneline --abbrev-commit --all --graph --decorate --color
+git viz
```
we will see our branching starting to show up:
```sh
-jlh5498@educcomp04:~/scratch_branching$ git log --oneline --abbrev-commit --all --graph --decorate --color
+jlh5498@educcomp04:~/scratch_branching$ git viz
* 48afd7c (HEAD -> master) A fix to match new data format
| * 5c7fc76 (towards_chart) More work towards charts
| * c72d745 Worked towards charts
@@ -321,7 +309,7 @@ Fast-forward
Finally we can visualize this branching, editing, and merging in two ways. First we can use this handy command to see a visualization in the command line.
```sh
-git log --oneline --abbrev-commit --all --graph --decorate --color
+git viz
```
Which will show us this (using an image here because the color doesn't copy):
diff --git a/quarto_course/skills/git_cherrypick_split_pr.qmd b/quarto_course/skills/git_cherrypick_split_pr.qmd
index 7adf46c..53f6987 100644
--- a/quarto_course/skills/git_cherrypick_split_pr.qmd
+++ b/quarto_course/skills/git_cherrypick_split_pr.qmd
@@ -63,11 +63,11 @@ gitGraph
commit id: "orange2"
```
-### LearnGitBranching exercise
+## LearnGitBranching exercise
We can see an example of the overall workflow for splitting a PR using the LearnGitBranching Visualizer, I have created a level called [Split Pull Request](https://learngitbranching.js.org/?gist_level_id=f7b4b63960ed80fa9a76728d853f2546).
-### Cherry-pick via commandline git
+## Cherry-pick via commandline git
You can see a situation like this in this repo on GitHub. Bring that to your working space with:
@@ -77,12 +77,12 @@ git clone https://github.com/jameshowison/i320d-needs-split.git
cd i320d-needs-split
```
-If you then run our gitviz command (see @sec-gitviz for how to set up a short cut for that)
+If you then run our git viz command (see @sec-gitviz for how to set up a short cut for that)
You will see both our apple and orange edits all together on the `main` branch.
``` sh
-jlh5498@educcomp04:~/github_repos/i320d-needs-split$ git log --oneline --abbrev-commit --all --graph --decorate --color
+jlh5498@educcomp04:~/github_repos/i320d-needs-split$ git viz
* c70df5a (HEAD -> main) orange2
* 423ad05 apple2
* 4f1fe99 orange1
@@ -95,7 +95,7 @@ jlh5498@educcomp04:~/github_repos/i320d-needs-split$ git log --oneline --abbrev-
We eventually want this to look like our first graph above, with two new branches (apple_branch and orange_branch):
``` sh
-jlh5498@educcomp04:~/github_repos/i320d-needs-split$ git log --oneline --abbrev-commit --all --graph --decorate --color
+jlh5498@educcomp04:~/github_repos/i320d-needs-split$ git viz
* 09d5482 (HEAD -> orange_branch) orange2
* 2137500 orange1
| * c8fd64d (apple_branch) apple2
@@ -137,7 +137,7 @@ jlh5498@educcomp04:~/github_repos/i320d-needs-split$ git cherry-pick 91abdfb 423
[apple_branch 2b82f41] apple2
Date: Wed Mar 1 15:31:38 2023 -0600
1 file changed, 1 insertion(+)
-jlh5498@educcomp04:~/github_repos/i320d-needs-split$ git log --oneline --abbrev-commit --all --graph --decorate --color
+jlh5498@educcomp04:~/github_repos/i320d-needs-split$ git viz
* 2b82f41 (HEAD -> apple_branch) apple2
* 9ca623a apple1
| * c70df5a (origin/main, origin/HEAD, main) orange2
@@ -164,13 +164,13 @@ And branches are just like little post-its added to some commits, they are just
See more about this on the GitHub blog
:::
-### Exercises
+## Exercises
-#### Individual Exercises
+### Individual Exercises
1. Now you work to get the `orange_branch` organized.
-#### Group Exercise
+### Group Exercise
Groups of 3. Nominate *Maintainer*, *Contributor A*, and *Contributor B*.
@@ -249,7 +249,7 @@ Groups of 3. Nominate *Maintainer*, *Contributor A*, and *Contributor B*.
-
+
@@ -285,7 +285,7 @@ Groups of 3. Nominate *Maintainer*, *Contributor A*, and *Contributor B*.
-
+
diff --git a/quarto_course/skills/git_delete_history.qmd b/quarto_course/skills/git_delete_history.qmd
index 552a62f..463c940 100644
--- a/quarto_course/skills/git_delete_history.qmd
+++ b/quarto_course/skills/git_delete_history.qmd
@@ -30,7 +30,7 @@ Let's say that we create a repo and add a README, then add a SPECIAL_SECRET file
[main 018f6b5] whoops added secret
1 file changed, 1 insertion(+)
create mode 100644 SPECIAL_SECRET
- git log --oneline --abbrev-commit --all --graph --decorate --color
+ git viz
* 018f6b5 (HEAD -> main) whoops added secret
* f4878b0 now we have a README
@@ -39,7 +39,8 @@ Now I'll go ahead and make one more edit to README
vi README
git add READMEgit commit -m "README edit 2"[main 4d51f91] README edit 2
1 file changed, 1 insertion(+)
- git log --oneline --abbrev-commit --all --graph --decorate --color* 4d51f91 (HEAD -> main) README edit 2
+ git viz
+ * 4d51f91 (HEAD -> main) README edit 2
* 018f6b5 whoops added secret
* f4878b0 now we have a README
ls
diff --git a/quarto_course/skills/git_rebase.qmd b/quarto_course/skills/git_rebase.qmd
index 6955712..b6cad35 100644
--- a/quarto_course/skills/git_rebase.qmd
+++ b/quarto_course/skills/git_rebase.qmd
@@ -274,7 +274,7 @@ Ignore the remote branch (origin/pie_chart_branch), and focus only on the local
Note that in these examples we did not encounter any conflicts (because edits were all on different files). In reality, though, when commits are moved around, rebased, and squashed, sometimes those operations result in conflicts (just as happens with merge). In that case git add the conflict symbols (`<<<<<<` and `==========` and `>>>>>>>>>`) which all need to be removed, then the files added and finally we run `git rebase --continue`. Git does provide useful messages through that process with guidance on the likely next steps.
-# Rebase Exercise
+## Rebase Exercise
In groups of three, a Maintainer and two contributors, begin by setting up the collaboration network (a new repo, forks, clones and setting upstream). Then work together to implement these steps:
diff --git a/quarto_course/skills/packaging.qmd b/quarto_course/skills/packaging.qmd
index b4549d7..fd44440 100644
--- a/quarto_course/skills/packaging.qmd
+++ b/quarto_course/skills/packaging.qmd
@@ -25,7 +25,7 @@ Packages and package management offer a few other important advantages:
- Packages can provide an appropriate location for running tests
- Packages provide a way to scale up software. Data Scientists often develop code in a Notebook ... which is very convenient for the analyst but not something that can be made into a web API which thousands of developers or products can use in real time. When we build packages they can be deployed in the cloud, and turned into [microservices](https://en.wikipedia.org/wiki/Microservices) using services like Kubernetes.
-# What is needed for package management?
+## What is needed for package management?
Packaging can be thought about in four steps:
diff --git a/quarto_course/skills/skills_faq.qmd b/quarto_course/skills/skills_faq.qmd
index 5827733..e53c931 100644
--- a/quarto_course/skills/skills_faq.qmd
+++ b/quarto_course/skills/skills_faq.qmd
@@ -156,20 +156,22 @@ mv ./.git ./backup_home_git
Now you could `cd backup_home_git` and use that folder as a git repo. But probably you are about to clone from github (in which case a new folder will be created) or you are about to use `git init` to create a new local repo (in which case you should create a folder first, `cd` into it, then run `git init`.
-## Vizualizing git trees (aka gitviz) {#sec-gitviz}
+## Vizualizing git trees (aka git viz) {#sec-gitviz}
-In this course we are using a command that I usually call "gitviz" for short:
+In this course we are using a command that I usually call "git viz" for short:
``` sh
git log --oneline --abbrev-commit --all --graph --decorate --color
```
+Instructions for creating the convenient alias `git viz` are in [Git basic workflow](git_basic_workflow.qmd).
+
This produces reasonably readable graphs (especially for the teaching repos used in this course).
They look like this:
``` bash
-jlh5498@educcomp04:~/github_repos/i320_test3,,\n git log --oneline --abbrev-commit --all --graph --decorate --color
+jlh5498@educcomp04:~/github_repos/i320_test3,,\n git viz
* d8ab2c1 (HEAD -> main, origin/main, origin/HEAD) Merge pull request #1 from jameshowison/new-feature
|\
| * ffb601d (origin/new-feature, new-feature) added extra
@@ -180,7 +182,7 @@ jlh5498@educcomp04:~/github_repos/i320_test3,,\n git log --oneline --abbrev-comm
Or as an image (with coloring as on Edupod Rstudio):
-
+
You can read a little more about how to read these graphs here
