Three tools

Issues track work, discussions talk, pull requests change code

Issuework to be done"Login fails on Safari"open or closed,assigned, labelledDiscussiona conversation"How should we handle dates?"questions, ideas, polls;an answer can be markedPull requesta proposed change"Fix the Safari login"commits, review,then a mergeAn issue tracks work. A discussion holds a conversation. A pull request changes the code.Use an issue when something should be done and then closed. Use a discussion when there isnothing to close. Use a pull request to propose commits and have them reviewed.

An issue is work to do. A discussion is a conversation. A pull request is a proposed change.

Three tools · Going deeper

The parts of an issue

Part of an issueWhat it is forTitle and descriptionWhat is wrong or wanted, written in MarkdownAssigneesWho is working on it; up to 10 peopleLabelsCategories such as bug, enhancement, good first issueMilestoneThe release or date it belongs toProjectsThe planning boards it appears onSub-issuesSmaller issues that break a large one into partsComments and reactionsThe conversation; reactions avoid "+1" commentsStateOpen, or closed as completed, not planned or duplicateDiscussions are organised in categories: Announcements, General, Ideas, Polls, Q&A, Show and tell.A discussion can be converted to an issue, and an issue to a discussion.

Assignees, labels, milestones and sub-issues.

Linking

A closing keyword ties a pull request to its issue

Issue #42Login fails on Safaristate: openPull request #57Fix the Safari loginCloses #42linkedmergedIssue #42closed automaticallyWrite "Closes #42" in a pull request, and merging it closes issue 42.The keyword links the two. When the pull request is merged into the default branch, GitHubcloses the issue for you. The keywords are close, fix and resolve, in any of their forms.

Closes #42 in a pull request closes issue 42 when it merges.

Linking · Going deeper

Pull request states and review verdicts

Pull request stateDraftWork in progress: cannot be merged, and code owners are not yet askedOpenReady for reviewMergedIts commits are now in the base branchClosedEnded without merging; it can be reopenedA review ends in one of threeCommentFeedback only: neither approves nor blocksApproveThe reviewer is happy for it to mergeRequest changesIt must be changed before it can mergeReviewers comment on single lines, and can suggest an exact change the author accepts with a click.A pull request compares a head branch with a base branch: "merge add-export into main".

Draft, open, merged, closed; approve or request changes.

Check yourself

Issue #12openPull request #19Fixes #12

The pull request is merged into main. What happens to issue 12?

Pull requests

One page for the change, the talk, the checks and the review

PULL REQUEST: ADD-EXPORT INTO MAINConversationCommitsChecksFiles changedfour tabsA reviewer chooses oneCommentfeedback onlyApproveready to mergeRequest changesmust be fixed firstA pull request gathers a change, its discussion, its checks and its review in one place.Reviewers read the changes, comment on lines and give a verdict. When it is approved and thechecks pass, it can be merged.

Four tabs, and a review that ends in comment, approve or request changes.

Pull requests · Going deeper

Templates, assignments and filters

ToolWhat it doesIssue templates and formsOffer a choice of pre-filled issues: bug report, feature requestPull request templatePre-fills every new pull request with a checklist or headingsWhere they live.github/ISSUE_TEMPLATE/ and .github/pull_request_template.mdAssigneesThe people responsible for the issue or pull requestReviewersThe people asked to review a pull requestPinned issuesUp to three issues kept at the top of the listFilters: type them in the search box of the Issues or Pull requests tabis:issue is:open label:bug assignee:@meis:pr is:open review-requested:@meis:issue no:assignee sort:updated-descTemplates make every report arrive with the facts the maintainers need.

Templates pre-fill, assignees own, filters find.

Notifications

Subscribed, involved or named: that is why you are told

Why you are notifiedyou are watching the repositoryyou took part in the threadsomeone @mentioned youyou were assigned, or asked to reviewNotificationsone streamWhere it arrivesthe inbox on GitHubemailGitHub MobileYou are notified because you subscribed, took part, or were named.Watching subscribes you to a whole repository. Being mentioned, assigned or asked for a reviewsubscribes you to one thread. You can unsubscribe from any thread.

Watching, participating, @mentions and assignments all feed one inbox.

Notifications · Going deeper

Watch settings and the inbox

Watch setting for a repositoryYou are notified ofParticipating and @mentionsOnly threads you are in or named in (the default)All ActivityEverything in the repositoryIgnoreNothing, even when mentionedCustomYour pick of issues, pull requests, releases, discussions, security alertsIn the inboxFilterBy repository, or by reason: assigned, mention, review requestedDone, Save, UnsubscribeClear it, keep it for later, or stop hearing about the threadPer-thread subscribeThe Subscribe button on any issue or pull requestStars do not notify. Watching does.

Participating, All Activity, Ignore or Custom.

Check yourself

Usesa library, and never contributes to itWantsto hear about each new releaseNotits issues or pull requests

Which watch setting gives this person what they want?

Gists, wikis and Pages

A snippet, a manual, a website

Gista snippetone or a few files,shared by a linkpublic or secretWikidocumentationpages beside the code,written in Markdowna tab of the repositoryGitHub Pagesa websitebuilt from filesin a repositoryname.github.ioThree ways to share writing: a snippet, a manual, a website.A gist is for a piece of code or a note too small for a repository. A wiki is for long-formdocumentation that lives next to a project. GitHub Pages turns a repository of HTML or Markdowninto a public website, free, with an optional custom domain.

A gist shares a snippet, a wiki holds documentation, GitHub Pages hosts a website.

Gists, wikis and Pages · Going deeper · 1 of 2

Gists, wikis and Pages compared

GistWikiGitHub PagesIt isa tiny Git repositorya Git repository of pagesa static website hostGood forsnippets, configs, notesguides, design notes, FAQsproject sites, docs, blogsVisibilitypublic, or secret by linkfollows the repositorypublic on the free planHistoryyes: every revisionyes: every page edityes: it is a repositoryBuilt bynothing: shown as isnothing: shown as isJekyll, or an Actions workflowA secret gist is not private: anyone who has the link can read it.Gists can be forked, cloned and embedded in web pages. Pages serves static files only: noserver-side code. The source is a branch, a /docs folder, or the output of a workflow.

A secret gist is not private. Pages serves static files.

Gists, wikis and Pages · Going deeper · 2 of 2

Clue words for collaboration

When the question saysThe answer isRemember"report a bug or track a task"Issueopen, then closed"ask the community a question"DiscussionQ&A, mark an answer"propose and review code changes"Pull requesthead into base"close an issue when the PR merges"Closing keywordCloses #42, Fixes #42"not ready for review yet"Draft pull requestcannot be merged"must be fixed before merging"Request changesa review verdict"pre-fill new issues with a form"Issue template.github/ISSUE_TEMPLATE"who is responsible for this issue"Assigneeup to 10"be told about all activity in a repo"Watch: All Activityor Custom"share a single file or snippet"Gistpublic or secret"documentation alongside the repository"WikiMarkdown pages"host a static website"GitHub Pagesgithub.ioDomain 3 is 10 to 15% of the exam.

Issue, discussion, pull request, gist, wiki and Pages.

Check yourself

Contentone shell script, twenty lines longSharewith a colleague, by sending a linkKeepits history, in case it is edited later

What is the best way to share this?

Lesson complete

You finished “Issues, pull requests and discussions”

Answer the questions along the way to see your score here.

Open in a new tab