From 5acd4ae15ac563caccc09bfab5ec8b5e5c23ed8b Mon Sep 17 00:00:00 2001 From: Brendan Forster Date: Tue, 20 Nov 2018 15:35:16 -0400 Subject: [PATCH] update documentation and README for Linux support (#287 #354 #537 #552 #592 #605 #656 #667 #836 #838 #839 #843 #864 #910 #956 #984 #1079) --- .github/ISSUE_TEMPLATE/bug_report.yaml | 4 - .github/ISSUE_TEMPLATE/installation-issue.md | 21 +++ README.md | 160 +++++++++++++------ docs/installation.md | 15 ++ docs/known-issues.md | 62 +++++++ docs/process/publishing-linux-releases.md | 154 ++++++++++++++++++ 6 files changed, 365 insertions(+), 51 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/installation-issue.md create mode 100644 docs/process/publishing-linux-releases.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index f71cfe29e20..758ddff8beb 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -1,10 +1,6 @@ name: 🐛 Bug Report description: File a bug report body: - - type: markdown - attributes: - value: | - Thanks for filing a bug report! This issue tracker is for [GitHub Desktop](https://desktop.github.com). Please search the issue tracker to see if there is an existing issue for the problem you are experiencing. If you are experiencing issues with the Linux fork of GitHub Desktop please open an issue [in its repository](https://github.com/shiftkey/desktop). If you are experiencing issues with github.com please [contact GitHub Support](https://support.github.com/). - type: textarea id: the-problem attributes: diff --git a/.github/ISSUE_TEMPLATE/installation-issue.md b/.github/ISSUE_TEMPLATE/installation-issue.md new file mode 100644 index 00000000000..0d2175f7faa --- /dev/null +++ b/.github/ISSUE_TEMPLATE/installation-issue.md @@ -0,0 +1,21 @@ +--- +name: "\U0001F4BB Installation issue" +about: Report a problem when installing the application +title: '' +labels: '' +assignees: '' + +--- + +### Operating System/Distribution + +Which distribution of Linux are you using? + +### Installer + +Which version of the app? +Which installer type? + +### What happened? + +Provide as much detail as possible. Error messages or output are extremely useful. diff --git a/README.md b/README.md index 2e3eb3bf644..17d59fe50b4 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,6 @@ -# [GitHub Desktop](https://desktop.github.com) +# [GitHub Desktop](https://desktop.github.com) - The Linux Fork + +[![CI](https://github.com/shiftkey/desktop/actions/workflows/ci.yml/badge.svg)](https://github.com/shiftkey/desktop/actions/workflows/ci.yml) [GitHub Desktop](https://desktop.github.com/) is an open-source [Electron](https://www.electronjs.org/)-based GitHub app. It is written in [TypeScript](https://www.typescriptlang.org) and @@ -16,78 +18,142 @@ uses [React](https://reactjs.org/). /> -## Where can I get it? +## What is this repository for? + +This repository contains specific patches on top of the upstream +`desktop/desktop` repository to support Linux usage. + +It also publishes [releases](https://github.com/shiftkey/desktop/releases) for various Linux distributions: + + - AppImage (`.AppImage`) + - Debian (`.deb`) + - RPM (`.rpm`) + +## Installation via package manager + +You can use your operating system's package manager to install `github-desktop` and +keep it up to date on Debian and RPM-based distributions. + +### Debian/Ubuntu + +There are two APT package feeds available, both hosted in the US. You only need +to add one or the other here, as both of these are generated based on the +releases from this repository. + +#### [@shiftkey](https://github.com/shiftkey) package feed + +```sh +wget -qO - https://apt.packages.shiftkey.dev/gpg.key | gpg --dearmor | sudo tee /usr/share/keyrings/shiftkey-packages.gpg > /dev/null +sudo sh -c 'echo "deb [arch=amd64 signed-by=/usr/share/keyrings/shiftkey-packages.gpg] https://apt.packages.shiftkey.dev/ubuntu/ any main" > /etc/apt/sources.list.d/shiftkey-packages.list' +``` + +#### [@mwt](https://github.com/mwt) package feed + +```sh +wget -qO - https://mirror.mwt.me/shiftkey-desktop/gpgkey | gpg --dearmor | sudo tee /usr/share/keyrings/mwt-desktop.gpg > /dev/null +sudo sh -c 'echo "deb [arch=amd64 signed-by=/usr/share/keyrings/mwt-desktop.gpg] https://mirror.mwt.me/shiftkey-desktop/deb/ any main" > /etc/apt/sources.list.d/mwt-desktop.list' +``` + +#### Installation + +Once you have a feed configured, run this command to install the application: + +```sh +sudo apt update && sudo apt install github-desktop +``` + +### Red Hat/CentOS/Fedora + +There are two RPM package feeds available, both hosted in the US. You only need +to add one or the other here, as both of these are generated based on the +releases from this repository. + +#### [@shiftkey](https://github.com/shiftkey) package feed + +```sh +sudo rpm --import https://rpm.packages.shiftkey.dev/gpg.key +sudo sh -c 'echo -e "[shiftkey-packages]\nname=GitHub Desktop\nbaseurl=https://rpm.packages.shiftkey.dev/rpm/\nenabled=1\ngpgcheck=1\nrepo_gpgcheck=1\ngpgkey=https://rpm.packages.shiftkey.dev/gpg.key" > /etc/yum.repos.d/shiftkey-packages.repo' +``` + +#### [@mwt](https://github.com/mwt) package feed + +```sh +sudo rpm --import https://mirror.mwt.me/shiftkey-desktop/gpgkey +sudo sh -c 'echo -e "[mwt-packages]\nname=GitHub Desktop\nbaseurl=https://mirror.mwt.me/shiftkey-desktop/rpm\nenabled=1\ngpgcheck=1\nrepo_gpgcheck=1\ngpgkey=https://mirror.mwt.me/shiftkey-desktop/gpgkey" > /etc/yum.repos.d/mwt-packages.repo' +``` + +#### Installation -Download the official installer for your operating system: +Once you have a feed configured, run this command to install the application: - - [macOS](https://central.github.com/deployments/desktop/desktop/latest/darwin) - - [macOS (Apple silicon)](https://central.github.com/deployments/desktop/desktop/latest/darwin-arm64) - - [Windows](https://central.github.com/deployments/desktop/desktop/latest/win32) - - [Windows machine-wide install](https://central.github.com/deployments/desktop/desktop/latest/win32?format=msi) +```sh +# if yum is your package manager +sudo yum install github-desktop -Linux is not officially supported; however, you can find installers created for Linux from a fork of GitHub Desktop in the [Community Releases](https://github.com/desktop/desktop#community-releases) section. +# if dnf is your package manager +sudo dnf install github-desktop -### Beta Channel +# if zypper is your package manager +sudo zypper ref && sudo zypper in github-desktop +``` -Want to test out new features and get fixes before everyone else? Install the -beta channel to get access to early builds of Desktop: +#### OpenSUSE - - [macOS](https://central.github.com/deployments/desktop/desktop/latest/darwin?env=beta) - - [macOS (Apple silicon)](https://central.github.com/deployments/desktop/desktop/latest/darwin-arm64?env=beta) - - [Windows](https://central.github.com/deployments/desktop/desktop/latest/win32?env=beta) - - [Windows (ARM64)](https://central.github.com/deployments/desktop/desktop/latest/win32-arm64?env=beta) +There are two RPM package feeds available, both hosted in the US. You only need +to add one or the other here, as both of these are generated based on the +releases from this repository. -The release notes for the latest beta versions are available [here](https://desktop.github.com/release-notes/?env=beta). +#### [@shiftkey](https://github.com/shiftkey) package feed -### Community Releases +```sh +sudo rpm --import https://rpm.packages.shiftkey.dev/gpg.key +sudo sh -c 'echo -e "[shiftkey-packages]\nname=GitHub Desktop\nbaseurl=https://rpm.packages.shiftkey.dev/rpm/\nenabled=1\ngpgcheck=1\nrepo_gpgcheck=1\ngpgkey=https://rpm.packages.shiftkey.dev/gpg.key" > /etc/zypp/repos.d/shiftkey-packages.repo' +``` -There are several community-supported package managers that can be used to -install GitHub Desktop: - - Windows users can install using [winget](https://docs.microsoft.com/en-us/windows/package-manager/winget/) `c:\> winget install github-desktop` or [Chocolatey](https://chocolatey.org/) `c:\> choco install github-desktop` - - macOS users can install using [Homebrew](https://brew.sh/) package manager: - `$ brew install --cask github` +#### [@mwt](https://github.com/mwt) package feed -Installers for various Linux distributions can be found on the -[`shiftkey/desktop`](https://github.com/shiftkey/desktop) fork. +```sh +sudo rpm --import https://mirror.mwt.me/shiftkey-desktop/gpgkey +sudo sh -c 'echo -e "[mwt-packages]\nname=GitHub Desktop\nbaseurl=https://mirror.mwt.me/shiftkey-desktop/rpm\nenabled=1\ngpgcheck=1\nrepo_gpgcheck=1\ngpgkey=https://mirror.mwt.me/shiftkey-desktop/gpgkey" > /etc/zypp/repos.d/mwt-packages.repo' +``` -## Is GitHub Desktop right for me? What are the primary areas of focus? +#### Installation -[This document](https://github.com/desktop/desktop/blob/development/docs/process/what-is-desktop.md) describes the focus of GitHub Desktop and who the product is most useful for. +```sh +sudo zypper ref && sudo zypper in github-desktop +``` -## I have a problem with GitHub Desktop -Note: The [GitHub Desktop Code of Conduct](https://github.com/desktop/desktop/blob/development/CODE_OF_CONDUCT.md) applies in all interactions relating to the GitHub Desktop project. +## Other Distributions -First, please search the [open issues](https://github.com/desktop/desktop/issues?q=is%3Aopen) -and [closed issues](https://github.com/desktop/desktop/issues?q=is%3Aclosed) -to see if your issue hasn't already been reported (it may also be fixed). +### Arch Linux -There is also a list of [known issues](https://github.com/desktop/desktop/blob/development/docs/known-issues.md) -that are being tracked against Desktop, and some of these issues have workarounds. +Arch Linux users can install GitHub Desktop from the [AUR](https://aur.archlinux.org/packages/github-desktop-bin/). -If you can't find an issue that matches what you're seeing, open a [new issue](https://github.com/desktop/desktop/issues/new/choose), -choose the right template and provide us with enough information to investigate -further. +`gnome-keyring` is required and the daemon must be launched either at login or when the X server is started. Normally this is handled by a display manager, but in other cases following the instructions found on the [Arch Wiki](https://wiki.archlinux.org/index.php/GNOME/Keyring#Using_the_keyring_outside_GNOME) will fix the issue of not being able to save login credentials. -## The issue I reported isn't fixed yet. What can I do? +### Cross-Distribution Packages -If nobody has responded to your issue in a few days, you're welcome to respond to it with a friendly ping in the issue. Please do not respond more than a second time if nobody has responded. The GitHub Desktop maintainers are constrained in time and resources, and diagnosing individual configurations can be difficult and time consuming. While we'll try to at least get you pointed in the right direction, we can't guarantee we'll be able to dig too deeply into any one person's issue. +GitHub Desktop is also available cross-platform as a [Flatpak](https://github.com/flathub/io.github.shiftey.Desktop) and [AppImage](https://appimage.github.io/GitHubDesktop/). -## How can I contribute to GitHub Desktop? +### deb-get -The [CONTRIBUTING.md](./.github/CONTRIBUTING.md) document will help you get setup and -familiar with the source. The [documentation](docs/) folder also contains more -resources relevant to the project. +Debian/Ubuntu users can also install directly from this repository using [`deb-get`](https://github.com/wimpysworld/deb-get): `deb-get install github-desktop`. -If you're looking for something to work on, check out the [help wanted](https://github.com/desktop/desktop/issues?q=is%3Aissue+is%3Aopen+label%3A%22help%20wanted%22) label. +## Known issues -## Building Desktop +If you're having troubles with Desktop, please refer to the [Known issues](docs/known-issues.md#linux) +document for guidance and workarounds for common limitations. -To setup your development environment for building Desktop, check out: [`setup.md`](./docs/contributing/setup.md). +If your package manager is still trying to reach PackageCloud, refer to the +[cleanup instructions](docs/known-issues.md#the-packagecloud-package-feed-is-no-longer-working) +for details about migrating away. -## More Resources +## More information -See [desktop.github.com](https://desktop.github.com) for more product-oriented +Please check out the [README](https://github.com/desktop/desktop#github-desktop) +on the upstream [GitHub Desktop project](https://github.com/desktop/desktop) and +[desktop.github.com](https://desktop.github.com) for more product-oriented information about GitHub Desktop. See our [getting started documentation](https://docs.github.com/en/desktop/overview/getting-started-with-github-desktop) for more information on how to set up, authenticate, and configure GitHub Desktop. diff --git a/docs/installation.md b/docs/installation.md index 6681d22a00b..e931a69ab89 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -13,6 +13,15 @@ On Windows you have two options: - Download the `GitHubDesktopSetup.exe` and run it to install it for the current user. - Download the `GitHubDesktopSetup.msi` and run it to install a machine-wide version of GitHub Desktop - each logged-in user will then be able to run GitHub Desktop from the program at `%PROGRAMFILES(x86)\GitHub Desktop Installer\desktop.exe`. +### Linux + +On Linux there are four different package formats available, depending on your +distribution: + + - AppImage (`.AppImage`) + - Debian (`.deb`) + - RPM (`.rpm`) + ## Data Directories GitHub Desktop will create directories to manage the files and data it needs to function. If you manage a network of computers and want to install GitHub Desktop, here is more information about how things work. @@ -25,6 +34,12 @@ GitHub Desktop will create directories to manage the files and data it needs to - `%LOCALAPPDATA%\GitHubDesktop\` - contains the latest versions of the app, and some older versions if the user has updated from a previous version. - `%APPDATA%\GitHub Desktop\` - this directory contains user-specific data which the application requires to run, and is created on launch if it doesn't exist. Log files are also stored in this location. +### Linux + +This varies based on the installer chosen: + + - AppImage, Debian and RPM: `~/.config/GitHub Desktop/` + ## Log Files GitHub Desktop will generate logs as part of its normal usage, to assist with troubleshooting. They are located in the data directory that GitHub Desktop uses (see above) under a `logs` subdirectory, organized by date using the format `YYYY-MM-DD.desktop.production.log`, where `YYYY-MM-DD` is the day the log was created. diff --git a/docs/known-issues.md b/docs/known-issues.md index 2a8d7b89cbe..58987489f63 100644 --- a/docs/known-issues.md +++ b/docs/known-issues.md @@ -11,6 +11,10 @@ - [I get a black screen when launching Desktop](#i-get-a-black-screen-when-launching-desktop) - [Failed to open CA file after an update](#failed-to-open-ca-file-after-an-update) - [Authentication errors due to modified registry entries](#authentication-errors-due-to-modified-registry-entries) +- [Linux](#linux) + - [I get a white screen when launching Desktop](#i-get-a-white-screen-when-launching-desktop) + - [I cannot access repositories under my organization](#i-cannot-access-repositories-under-my-organization) + - [My shell/terminal is not detected and is stuck on "GNOME Terminal"](#my-shellterminal-is-not-detected-and-is-stuck-on-gnome-terminal) # Known Issues @@ -225,3 +229,61 @@ Related issue: [#15217](https://github.com/desktop/desktop/issues/15217) If you see an error that says "Not enough resources are available to process this command" when signing in to GitHub Desktop, it's likely that you have too many credentials stored in Windows Credentials Manager. **Workaround:** open the Credential Manager application, click on Windows Credentials and go through the list to see if there are some you can delete. + +## Linux + +### The PackageCloud package feed is no longer working + +The PackageCloud feed has been closed down. If you are seeing errors about this you should remove the configuration for this feed and refer to the [README](https://github.com/shiftkey/desktop#repositories) +for the new settings. + +#### APT configuration + +``` +sudo rm /etc/apt/trusted.gpg.d/shiftkey-desktop.asc +sudo rm /etc/apt/sources.list.d/packagecloud-shiftkey-desktop.list +``` + +#### RPM configuration + +``` +sudo rm /etc/apt/sources.list.d/packagecloud-shiftkey-desktop.list +``` + +### I get a white screen when launching Desktop + +Electron enables hardware accelerated graphics by default, but some graphics cards have issues with hardware acceleration which means the application will launch successfully but it will be a white screen. If you are running GitHub Desktop within virtualization software like Parallels Desktop, hardware accelerated graphics may not be available. + +**Workaround:** if you set the `GITHUB_DESKTOP_DISABLE_HARDWARE_ACCELERATION` environment variable to any value and launch Desktop again it will disable hardware acceleration on launch, so the application is usable. + +### I cannot access repositories under my organization + +The GitHub Desktop application is an OAuth application, but this fork does not +have the same permissions as the app does on Windows and macOS, which manifests +in a couple of different ways: + + - the "Clone a Repository" view does not show all organization repositories + - pushes to a repository owned by an organization may be rejected with a + generic error message + +The root cause of this is organizations by default will have "OAuth App access +restrictions" enabled, which blocks the GitHub Desktop development app that is +used by this fork. + +**Workaround:** ask your organization admin to [approve access](https://docs.github.com/en/organizations/restricting-access-to-your-organizations-data/approving-oauth-apps-for-your-organization) +to the GitHub Desktop development app. + +If you have not requested the GitHub Desktop development app for this organization, [follow these instructions first](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/requesting-organization-approval-for-oauth-apps). + +### My shell/terminal is not detected and is stuck on GNOME Terminal + +On non-GNOME desktop's the GitHub Desktop application may not correctly set the +environment's shell, despite the shell being selected in the application settings. + +Attempting to launch the shell from the application will show the error +"cannot read property 'path' of undefined". + +**Workarounds:** + +- Option 1: install a second different terminal, switch to it, then switch to the terminal you want to use, and then uninstall the second terminal. +- Option 2: open the application's developer tools and step through the JS calls to correctly set the shell. Further details at https://github.com/shiftkey/desktop/issues/344#issuecomment-1001287110 diff --git a/docs/process/publishing-linux-releases.md b/docs/process/publishing-linux-releases.md new file mode 100644 index 00000000000..76a5648b68a --- /dev/null +++ b/docs/process/publishing-linux-releases.md @@ -0,0 +1,154 @@ +# Publishing Linux Releases + +This document outlines the steps I take once a release has been published from +the main GitHub Desktop project. + +This document assumes you have these remotes configured: + +``` +$ git remote -v +origin https://github.com/shiftkey/desktop (fetch) +origin https://github.com/shiftkey/desktop (push) +upstream https://github.com/desktop/desktop (fetch) +upstream https://github.com/desktop/desktop (push) +``` + +Ensure that `development` and `linux` are up-to-date: + +``` +$ git fetch --all +$ git checkout development +$ git reset upstream/development --hard +$ git push origin development +$ git checkout linux +$ git reset origin/linux --hard +$ git rebase development linux +``` + +We want to ensure our changes work against the current branch, so take some time +to rebase the changes and force push `linux` once you're done. + +``` +$ git push origin linux --force-with-lease +``` + +Wait for the continuous integration tests to pass. If `linux` is not passing the +continuous integration tests we need to investigate and identify why things are +no longer working. + +### 1. Create a branch from the release tag + +Each release tag from the upstream project matches the format `release-X.Y.Z` +where `X.Y.Z` are version numbers. We should create a corresponding branch in +this repository named `linux-release-X.Y.Z` as a starting point for the next +Linux release. + +On the command line, this looks like this (using the `2.1.3` release as an +example): + +``` +$ git checkout -b linux-release-2.1.3 release-2.1.3 +$ git push origin linux-release-2.1.3 -u +``` + +### 2. Open pull request to apply the necessary patches to the new branch + +The first step to cutting a release is to backport the latest fixes to the +release branch: + +``` +$ git checkout -b apply-changes-2.1.3 linux +$ git submodule update +$ git rebase --onto linux-release-2.1.3 development apply-changes-2.1.3 +``` + +Work through the conflicts reported until the branch is cleanly applied to the +previous release. + +When the branch is ready to go, push the branch to the remote: + +``` +$ git push origin apply-changes-2.1.3 -u +``` + +Open a pull request that targets `linux-release-2.1.3`. Review the changes and +ensure the tests pass. + +### 3. Approve and merge PR + +If we're satisifed with the pull request, we can merge the pull request to +update the release branch. + +Ensure **rebase and merge** is used here, as we want to preserve the commit +history as-is without introducing merge commits. + +If there are additional changes that need to go into the release, make sure to +include them + +### 4. Tag the release + +Ensure you are on the latest version that passes all tests: + +``` +$ git checkout linux-release-2.1.3 +$ git pull +``` + +We need to bump the version here to indicate this is not the exact same version +as the original release. The convention we follow is `release-X.Y.Z-linuxA` +where `A` is an auto-incrementing number (starting from 1). + +Update the `version` field in `app/package.json` to this new version. For +example, updating to the first release of `2.1.3` would look like this: + +```diff +diff --git a/app/package.json b/app/package.json +index fbbbb976f..3baaf9e33 100644 +--- a/app/package.json ++++ b/app/package.json +@@ -3,7 +3,7 @@ + "productName": "GitHub Desktop", + "bundleID": "com.github.GitHubClient", + "companyName": "GitHub, Inc.", +- "version": "2.1.0", ++ "version": "2.1.3-linux1", + "main": "./main.js", + "repository": { + "type": "git", +``` + +Commit and push this change to ensure we still pass the CI suite: + +``` +$ git commit -am "bump version for release" +$ git push +``` + +With this passing CI, we can tag this version to indicate this is what we are +releasing: + +``` +$ git tag release-2.1.3-linux1 +``` + +With those things in place, push the changes to the branch as well as the new +tag: + +``` +$ git push --follow-tags +``` + +### 5. Publish to GitHub + +After the tagged build completes, it will have the installers available as +artifacts. Over on Azure Pipelines - switch to the Releases tab and run "Publish +to Beta Channel" with the Snap release disabled +([**#204**](https://github.com/shiftkey/desktop/issues/202) is the tracking +issue for re-enabling that). + +When that is done, there should be a draft release available assigned to the tag +from earlier. Edit the release to add the release notes and checksums. + +**TODO:** it'd be great to have some sort of script to generate the release +notes from the changelog in this "markdown + sections" format, which would save +a lot of manual effort.