diff --git a/content/contributing.md b/content/contributing.md deleted file mode 100644 index ad04e4a..0000000 --- a/content/contributing.md +++ /dev/null @@ -1,90 +0,0 @@ -# How to contribute changes to somebody else's project - -```{objectives} -- Avoid frustration and surprises by first discussing and then coding. -``` - -```{instructor-note} -- 15 min teaching/discussion -``` - - -## Contributing very minor changes - -- Clone or fork+clone repository -- Create a branch -- Commit and push change -- Open a pull request or merge request - - -## If you observe an issue and have an idea how to fix it - -- Open an issue in the repository you wish to contribute to -- Describe the problem -- If you have a suggestion on how to fix it, describe your suggestion -- Possibly **discuss and get feedback** -- If you are working on the fix, indicate it in the issue so that others know that somebody is working on it and who is working on it -- Submit your fix as pull request or merge request which references/closes the issue - -```{admonition} Motivation -- **Inform others about an observed problem** -- Make it clear whether this issue is up for grabs or already being worked on -``` - - -## If you have an idea for a new feature - -- Open an issue in the repository you wish to contribute to -- In the issue, write a short proposal for your suggested change or new feature -- Motivate why and how you wish to do this -- Also indicate where you are unsure and where you would like feedback -- **Discuss and get feedback before you code** -- Once you start coding, indicate that you are working on it -- Once you are done, submit your new feature as pull request or merge request which references/closes the issue/proposal - -```{admonition} Motivation -- **Get agreement and feedback before writing 5000 lines of code** which might be rejected -- If we later wonder why something was done, we have the issue/proposal as - reference and can read up on the reasoning behind a code change -``` - - -## WIP (work in progress) merge requests and draft pull requests - -- Convention: Pull requests or merge requests starting with "WIP" or "Draft" are not to be merged yet -- They are there to **collect feedback on unfinished work** -- On GitHub you can create [draft pull requests](https://github.blog/2019-02-14-introducing-draft-pull-requests/) - which cannot be merged until marked ready for review. -- Also GitLab offers same mechanism (merge request starting with "WIP" or "Draft") - -```{admonition} Motivation -- Collect feedback before it is finished and before it becomes more difficult to change -- Communicate to others what is partially done if it affects their work -``` - - -## Licenses matter - -- If you submit code that is derivative work or code somebody else wrote, clarify license -- If you receive pull requests with a lot of code, **clarify its license and - copyright** with the submitter, before merging - - -## How to make sure that you don't merge malicious code - -(this is typically not a problem for most of us but can be a problem for some) - -- Since commit hashes depend on all their parents you cannot modify the past - without all future hashes changing -- Projects like or - have to be extremely careful what they accept -- Browse the code changes before merging them -- If you get an extremely large changeset, ask for more information -- Possibly verify whether the submitter is not trying to impersonate somebody you know -- Git commits can be PGP signed to verify authenticity - - -```{keypoints} -- Communicate and discuss before coding massive changes. -- **Cross-reference discussions, proposals, and code changes**. -``` diff --git a/content/forking-workflow-old.md b/content/forking-workflow-old.md deleted file mode 100644 index bc52c9b..0000000 --- a/content/forking-workflow-old.md +++ /dev/null @@ -1,525 +0,0 @@ -# Forking workflow - -```{objectives} -- Get a mental representation of what is happening on GitHub/GitLab. -- Get comfortable with the forking workflow. -``` - -```{instructor-note} -- 30 min teaching -- 30 min exercises -``` - - -## Forking layout - -```{figure} img/forking/forking-overview.svg -:alt: Forking workflow -:width: 50% - -Forking workflow. **Red** is the central repository, where only -owners have access. **Green** are *forks* on GitHub (copy for a -single user to work on). **Blue** are local copies where contributors -work on their own computer. -``` - -In the **forking layout**, again we call one repository the "central" -repository but people push to **forks** (their own copies of the -repository on GitHub/GitLab/Bitbucket). - -Features: - -- **Anybody can propose contributions without asking for advance permission** - (to public projects). -- Maintainer still has **full control over what is merged**. -- Contributors now have **more than one remote** to work with. - -This is used by almost all large (and small) open-source projects -these days. Real life examples: - -- [NumPy](https://numpy.org/devdocs/dev/index.html) -- [JupyterLab](https://github.com/jupyterlab/jupyterlab) - -```{discussion} Discussion: Why do we create a fork and not only a clone? -- It is not easy to show my changes on my computer to somebody else. -- The maintainer cannot pull from my laptop. -- The cloud provider is a trusted place to pull from and allows review before pulling. -- Backup. -``` - - -## Working with multiple remotes - -In the forking layout described above we work with **multiple remotes**, -in this case **two remotes**: One remote refers to the "central" repository, and the other -remote refers to the fork. - -- There is nothing special about the name `origin`. The `origin` is an alias/placeholder (think of "sticky note" referring to an URL). -- We can name these aliases as we like. -- We can add and remove remotes: - ```console - $ git remote add upstream https://github.com/project/project.git - $ git remote rm upstream - - $ git remote add group-repo https://example.com/exciting-project.git - $ git remote rm group-repo - - $ git remote add upstream https://github.com/project/project.git - $ git remote add downstream https://github.com/userX/project.git - ``` - -- To see all remotes: - ```console - $ git remote --verbose - ``` - -```{warning} -**We will work with a new repository for this exercise!** - -For this exercise we will fork a different repository compared to earlier today. -Please step out of the repository and check that you fork the **forking**-workflow-exercise. -``` - - -## Exercise - -We are working on combining the steps into one exercise. - - -## Exercise preparation - -``````{prereq} Exercise preparation -`````{tabs} - ````{tab} Part of team/exercise room - - **Maintainer (team lead)**: - - Create an exercise repository by - [generating from a template](https://help.github.com/en/articles/creating-a-repository-from-a-template) - using this template: - called `forking-workflow-exercise` - - In this case we **do not add collaborators** to the repository (this is the point of this example). - - Share the link to the newly created repository with your group. - - **Learners in exercise team**: Fork the newly created repository (not the - "coderefinery" one) and then **clone your fork**. - ```` - - ````{tab} Following on your own - The instructors are the **maintainers**. All watchers are - **collaborators**. - - We create(d) these the day before hopefully. **Choose only one to - work with**: - - Not recorded: - (this - will not be shown on stream or recorded in our videos, but is be public on - the internet until it is deleted) - - Recorded: - - (this will be shown on stream and recorded, **your username and comments - may appear in the recorded video on YouTube**) - - Here we don't need your GitHub usernames because the point of this exercise - is to show that we can collaborate without granting write permissions. - - Learners following on their own: Fork one of these two repositories - and then **clone your fork** to your computer. - ```` -````` -`````` - - -## Exercise: Part 1 - creating a pull request - -```{exercise} Distributed-1: Fork a repository and create a pull request -As an example we will collaboratively develop a cookbook for taco recipes, -inspired by [tacofancy](https://github.com/sinker/tacofancy). - -**Objectives**: -- Learn how to fork, modify the fork, and open a pull request towards the central repository. -- Learn how to update your fork with changes that others have already made to the - forked repository. - -**Exercise**: -- Maintainer prepares an exercise repository (see above; this will take 5-10 minutes). -- **Learners work on steps A-F** (15-20 minutes). -- There are two optional steps after step E for those who want more. -- After step E you take a break or help others. - Please ask questions both during group work and in the collaborative document. -- **We will review the pull requests together** - and then update forks. -``` - -Before and after each action you take, run the following informational -commands. Carefully observe what happens, especially in `git graph`: - -- `git graph` - almost every time. As a reminder, to define `git graph` use: - ```console - $ git config --global alias.graph "log --all --graph --decorate --oneline" - ``` -- `git status` - when you modify files. - - -### Step A: Fork and clone - -First fork the exercise repository (please carefully check with your exercise group -which repository you should fork). - -```{figure} img/forking/how-to-fork.png -:class: with-border - -How to fork. -``` - -Then **clone your fork** to your computer. The repository URL -should include your username. **Clone using the SSH path you get from -the webpage, not the https URL** from the web browser. The URL should start with -`git@github.com:`. Otherwise, you won't be able to push later. - -````{admonition} Pictorial representation of this step ---- -class: dropdown ---- -Here is a pictorial representation of this part: - -```{figure} img/forking/forking-1.svg - -Forking followed by cloning. -``` - -This is how it looks after we fork: - -```{figure} img/forking/github-remote-01.svg - -central -``` - -```{figure} img/forking/github-remote-01.svg - -fork -``` - -- A fork is basically a (bare) clone. -- The forked repo and the fork are in principle independent repositories. -- When forking we copy all commits, all branches. - -After we clone the fork we have three in principle independent repositories: - -```{figure} img/forking/github-remote-01.svg - -central -``` - -```{figure} img/forking/github-remote-01.svg - -fork -``` - -```{figure} img/forking/github-local-01.svg - -local -``` -```` - - -### Step B: Open an "issue" as a change proposal - -Before we start any coding, open a new "Issue" on the central repository as a -"proposal" where you describe your idea for a recipe with the possibility to -collect feedback from others. After creating this issue note the issue number. -We will later refer to this issue number. - -Discuss why it can be useful to open an issue before -starting the actual coding. - - -### Step C: Modify and commit - -Before we do any modification, we create a new branch and switch to it: this is -a good reflex and a good practice. Choose a branch name which is descriptive of -its content. For example: - -```console -$ git branch myname-feature # describes both who it belongs to and the purpose -$ git switch myname-feature -``` - -**On the new branch create a new file** which will hold your recipe, -for instance `traditional_coderefinery_tacos.md` (but change the name). You can get inspired -[here](https://github.com/sinker/tacofancy/tree/master/full_tacos). Hopefully we all use different -file names, otherwise we will experience conflicts later (which is also interesting!). - -There is also a file called `test.py` which will automatically verify whether your recipe contains the string -"taco" (case insensitive). This is there to slowly introduce us to automated testing. - -Once you are happy with your recipe, commit the change and in your commit -message **reference the issue** which you have opened earlier with "this is my -commit message; closes #N" (use a more descriptive message and replace N by the -actual issue number from step B). - -````{admonition} Pictorial representation of this step ---- -class: dropdown ---- -And here is a picture of what just happened: - -```{figure} img/forking/github-remote-01.svg - -central -``` - -```{figure} img/forking/github-remote-01.svg - -fork -``` - -```{figure} img/forking/github-local-02.svg - -local -``` -```` - - -### Step D: Push your changes to the fork - -Now push your new branch to your fork. Your branch is probably called something -else than "myname-feature". Also verify where "origin" points to. - -```console -$ git push origin myname-feature -``` - -````{admonition} If you get a password request for https://github.com when you try to push ---- -class: warning, dropdown ---- -Probably you cloned with the HTTPS URL (see `git remote -v` to -confirm). You can change this to SSH by going to the repository page, -clicking "Code", copying the SSH URL (starts with `git@github.com:`), -and then updating the URL with: - -```console -$ git remote set-url origin REPOSITORY-URL -``` -```` - -````{admonition} Pictorial representation of this step ---- -class: dropdown ---- -```{figure} img/forking/github-remote-01.svg - -central -``` - -```{figure} img/forking/github-remote-02.svg - -fork -``` - -```{figure} img/forking/github-local-03.svg - -local -``` -```` - - -### Step E: Open a pull request - -Then file a pull request from the branch on your fork towards the main branch on the central repository. - -````{admonition} Pictorial representation for steps D and E ---- -class: dropdown ---- -```{figure} img/forking/forking-2.svg - -Push followed by a pull request. -``` - -A pull-request means: "please review my changes and if you agree, merge them with a mouse-click". - -Once the pull-request is accepted, the change is merged: - -```{figure} img/forking/github-remote-03.svg - -central -``` - -```{figure} img/forking/github-remote-02.svg - -fork -``` - -```{figure} img/forking/github-local-03.svg - -local -``` -```` - -### Step F: View your pull request - -Go to the central repository, and list all pull requests and view your your pull request. -Remember that the pull request is created on the original repostory. - -**Wait here** until we integrate all pull requests into the central repo -together. - -Observe how the issues automatically close after the pull requests are merged -(provided the commit messages contain [the right keywords](https://help.github.com/en/articles/closing-issues-using-keywords)). - -```{exercise} (optional) Distributed-2: Send a conflicting pull request -If you complete parts A-E much earlier than others, try to open another pull request -where you anticipate a conflict with your first pull request. -``` - -```{exercise} (optional) Distributed-3: Making changes to your pull request after it has been opened. -You can do that by pushing **additional commits to the same branch** where you opened the pull -request from. Observe how they end up added to your pull request. -``` - - -## Exercise: Part 2 - code review and merging changes - -**We do this step together**. The instructor shows a submitted -pull request, discusses what features to look at, and how to discuss and review. - -At the same time, maintainers can review open pull requests from their exercises groups. - - -```{exercise} (optional) Distributed-4: Squash merge a pull request -If you complete this exercise much earlier than others, create a new pull -request with two or more commits. - -Then, when reviewing the change as maintainer, accept these with "Squash and -merge" and later compare the source and target repositories/branches how they -differ after the small commits got squashed into one. -``` - - -## Exercise: Part 3 - Updating forks - -We do this part **after the contributions from all participants have been -integrated**. - -Once this is done, practice to update your fork with the -merged changes from others and verify that you got the files created by other participants. - -Make sure that the contributions from other participants are not only on your -local repository but really also end up in your fork. - -On GitHub it is possible to update the fork by pressing a button (see -screenshot below): - -```{figure} img/forking/fetch-and-merge.png -:alt: Updating the fork via GitHub web interface - -Updating the fork via GitHub web interface. -``` - -````{admonition} Updating the fork using the command line ---- -class: dropdown ---- -Remotes are aliases. We can use the URLs a remote directly. -instead of aliases like `origin` or `upstream`. - -Here we pull from the central repo and push to our fork: -```console -$ git switch main -$ git pull CENTRAL-REPOSITORY-URL main -$ git push FORK-URL main -``` - -Here is a pictorial representation of this part: -```{figure} img/forking/forking-3.svg - -Pull followed by push to a different remote. -``` -```` - -````{admonition} Updating the fork using the command line (longer version) ---- -class: dropdown ---- -Below is a step by step recipe with pictorial representations which hopefully -makes clear what happens in each step. - -```console -$ git remote add central CENTRAL-REPOSITORY-URL -$ git fetch central -``` - -```{figure} img/forking/github-remote-03.svg - -central -``` - -```{figure} img/forking/github-remote-02.svg - -fork -``` - -```{figure} img/forking/github-local-04.svg - -local -``` - -```console -$ git switch main -$ git merge central/main -``` - -```{figure} img/forking/github-remote-03.svg - -central -``` - -```{figure} img/forking/github-remote-02.svg - -fork -``` - -```{figure} img/forking/github-local-05.svg - -local -``` - -```console -$ git push origin main -``` - -```{figure} img/forking/github-remote-03.svg - -central -``` - -```{figure} img/forking/github-remote-04.svg - -fork -``` - -```{figure} img/forking/github-local-06.svg - -local -``` -```` - ---- - -```{figure} img/forking/remote.jpg -``` -- Luke Skywalker: *You know, I did feel something. I could almost see the remote.* -- Ben Kenobi: *That's good. You've taken your first step into a larger world.* - -[from Star Wars Episode IV - A New Hope] - - -```{discussion} Discussion: Always create a feature branch -**For each pull request create a new branch**. Motivation: -- Limits the risk that commits get accidentally appended to an open pull - request (remember: pull requests are from branch to branch, not from commit - to branch). -- History-rewrite (rebased and/or squashed commits) on the central repository - does not lead to a diverging branch on the fork. -``` diff --git a/content/index.md b/content/index.md index 5d40fe8..a6ef33d 100644 --- a/content/index.md +++ b/content/index.md @@ -51,15 +51,6 @@ code-review.md forking-workflow.md ``` -```{toctree} -:maxdepth: 1 -:caption: Older episodes - -same-repository-old.md -forking-workflow-old.md -contributing.md -``` - ```{toctree} :maxdepth: 1 :caption: Optional episodes diff --git a/content/same-repository-old.md b/content/same-repository-old.md deleted file mode 100644 index b5323dc..0000000 --- a/content/same-repository-old.md +++ /dev/null @@ -1,537 +0,0 @@ -# Collaborating within the same repository - -```{objectives} -- Understand how to collaborate using a centralized workflow. -- Understand the difference between local branch, origin/branch, and remote branch. -``` - -```{instructor-note} -- 30 min teaching -- 30 min exercises -``` - - -## Meaning of "central" in a distributed version control - -In this episode, we will explore the usage of a **centralized workflow** for collaborating online on a project -**within one repository on GitHub**. This means that everyone has -access to that **central repository** - convenient (but doesn't scale to a huge -project). - -In {doc}`the next section `, we will see that Git is -**distributed** version control. -This means that any type of repository links that you can think of can be -implemented - not just "everything connects to one central server". - - - -## Centralized layout - -```{figure} img/forking/centralized.svg -:alt: Centralized layout -:width: 50% - -Centralized layout. **Red** is the repository on GitHub. **Blue** is -where all contributors work on their own computers. -``` - -Features: - -- Typically all developers have both read and write permissions (double-headed arrows). -- Suited for cases where **all developers are in the same group or organization or project**. -- **Everybody who wants to contribute needs write access**. -- Good idea to write-protect the main branch (typically `main` or `master`). - -Real life examples: - -- Within the CodeRefinery team we mostly use this approach: [https://github.com/coderefinery](https://github.com/coderefinery) -- [https://github.com/ropensci/plotly](https://github.com/ropensci/plotly) - - -## Exercise - -We are working on combining the steps into one exercise. - - -## Exercise preparation - -In this exercise we will practice collaborative centralized workflow in -groups (but you can also collaborate with us as individual). -One person (**maintainer**) will create the exercise repository, and -**collaborators** will contribute to it. We'll discuss how this leads -to code review and discuss a number of typical pitfalls. - -``````{prereq} Exercise preparation -`````{tabs} - ````{tab} Part of team/exercise room - - Form not too large groups (4-5 persons). - - Each group needs to appoint someone who will host the shared - GitHub repository: the *maintainer*. - This is typically the exercise lead (if available). Everyone else - is a *collaborator*. - - The **maintainer** (one person per group) generates a new repository - from the template - called `centralized-workflow-exercise` (There is no need to tick *"Include all branches"* for this exercise): - ```{figure} img/centralized/generate_repo.png - :alt: Screenshot of generating the exercise repository - :width: 100% - ``` - - Then **everyone in your group** needs their GitHub account to be added as collaborator to the exercise repository: - - Collaborators give their GitHub usernames to their chosen maintainer. - - Maintainer gives the other group members the newly created GitHub repository URL. - - Maintainer adds participants as collaborators to their project (Settings → Manage Access → Invite a collaborator). - ```` - - ````{tab} Following on your own - The instructors are the **maintainers**. All watchers are - **collaborators**. This exercise is only possible during our - livestream courses. - The preparation typically happens already the day before. - - ```{admonition} If you have not requested access (we email about it typically the day before this lesson) - --- - class: dropdown - --- - If you have not yet requested access, could you please [open an - issue in this - repository](https://github.com/cr-workshop-exercises/access-requests/issues/new/choose). - Wait a - minute for staff to add you, then wait for the invite email to arrive and - accept the invitation from the email and "unwatch" repositories (below). - ``` - - **Choose only one to work with** (you must have requested access already, see above) - - - Not recorded: - - (this will not be shown on stream or recorded in our videos, but is public - on the internet until it is deleted) - - Recorded: (this will be shown on stream and recorded, **your username and comments may appear in the recorded video on YouTube**) - ```` -````` - -- **Don't forget to accept the invitation** - - Check - - Alternatively check the inbox for the email account you registered with - GitHub. GitHub emails you an invitation link, but if you don't receive it - you can go to your GitHub notifications in the top right corner. The - maintainer can also "copy invite link" and share it within the group. - -(unwatch)= - -- **Watching and unwatching repositories** - - Now that you are a collaborator, you get notified about new issues and pull - requests via email. - - If you do not wish this, you can "unwatch" a repository (top of - the project page). - - However, we recommend watching repositories you are interested - in. You can learn things from experts just by watching the - activity that come through a popular project. - ```{figure} img/centralized/unwatch.png - :alt: Unwatching a repository - - Unwatch a repository by clicking "Unwatch" in the repository view, - then "Participating and @mentions" - this way, you will get - notifications about your own interactions. - ``` - -`````` - - -## Exercise: Part 1 - creating a pull request - -```{exercise} Centralized-1: Clone a repository, add a file, push changes as a branch, and create a pull request -- Before we start with the exercise, instructor points to the preparation (above). -- Then work on steps A-H. -- There are also optional exercises. -- Before and after each action you take, run the following informational -commands: - - `git graph` - almost every time - - `git status` - when you modify files -``` - -```{callout} Hint for breakout rooms -If the helper in the room is the one who sets up the central repository, they -cannot easily demostrate the steps via screen-sharing as the repository's maintainer. A -good alternative is to have one of the learners screen-share and get advice on the -steps from other learners and helpers! -``` - - -### Step A. Clone your maintainer's group repository - -```console -$ git clone REPOSITORY-URL centralized-workflow-exercise -``` - -Where `REPOSITORY-URL` is the repository created by the exercise -maintainer. - -**Clone using the SSH path** you get from the webpage (the one that starts with -`git@github.com:`), not the one that starts with `https://github.com`. -Otherwise, you won't be able to push later. - -````{admonition} Representation of what happens when you clone ---- -class: dropdown ---- -```{figure} img/centralized/01-remote.svg - -remote or central -``` - -```{figure} img/centralized/01-local.svg - -local -``` - -Here and in what follows, "c1" is a commit, "b1" etc. are commits on side branches -and "m1" is a merge commit. - -- We clone the entire history, all branches, all commits. In our case, we have one branch (we did not include *all branches* when creating our repository from template) and we have only one commit (*initial commit*). -- `git clone` creates pointers `origin/main` so you can see the branches of the origin. -- `origin` refers to where we cloned from. -- `origin` is a shortcut for the full URL. -- `origin/main` is a read-only pointer. -- The branches starting with `origin/` only move during `git pull` or `git fetch` or `git push`. -- Only `git pull` or `git fetch` or `git push` require network. -- All other operations are local operations. -```` - - -### Step B. Change directory into the newly created directory - -```console -$ cd centralized-workflow-exercise -``` - -Try to find out where this repository was cloned from using `git remote -v`. - - -### Step C. Create a branch `yourname-somefeature` pointing at your commit - -Create a branch from the current `main`. Also adapt "yourname-somefeature" to a better name: - -```console -$ git branch yourname-somefeature main -$ git switch yourname-somefeature -``` - -The `yourname-` prefix has no special meaning here (not like `origin/`): it is just part of a -branch name to indicate who made it. - - -### Step D. Create a file with a unique name, e.g.: `yourusername.txt` - -In this file share your favourite cooking recipe or haiku or Git trick or -whatever (we will push soon to a public repository so don't share something you -don't want to become public for the duration of the exercise). - - -### Step E. Stage and commit the change - -```console -$ git add yourusername.txt -$ git commit -``` - -````{admonition} The commit only exists locally ---- -class: dropdown ---- -```{figure} img/centralized/01-remote.svg - -remote or central -``` - -```{figure} img/centralized/04-local.svg - -local (read figure left to right) -``` -```` - - -### Step F. Push your change as a new branch - -```console -$ git push origin -u yourname-somefeature -``` - -````{admonition} If you get a password request for https://github.com when you try to push ---- -class: warning, dropdown ---- -Probably you cloned with the HTTPS URL (see `git remote -v` to -confirm). You can change this to SSH by going to the repository page, -clicking "Code", copying the SSH URL (starts with `git@github.com:`), -and then updating the URL with: - -```console -$ git remote set-url origin SSH-REPOSITORY-URL -``` -```` - -````{admonition} Now the commit also exists on the remote repository ---- -class: dropdown ---- -```{figure} img/centralized/04-remote.svg - -remote or central (read figure left to right) -``` - -```{figure} img/centralized/04-local.svg - -local (read figure left to right) -``` -```` - -```{admonition} Meaning of -u ---- -class: dropdown ---- -The `-u` or `--set-upstream` will connect the local branch with the newly created upstream/remote branch -and track it. This has the following advantages: -- If you from here on only type `git push` or `git pull` without branchname, Git will know what branch you - refer to (depending also on your Git configuration). However, we still recommend to explicitly type where - you want to push/pull to/from and which branch explicitly. -- When you type `git status`, Git will inform you whether your local branch is ahead or behind the upstream branch - that it tracks. - -However, also without the `-u` this step and the rest of the exercise will -work. The fact that the local and remote branch are not connected is not a -problem if you explicitly type out the remote and branch name every time. -``` - - -### Step G. Browse the network of branches and commits - -After you have pushed your branch and other participants have too, browse the -network of branches and commits (on GitHub click on Insights -> Network) and -discuss what you see. - - -### Step H. Submit a pull request - -Submit a pull request from your branch towards the `main` branch. -Do this through the web interface. - -Meaning of a pull request: think of it as change proposal. In a popular project, it means that anyone can -contribute with *almost no work* on the maintainer's side - a big win. - -There are **several options to open a pull request**: -- Follow the link printed to terminal output when git-pushing a branch to GitHub/GitLab -- Visit the GitHub repository in the browser after pushing the branch and click on the green button "Compare & pull request" -- Click on "Pull requests" on top of the GitHub repository and either "Compare & pull request" or "New pull request" -- Click on "Branches" and then "New pull request" from the respective branch - - -## Exercise: Part 2 - code review and merging changes - -```{exercise} Centralized-2: Merge the pull requests (together) -- **We do step 2A and 2B together** (instructor demonstrates, and everybody follows along in their repositories). -``` - -```{instructor-note} -At this stage it might be good to show how to submit and how to review a pull request. -- When co-teaching change roles and switch screenshares also. -- Discuss what you look at when submitting. -- Discuss what you look at when reviewing. -``` - - -### Step 2A. Discuss and accept pull requests - -**We do this step together on the main screen (in the main room) or on stream**. The instructor shows a submitted -pull request, discusses what features to look at, and how to discuss and review. - -At the same time, helpers can review open pull requests from their exercises groups. - -````{admonition} Once the pull-request is accepted, the change is merged ---- -class: dropdown ---- -```{figure} img/centralized/06-remote.svg - -remote or central -``` - -```{figure} img/centralized/04-local.svg - -local -``` -```` - -Finally also discuss the "network" on GitHub. - -```{instructor-note} -At this stage demonstrate how to suggest small changes to pull/merge requests: -- [GitHub](http://haacked.com/archive/2019/06/03/suggested-changes/) -- [GitLab](https://docs.gitlab.com/ee/user/project/merge_requests/reviews/suggestions.html) -``` - -```{discussion} -**Naming** - -- In GitLab or BitBucket these are named **merge requests**, not **pull requests**. -- Which one do you feel is more appropriate and in which - context? (The name **pull request** may make more sense in the forking workflow: next episode). -- It can be useful to think of them as **change proposals**. - -**Pull requests can be used for code review** - -- We recommend that pull requests are reviewed by someone else in your group. -- Collaborative learning -- OK if students and junior researchers review senior researchers -- In our example everyone has write access to the "central" repository. - -**Pull requests are from branch to branch** - -- They originate from a source branch and are directed towards a branch. -- Not from commit to branch. -- Pull requests create new commits on the target branch. -- They do not create new branches. - -**Protected branches** - -- A good setting for large projects is to make the `main` branch **protected** and all changes to it have to go - through code review. -- Centralized workflow with protected branches is a good setup for many projects. - -**Read more** - -- This is a great resource: [Practical git PRs for small teams](https://scicomp.aalto.fi/scicomp/practical-git-prs/) -``` - - -### Step 2B. Update your local copy - -Your branch `yourname-somefeature` is not needed anymore but more importantly, -you need to sync your local copy: **Everybody needs to do this step in their -exercise repository** but we do this together in the main room so that we can -discuss this step and ask questions. - -```console -$ git switch main -$ git pull origin main -``` - -```{figure} img/centralized/06-remote.svg - -remote or central -``` - -```{figure} img/centralized/07-local.svg - -local -``` - -## Optional exercises - -```{exercise} (optional) Centralized-3: Cross-referencing issues using "#N" -We will submit another change by a pull request but this time we will **first create an issue**. - -1. Open an issue on GitHub and describe your idea for a change. This gives - others the chance to give feedback/suggestions. **Note the issue number**, you - will need it in step 3. -2. Create a new branch and switch to it. -3. On the new branch create a commit and in the commit message write what you - did, but also add that this "closes #N" (replace N by the actual issue number from step 1). -4. Push the branch and open a new pull request. If you forgot to refer to the - issue number in step 3, you can still refer to it in the pull request - form (add a "closes #N" to the title or description). -5. Note how now commits, pull requests, and issues can be cross-referenced by including `#N`. -6. Notice how after the pull request is merged, the issue gets automatically - closed. This only happens for certain keywords like `closes` or `fix`. -7. Discuss the value of cross-referencing them and of auto-closing issues - with commits or pull requests. - -See also the [GitHub documentation](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) -for more examples. -``` - -````{exercise} (optional) Centralized-4: Why did we create a feature branch "yourname-somefeature"? (exercise/discussion) - Pushing directly to the main branch is perfectly fine for simple personal projects - - the pull-request workflows covered here are for larger projects or for collaborative development. - Guidelines for simpler workflows are given in the - [how much Git is necessary?](https://coderefinery.github.io/git-intro/level/) episode of the git-intro lesson. - - In collaborative development, whenever we update our repository we create a new branch - and create a pull-request. Let's now imagine that everyone in your group (or one person on two different clones) - makes a new change (create a new file) - but without creating a new branch. - - 1. You all create a new file in the main branch, stage and commit your change locally. - 2. Try to push the change to the upstream repository: - - ```console - $ git push origin main - ``` - You probably see something like this: - - ```console - $ git push - - To https://github.com/user/repo.git - ! [rejected] main -> main (non-fast-forward) - error: failed to push some refs to 'https://github.com/user/repo.git' - To prevent you from losing history, non-fast-forward updates were rejected - Merge the remote changes (e.g. 'git pull') before pushing again. See the - 'Note about fast-forwards' section of 'git push --help' for details. - ``` - - - The push only worked for one participant (one clone). - - Discuss why push for everybody else in this group was rejected? - - ```{solution} - The push for everyone except one person fails because they are missing one - commit in their local repository that exists on the remote. They will first - need to pull the remote changes before pushing their own, which will usually - result in a merge commit. - ``` -```` - -````{discussion} Discussion: How to make changes to remote branches - If there is a remote branch `somefeature`, we can create a local branch and start tracking `origin/somefeature` like this: - ```console - $ git switch somefeature - ``` - - Once we track a remote branch, we can pull from it and push to it: - ```console - $ git pull origin somefeature - $ git push origin somefeature - ``` - - We can also delete remote branches: - ```console - $ git push origin --delete somefeature - ``` -```` - -```{callout} Creating pull requests from the command line -There are several possibilties: -- -- -- -``` - -```{callout} How you can find out in which repositories you are a collaborator -Visit where you will see -an overview of all repositories you have write access to. -``` - -```{callout} GitHub/GitLab organizations -- Projects often start under a personal namespace. -- If you want the project to live beyond the interest or work time of one person, - one can share projects under an "organization". -- You can then invite collaborators to an organization. -- This is what we do in the CodeRefinery project: -``` - -```{keypoints} -- Centralized workflow is often used for remote collaborative work. -- `origin` refers to where you cloned from (but you can relocate it). -- `origin/mybranch` is a read-only pointer to branch `mybranch` on `origin`. -- These read-only pointers only move when you `git fetch`/`git pull` or `git push`. -```