From c17e2feb62c2b5cf5bc84f269542143c7a2c4403 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Signe=20Kirk=20Br=C3=B8db=C3=A6k?= Date: Thu, 30 Nov 2023 12:58:21 +0100 Subject: [PATCH 01/13] docs: add tip about issue templates --- entries/git-workflow-guidelines/issues.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/entries/git-workflow-guidelines/issues.md b/entries/git-workflow-guidelines/issues.md index 6c65eda5..eaba4614 100644 --- a/entries/git-workflow-guidelines/issues.md +++ b/entries/git-workflow-guidelines/issues.md @@ -92,14 +92,11 @@ Where: - **Functionality** is the change requested, i.e., the action that the issue is about, and - **Benefit** is the reason why this is needed amd the benefit of this change is. -- Issue templates. Which kinds of issues do we expect? - - Documentation Clarification - - Feature Request - - Bug Report - - Report a Safety Vulnerability - - - - +::: {.callout-tip} -- Advanced: Creating issue templates for your repository? +A way to standardise issues within your project is to utilise [issue templates](). + +For examples of issue templates, see the [issue templates](https://github.com/seedcase-project/.github/tree/main/.github/ISSUE_TEMPLATE) of the Seedcase Organisation on GitHub. + +::: -Maybe: GitHub Action for issues: E.g., label, assign (maybe to someone per default?), is the issue reproducible? From 3ca81c99a1d385de67cc6385be5e905983c92186 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Signe=20Kirk=20Br=C3=B8db=C3=A6k?= Date: Thu, 30 Nov 2023 14:25:48 +0100 Subject: [PATCH 02/13] docs: change codeblocks to default for nicer layout --- entries/git-workflow-guidelines/issues.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/entries/git-workflow-guidelines/issues.md b/entries/git-workflow-guidelines/issues.md index eaba4614..fcb12f49 100644 --- a/entries/git-workflow-guidelines/issues.md +++ b/entries/git-workflow-guidelines/issues.md @@ -63,7 +63,7 @@ For a bug report, it is important to include the steps to reproduce the bug to c You can use the “>” symbol to show the steps. For example: -``` +```default 1. Go to settings > Profile (this would take user to new screen) 2. Tap on More Options > Delete Account ``` @@ -80,7 +80,7 @@ Remember to be specific about the user this change will benefit, and the functio The structure looks like this: -```bash +```default As a I want to so that From ba7397e1ab016abd68420ffd9e3ce2b075f8e3d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Signe=20Kirk=20Br=C3=B8db=C3=A6k?= Date: Thu, 30 Nov 2023 14:39:11 +0100 Subject: [PATCH 03/13] docs: add link to issue templates --- entries/git-workflow-guidelines/issues.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/entries/git-workflow-guidelines/issues.md b/entries/git-workflow-guidelines/issues.md index fcb12f49..9e97a23c 100644 --- a/entries/git-workflow-guidelines/issues.md +++ b/entries/git-workflow-guidelines/issues.md @@ -94,7 +94,7 @@ Where: ::: {.callout-tip} -A way to standardise issues within your project is to utilise [issue templates](). +A way to standardise issues within your project is to use [issue templates](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository) in your repository. For examples of issue templates, see the [issue templates](https://github.com/seedcase-project/.github/tree/main/.github/ISSUE_TEMPLATE) of the Seedcase Organisation on GitHub. From 6d2b167da8e74549c21446ccac5983875efef2c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Signe=20Kirk=20Br=C3=B8db=C3=A6k?= Date: Fri, 1 Dec 2023 08:14:45 +0100 Subject: [PATCH 04/13] docs: add description of prefixes to issue types --- entries/git-workflow-guidelines/issues.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/entries/git-workflow-guidelines/issues.md b/entries/git-workflow-guidelines/issues.md index 9e97a23c..b8597c82 100644 --- a/entries/git-workflow-guidelines/issues.md +++ b/entries/git-workflow-guidelines/issues.md @@ -52,7 +52,7 @@ When creating a feature request, first present the feature you want implemented. If possible, yuo can include a concise suggestion to a solution Things to address include details of the technical implementation, tradeoffs made in design decisions, and caveats and considerations for the future. -To clearly communicate that an issue is a feature request, you can add this to the title of the issue like so: `feature request: `. +To clearly communicate that an issue is a feature request, you can add this to the title of the issue like so: `feature: `. Remember the the title should be concise and clearly communicate the ### Bug Reports @@ -72,6 +72,8 @@ Remember to out your instructions before filing the report to ensure that they r After the reproduction steps, include a description of the expected result (i.e., what *should* happen, whe the steps are followed) as well as the actual results (the bug). When describing the bug, be as specific as you can. It can be helpful to include screenshots or videos here. +You can add the prefix `bug report` to the issue title: `bug report story: `. + ### User Stories One way to structure an issue is in the form of a [user story](https://www.atlassian.com/agile/project-management/user-stories). When writing the issue, this structure helps with explicitly 1) phrasing the issue/change from the the user's perspective, 2) stating the functionality of the change requested, and 3) stating how this will benefit this kind of user. @@ -92,6 +94,8 @@ Where: - **Functionality** is the change requested, i.e., the action that the issue is about, and - **Benefit** is the reason why this is needed amd the benefit of this change is. +In the issue title, you can add the prefix `user story` like so: `user story: `. + ::: {.callout-tip} A way to standardise issues within your project is to use [issue templates](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository) in your repository. From 8a68d79a03223a3177ca4cd85acf52a7c22450b7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Signe=20Kirk=20Br=C3=B8db=C3=A6k?= Date: Fri, 1 Dec 2023 08:31:41 +0100 Subject: [PATCH 05/13] docs: add issues in practice section --- entries/git-workflow-guidelines/issues.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/entries/git-workflow-guidelines/issues.md b/entries/git-workflow-guidelines/issues.md index b8597c82..f9651460 100644 --- a/entries/git-workflow-guidelines/issues.md +++ b/entries/git-workflow-guidelines/issues.md @@ -104,3 +104,7 @@ For examples of issue templates, see the [issue templates](https://github.com/se ::: +## Issues in Practice + +Since issues can be so multifaceted, they can be created in a lot of different ways. In GitHub Docs, how to [create an issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue) in different ways are thoroughly documented. + From 39aec62906baa1389bc99701180e2b0b56a8f61b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Signe=20Kirk=20Br=C3=B8db=C3=A6k?= Date: Fri, 1 Dec 2023 08:32:44 +0100 Subject: [PATCH 06/13] docs: add paneltab with issues using the command line issues using github and issues in vs code are still wips --- entries/git-workflow-guidelines/issues.md | 38 +++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/entries/git-workflow-guidelines/issues.md b/entries/git-workflow-guidelines/issues.md index f9651460..5265a066 100644 --- a/entries/git-workflow-guidelines/issues.md +++ b/entries/git-workflow-guidelines/issues.md @@ -108,3 +108,41 @@ For examples of issue templates, see the [issue templates](https://github.com/se Since issues can be so multifaceted, they can be created in a lot of different ways. In GitHub Docs, how to [create an issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue) in different ways are thoroughly documented. +::: panel-tabset + +### Issues using the Command Line + +To create an issue using the command line, you will need [GitHub CLI](https://cli.github.com/), an open-source command-line interface for GitHub. +If you want to learn more about GitHub CLI, see the [About GitHub CLI](https://docs.github.com/en/github-cli/github-cli/about-github-cli) post in GitHub Docs. + +Once you have GitHub CLI installed, you can create an issue from the command line (when you are within your Git repository) using the following command: + +```bash +gh issue create --title "" --body "" +``` + +`gh issue create` is a subcommand of `gh issue` which creates a new issue. The `--title` and `--body` flags are used to add a title and description to the new issue. Replace `` above with a concise title describing, maybe with a prefix describing the issue type. + +You can also add additional flags to this command, e.g., assignees with the `--assignee` flag: + +```bash +gh issue create --title "" --body "" --assignee @me,my-collaborator +``` + +For the assignee flag, you should use your or your collaborators' GitHub username with an `@` before the first assignee. + +Source: [GitHub Docs](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue#creating-an-issue-with-github-cli) + +Go to GitHub CLI's documentation on [gh issue](https://cli.github.com/manual/gh_issue) for all gh commands related to issues. + +### Issues using GitHub + +If you go to your repository on GitHub, you will find an *Issues* tab. Click this to get a list of all open issues. Here you can search for existing issues as well as create new ones by clicking the `New issue` button. + +WIP: https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue + +### Issues in VS Code + +WIP: https://leonardomontini.dev/manage-issues-vscode-github/ + +::: From 23aca16d6922c2eda96c2fb27c5d2a979d776ff2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Signe=20Kirk=20Br=C3=B8db=C3=A6k?= Date: Fri, 1 Dec 2023 08:33:10 +0100 Subject: [PATCH 07/13] docs: add summary section header --- entries/git-workflow-guidelines/issues.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/entries/git-workflow-guidelines/issues.md b/entries/git-workflow-guidelines/issues.md index 5265a066..1c0af5b1 100644 --- a/entries/git-workflow-guidelines/issues.md +++ b/entries/git-workflow-guidelines/issues.md @@ -146,3 +146,7 @@ WIP: https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-a WIP: https://leonardomontini.dev/manage-issues-vscode-github/ ::: + +## Summary + +- From 9f75695056a54016a81da331d916d285eb0b7ccb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Signe=20Kirk=20Br=C3=B8db=C3=A6k?= Date: Fri, 1 Dec 2023 08:34:09 +0100 Subject: [PATCH 08/13] docs: add prs in practice section --- entries/git-workflow-guidelines/prs.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/entries/git-workflow-guidelines/prs.md b/entries/git-workflow-guidelines/prs.md index 399d6e07..c71ee624 100644 --- a/entries/git-workflow-guidelines/prs.md +++ b/entries/git-workflow-guidelines/prs.md @@ -31,6 +31,17 @@ Your collaborators will be able to add review comments, request changes, contrib PRs also work as documentation, since they will be a part of the repository's history forever. They enable new collaborators to read about the motivation of changes and the conversations your team had about these changes, before they were implemented. +## Pull Requests in Practice + +When you follow the [GitHub flow](index.md#branching-strategy-github-flow) and want to implement changes to your repository, you start by creating a new branch from `main`. Then, you begin implementing the changes on this new branch. As described in the [branching post](branching.md#introduction-to-branches), a branch acts as an isolated container to implement your changes before they are ready to be merged into `main`. Then, you push your changes to the remote repository (potentially on GitHub or GitLab) and create a PR, i.e., you ask your collaborators to review your changes before they can be added to the `main` branch. + +When you create a PR, you will have to add a title to it. Think of this title as an email subject line: It should be concise so that your collaborators will be able to look at the title and know what's going to be in the PR. You should also include a summary of the changes proposed in the PR and, if relevant, a reference to a related issue in your repository (issues are references using a `#`, e.g., `#22`). + +In addition, you need to request *reviewers* to your PRs, i.e., who you want to review your changes. These reviewers will be actively reviewing your PR. You should also add an *assignee*, which is the owner of the PR who is responsible for getting it into a merge-ready state. Most of the time, you will be the assignee of the PRs you create. + +Like with [branching](branching.md#when-to-create-branches-and-how-much-they-should-cover), create one PR for one purpose. The shorter the changes, the easier it will be for your collaborators to review. This will result in faster reviews and faster merging. The commit history of the branch you have created a PR from will appear in chronological order and help your collaborators get an overview of the changes you have made. This is one of the reasons why writing good [commit messages](commits.md#commit-messages) is so important: it enables your collaborators to get a quick overview of the changes you have made. + + ## Review Guidelines So how do you do a review of a pull request? Thankfully GitHub has a From 8d2e6ee6d4d435de0c390984af0fcff36c6706db Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Signe=20Kirk=20Br=C3=B8db=C3=A6k?= Date: Fri, 1 Dec 2023 08:34:33 +0100 Subject: [PATCH 09/13] docs: add tip on creating prs early and drafts --- entries/git-workflow-guidelines/prs.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/entries/git-workflow-guidelines/prs.md b/entries/git-workflow-guidelines/prs.md index c71ee624..18da8730 100644 --- a/entries/git-workflow-guidelines/prs.md +++ b/entries/git-workflow-guidelines/prs.md @@ -41,6 +41,16 @@ In addition, you need to request *reviewers* to your PRs, i.e., who you want to Like with [branching](branching.md#when-to-create-branches-and-how-much-they-should-cover), create one PR for one purpose. The shorter the changes, the easier it will be for your collaborators to review. This will result in faster reviews and faster merging. The commit history of the branch you have created a PR from will appear in chronological order and help your collaborators get an overview of the changes you have made. This is one of the reasons why writing good [commit messages](commits.md#commit-messages) is so important: it enables your collaborators to get a quick overview of the changes you have made. +::: {.callout-tip} + +You don't have to wait until you have fully-incorporated your changes, before you create a PR. + +As noted at[GitHub Universe](https://www.youtube.com/watch?v=vCwuZfK0VG4&list=PL0lo9MOBetEHWqH1OLA0qOL4rPDJLHl15), you should create your PRs early on, as soon as you have incorporated meaningful changes and have an idea of the full implementation, This way, you get your collaborators' feedback on your changes before you have spend a lot of time on your initial implementation idea. Maybe they have some alternative ideas on how to implement these changes, and you can start the discussion early. Furthermore, you ensure that they know what you are working on, so they don't start up a similar implementation in the meantime. + +If your PR is still a work in progress, remember to mark the PR as a [draft](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request#converting-a-pull-request-to-a-draft). + +::: + ## Review Guidelines From d751e7c01522f967057bccad9aff4efda1ac5134 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Signe=20Kirk=20Br=C3=B8db=C3=A6k?= Date: Fri, 1 Dec 2023 08:39:10 +0100 Subject: [PATCH 10/13] docs: add tip on pr templates --- entries/git-workflow-guidelines/prs.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/entries/git-workflow-guidelines/prs.md b/entries/git-workflow-guidelines/prs.md index 18da8730..724c81b9 100644 --- a/entries/git-workflow-guidelines/prs.md +++ b/entries/git-workflow-guidelines/prs.md @@ -51,6 +51,15 @@ If your PR is still a work in progress, remember to mark the PR as a [draft](htt ::: +::: {.callout-tip} + +One way to ensure that a PR incorporates the information you find necessary for your project is to include a PR template in your project. + +A PR templates adds default content to PRs that will show up automatically in the body of the PR. The [GitHub Docs](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository) described how to include PR templates to your repository. + +For examples, see the [PR templates](https://github.com/seedcase-project/.github/tree/main/.github) in the Seedcase Organisation. +::: + ## Review Guidelines From b853c2d9f63d37a95a3f14d5e2b683b5946c508d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Signe=20Kirk=20Br=C3=B8db=C3=A6k?= Date: Fri, 1 Dec 2023 08:40:31 +0100 Subject: [PATCH 11/13] docs: add paneltab on creating prs (very much wip) --- entries/git-workflow-guidelines/prs.md | 31 ++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/entries/git-workflow-guidelines/prs.md b/entries/git-workflow-guidelines/prs.md index 724c81b9..b5426d6f 100644 --- a/entries/git-workflow-guidelines/prs.md +++ b/entries/git-workflow-guidelines/prs.md @@ -60,6 +60,37 @@ A PR templates adds default content to PRs that will show up automatically in th For examples, see the [PR templates](https://github.com/seedcase-project/.github/tree/main/.github) in the Seedcase Organisation. ::: +::: panel-tabset + +### Create a Pull Request from VS Code + +To be able to create pull requests to GitHub from within VS Code, you first need to install the extension [GitHub Pull Requests and Issues](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github). You can find and install this extension by going to the `Extension` view in the left sidebar of VS Code and search for it. + +Once you have installed it, VS Code will prompt you to link to your GitHub account by signing in and giving access. + +Now, in the `Source Control` view, a pull request icon will appear above the commit message box. When you click it, you will switch to the `GitHub Pull Request` view. + +In this view, you can fill our the `TITLE` and `DESCRIPTION` boxes, as well as mark it as a draft, if your work is still a work-in-progress. + +Note: Double check that you are in the correct repository and on the correct branch before you continue to the next step. + +Then, click the `Create` button at the bottom of the sidebar. + +Now, VS Code will show you the pull request on GitHub and in this view, you can add reviewers and assignees. + +Voila, you have now created a pull request! + + + +### Create a Pull Request on GitHub + +Go to . + +### Create a Pull Request using the Command Line + +:warning: I have never done this. Is this a good practice? :warning: + +::: ## Review Guidelines From 62692e30b93140fbfbf59b9f73b782471f408a70 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Signe=20Kirk=20Br=C3=B8db=C3=A6k?= Date: Fri, 1 Dec 2023 08:41:22 +0100 Subject: [PATCH 12/13] docs: WIP add very drafty review in practice section --- entries/git-workflow-guidelines/prs.md | 54 ++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/entries/git-workflow-guidelines/prs.md b/entries/git-workflow-guidelines/prs.md index b5426d6f..edb7bdb6 100644 --- a/entries/git-workflow-guidelines/prs.md +++ b/entries/git-workflow-guidelines/prs.md @@ -130,9 +130,47 @@ a pull request review. {{< video >}} +## Reviews in Practice + +In practice, the review process is iterative. First, the person responsible for the PR (the assignee), creates it and request a review from relevant collaborators. Then, these collaborators review the changes and might suggest changes to the implementation, after which the assignee implements the suggested changes and/or start a discussion on the feedback. This initiates a back-and-forth, where the assignee might request the reviewers to review the updated version of the PR again (and again) until a consensus is reached. + +Good practices as reviewer and assignee: + +- Vote + +As a reviewer, here are a few things to keep in mind when you're giving feedback: + +- Make sure that your feedback is easy to understand and has a clear intention +- If you identify issues, give specific suggestions on what to do differently +- Leave comments: + - Both authors and reviewers can communicate with each other by adding and responding to PR comments. When you review a PR, use comments to point out issues with the proposed changes, suggest changes, and respond to previous comments. Aim for constructive feedback that's precise and easy to understand. Address recipients directly by using their @username. Reference work items by using #workitemID and other PRs by using !pullrequestID. Sometimes, PR authors create comments for themselves for documentation purposes. from: **Comment: Remember to comment.** + + +Re-review --> how to! + +## Merging a PR + +When the reviews have been finalised and suggested changes have been implemented, it is time to merge the new branch into `main`. + +You can merge a PR on GitHub, but also in VS Code or using a Terminal: + +::: panel-tabset + +### Merge PR in VS Code + +Extension: Pull Requests + +### Merge PR using a Terminal + +### Merge PR on GitHub + +For a guide on how to merge a PR on GitHub, go to this [post](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request#merging-a-pull-request) in the GitHub Docs. + +::: + ## Merge Conflicts Most of the time, when you want to merge new changes into the main branch, the merge happens without problems. In these cases, Git can handle the changes between the branches and merge automatically, because the changes are on different lines or in different files. @@ -166,3 +204,19 @@ It is also possible to resolve merge conflicts using a Terminal, see [Resolving In the [GitHub Docs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github) how to resolve a merge conflict on GitHub is described thoroughly. ::: + +## Summary + +- What is a pull request? + - When to request a review +- Pull request best practices + - Naming scheme + - What to include? + - Assignee + reviewer assignment (+ re-request) + - Draft +- What is a review? +- Review best practices + - No single comment - video + - Collected "summary" of review + - +- Handling merge conflicts From d63ebd66ea193ad2f9a606978d83817762b43b72 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Signe=20Kirk=20Br=C3=B8db=C3=A6k?= Date: Mon, 4 Dec 2023 08:58:57 +0100 Subject: [PATCH 13/13] docs: add note on fetch section --- entries/git-workflow-guidelines/branching.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/entries/git-workflow-guidelines/branching.md b/entries/git-workflow-guidelines/branching.md index 3277736b..f276d986 100644 --- a/entries/git-workflow-guidelines/branching.md +++ b/entries/git-workflow-guidelines/branching.md @@ -124,6 +124,8 @@ Note: This is not a widely used extension (~400 downloads as of November 2023) a ::: +:warning: Add section on how to fetch remote branches :warning: + ## Summary - By default, a Git repository has one branch, usually called `main`