docs: reorganize docs pages and CONTRIBUTING.md (#1705)

.github/ISSUE_TEMPLATE/bug_report.md

@@ -14,7 +14,7 @@ A clear and concise description of what the bug is.
 - [ ] This bug doesn't happen if I use Microsoft's Visual Studio Code. It only happens in VSCodium.
 
 **Please confirm that the issue/resolution isn't already documented**
-- [ ] I checked [the Docs page](https://github.com/VSCodium/vscodium/blob/master/DOCS.md) and my issue is not mentioned there.
+- [ ] I checked [the Docs page](https://github.com/VSCodium/vscodium/blob/master/docs/index.md) and [the Troubleshooting page](https://github.com/VSCodium/vscodium/blob/master/docs/troubleshooting.md) and my issue is not mentioned there.
 
 **To Reproduce**
 Steps to reproduce the behavior:

CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing
+
+:+1::tada: First off, thanks for taking the time to contribute! :tada::+1:
+
+#### Table Of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Reporting Bugs](#reporting-bugs)
+- [Making Changes](#making-changes)
+
+## Code of Conduct
+
+This project and everyone participating in it is governed by the [VSCodium Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
+
+## Reporting Bugs
+
+### Before Submitting an Issue
+
+Before creating bug reports, please check existing issues and [the Troubleshooting page](https://github.com/VSCodium/vscodium/blob/master/docs/troubleshooting.md) as you might find out that you don't need to create one.
+When you are creating a bug report, please include as many details as possible. Fill out [the required template](https://github.com/VSCodium/vscodium/issues/new?&labels=bug&&template=bug_report.md), the information it asks for helps us resolve issues faster.
+
+## Making Changes
+
+If you want to make changes, please read [the Build page](./docs/howto-build.md).
+
+### Building VSCodium
+
+To build VSCOdium, please follow the command found in the section [`Build Scripts`](./docs/howto-build.md#build-scripts).
+
+### Updating patches
+
+If you want to update the existing patches, please follow the section [`Patch Update Process - Semi-Automated`](./docs/howto-build.md#patch-update-process-semiauto).
+
+### Add a new patch
+
+- firstly, you need to build VSCodium
+- then use the command `patch.sh <your patch name>`, to initiate a new patch
+- when the script pause at `Press any key when the conflict have been resolved...`, open `vscode` directory in **VSCodium**
+- run `yarn watch`
+- run `./script/code.sh`
+- make your changes
+- press any key to continue the script `patch.sh`

README.md

@@ -45,7 +45,7 @@ Download latest release here:
 [insiders](https://github.com/VSCodium/vscodium-insiders/releases)
 :tada: :tada:
 
-[More info / helpful tips are here.](https://github.com/VSCodium/vscodium/blob/master/DOCS.md)
+[More info / helpful tips are here.](https://github.com/VSCodium/vscodium/blob/master/docs/index.md)
 
 
 #### <a id="install-with-brew"></a>Install with Brew (Mac)
@@ -60,7 +60,7 @@ brew tap homebrew/cask-versions
 brew install --cask vscodium-insiders
 ```
 
-*Note for macOS users: if you can't open the App, please read [the following troubleshooting](https://github.com/VSCodium/vscodium/wiki/Troubleshooting#macos).*
+*Note for macOS users: if you can't open the App, please read [the following troubleshooting](https://github.com/VSCodium/vscodium/blob/master/docs/troubleshooting.md#macos).*
 
 #### <a id="install-with-winget"></a>Install with Windows Package Manager (WinGet)
 
@@ -95,7 +95,7 @@ scoop install vscodium
 #### <a id="install-with-snap"></a>Install with snap (GNU/Linux)
 
 VSCodium is available in the [Snap Store](https://snapcraft.io/) as [Codium](https://snapcraft.io/codium),
-thanks to the help of the [Snapcrafters](https://github.com/snapcrafters/codium) community.  
+thanks to the help of the [Snapcrafters](https://github.com/snapcrafters/codium) community.
 If your GNU/Linux distribution has support for [snaps](https://snapcraft.io/docs/installing-snapd):
 ```bash
 snap install codium --classic
@@ -109,7 +109,7 @@ You can always install using the downloads (deb, rpm, tar) on the releases page
 install using your favorite package manager and get automatic updates.
 
 [@paulcarroty](https://github.com/paulcarroty) has set up a repository with instructions
-for `apt`, `dnf` and `zypper` [here](https://gitlab.com/paulcarroty/vscodium-deb-rpm-repo).  
+for `apt`, `dnf` and `zypper` [here](https://gitlab.com/paulcarroty/vscodium-deb-rpm-repo).
 
 Any issues installing VSCodium using your package manager should be directed to that repository's issue tracker.
 
@@ -118,11 +118,11 @@ Any issues installing VSCodium using your package manager should be directed to
 VSCodium is available in [AUR](https://wiki.archlinux.org/index.php/Arch_User_Repository),
 maintained by [@binex-dsk](https://github.com/binex-dsk)
 as package [vscodium-bin](https://aur.archlinux.org/packages/vscodium-bin/) (stable) and
-as [vscodium-insiders-bin](https://aur.archlinux.org/packages/vscodium-insiders-bin).  
+as [vscodium-insiders-bin](https://aur.archlinux.org/packages/vscodium-insiders-bin).
 
 If you want to save disk space by having VSCodium use the Electron system-wide, you also have
 [vscodium-electron](https://aur.archlinux.org/packages/vscodium-electron),
-maintained by [@m00nw4tch3r](https://aur.archlinux.org/account/m00nw4tch3r).  
+maintained by [@m00nw4tch3r](https://aur.archlinux.org/account/m00nw4tch3r).
 
 An alternative package [vscodium-git](https://aur.archlinux.org/packages/vscodium-git/),
 maintained by [@cedricroijakkers](https://github.com/cedricroijakkers),
@@ -131,7 +131,7 @@ is also available should you wish to compile from source yourself.
 #### <a id="flatpak"></a>Flatpak Option (GNU/Linux)
 
 VSCodium is (unofficially) available as a Flatpak app [here](https://flathub.org/apps/details/com.vscodium.codium)
-and the build repo is [here](https://github.com/flathub/com.vscodium.codium). 
+and the build repo is [here](https://github.com/flathub/com.vscodium.codium).
 If your distribution has support for [flatpak](https://flathub.org), and you have enabled the [flathub repo](https://flatpak.org/setup/):
 ```bash
 flatpak install flathub com.vscodium.codium
@@ -140,7 +140,7 @@ flatpak run com.vscodium.codium
 
 ## <a id="build"></a>Build
 
-Build instructions can be found [here](https://github.com/VSCodium/vscodium/blob/master/docs/build.md)
+Build instructions can be found [here](https://github.com/VSCodium/vscodium/blob/master/docs/howto-build.md)
 
 ## <a id="why"></a>Why Does This Exist
 
@@ -170,13 +170,17 @@ Microsoft's build process (which we are running to build the binaries) does down
 
 ### Documentation
 
-For more information on getting all the telemetry disabled and tips for migrating from Visual Studio Code to VSCodium, have a look at this [Docs](https://github.com/VSCodium/vscodium/blob/master/DOCS.md) page.
+For more information on getting all the telemetry disabled, tips for migrating from Visual Studio Code to VSCodium and more, have a look at [the Docs page](https://github.com/VSCodium/vscodium/blob/master/docs/index.md) page.
+
+### Troubleshooting
+
+If you have any issue, please check [the Troubleshooting page](https://github.com/VSCodium/vscodium/blob/master/docs/troubleshooting.md) or the existing issues.
 
 ### Extensions and the Marketplace
 
-According to the VS Code Marketplace [Terms of Use](https://aka.ms/vsmarketplace-ToU), _you may only install and use Marketplace Offerings with Visual Studio Products and Services._ For this reason, VSCodium uses [open-vsx.org](https://open-vsx.org/), an open source registry for VS Code extensions. See the [Extensions + Marketplace](https://github.com/VSCodium/vscodium/blob/master/DOCS.md#extensions-marketplace) section on the Docs page for more details.
+According to the VS Code Marketplace [Terms of Use](https://aka.ms/vsmarketplace-ToU), _you may only install and use Marketplace Offerings with Visual Studio Products and Services._ For this reason, VSCodium uses [open-vsx.org](https://open-vsx.org/), an open source registry for VS Code extensions. See the [Extensions + Marketplace](https://github.com/VSCodium/vscodium/blob/master/docs/index.md#extensions-marketplace) section on the Docs page for more details.
 
-Please note that some Visual Studio Code extensions have licenses that restrict their use to the official Visual Studio Code builds and therefore do not work with VSCodium. See [this note](https://github.com/VSCodium/vscodium/blob/master/DOCS.md#proprietary-debugging-tools) on the Docs page for what's been found so far and possible workarounds.
+Please note that some Visual Studio Code extensions have licenses that restrict their use to the official Visual Studio Code builds and therefore do not work with VSCodium. See [this note](https://github.com/VSCodium/vscodium/blob/master/docs/index.md#proprietary-debugging-tools) on the Docs page for what's been found so far and possible workarounds.
 
 ### How are the VSCodium binaries built?
 

docs/accounts-authentication.md

@@ -0,0 +1,17 @@
+# Accounts authentication
+
+## GitHub
+
+The GitHub authentication has been patched to use personal access token.
+
+Here how to create a new personal access token: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token
+
+## Microsoft
+
+The Microsoft authentication hasn't been patched so its status is unknown.
+
+## When does it happened?
+
+An account authentication occurs only when an extension is asking for it.
+
+For `GitLens`, since the `12 non-plus` version, it won't ask for any new authentication.

docs/extensions-compatibility.md

@@ -0,0 +1,27 @@
+# Extensions compatibility
+
+## Partial Compatibility
+
+- [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
+> [Since May 2021](https://devblogs.microsoft.com/python/python-in-visual-studio-code-may-2021-release/), Python is using a closed source language server ([Pylance](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance))
+
+## Incompatibility
+
+- [LaTeX Workshop](https://marketplace.visualstudio.com/items?itemName=James-Yu.latex-workshop)
+> It's officially unsupported: https://github.com/James-Yu/LaTeX-Workshop/wiki/FAQ#vscodium-is-not-officially-supported
+
+## Incompatibility due to licensing
+
+The following extensions are not compatible with VSCodium due to their licensing:
+
+- [Live Share](https://marketplace.visualstudio.com/items?itemName=MS-vsliveshare.vsliveshare)
+- [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+- [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh)
+- [Remote - SSH: Editing Configuration Files](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh-edit)
+- [Remote - WSL](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl)
+
+## Replacements
+
+The following extensions are functional replacements for incompatible extensions:
+
+- [Open Remote - SSH](https://open-vsx.org/extension/jeanp413/open-remote-ssh)

docs/build.md → docs/howto-build.md

@@ -1,4 +1,4 @@
-# Build
+# How to build VSCodium
 
 ## Table of Contents
 

DOCS.md → docs/index.md

@@ -10,14 +10,18 @@
   - [How to self host your own VS Code Marketplace](#howto-selfhost-marketplace)
   - [Proprietary Debugging Tools](#proprietary-debugging-tools)
   - [Proprietary Extensions](#proprietary-extensions)
+- [Extensions compatibility](https://github.com/VSCodium/vscodium/blob/master/docs/extensions-compatibility.md)
 - [Migrating from Visual Studio Code to VSCodium](#migrating)
 - [Sign in with GitHub](#signin-github)
+- [Accounts authentication](https://github.com/VSCodium/vscodium/blob/master/docs/accounts-authentication.md)
 - [How do I run VSCodium in portable mode?](#portable)
 - [How do I fix the default file manager?](#file-manager)
 - [How do I press and hold a key and have it repeat in VSCodium?](#press-and-hold)
 - [How do I open VSCodium from the terminal?](#terminal-support)
   - [From Linux .tar.gz](#from-linux-targz)
-- [How to build VSCodium](https://github.com/VSCodium/vscodium/blob/master/docs/build.md)
+- [Troubleshooting](https://github.com/VSCodium/vscodium/blob/master/docs/troubleshooting.md)
+- [Contributing](https://github.com/VSCodium/vscodium/blob/master/CONTRIBUTING.md)
+- [How to build VSCodium](https://github.com/VSCodium/vscodium/blob/master/docs/howto-build.md)
 
 ## <a id="disable-telemetry"></a>Getting all the Telemetry Out
 
@@ -56,7 +60,7 @@ By default, the `product.json` file is set up to use [open-vsx.org](https://open
 
 ### <a id="howto-openvsx-marketplace"></a>How to use the Open VSX Registry
 
-As noted above, the [Open VSX Registry](https://open-vsx.org/) is the pre-set extension gallery in VSCodium. Using the extension view in VSCodium will therefore by default use it.  
+As noted above, the [Open VSX Registry](https://open-vsx.org/) is the pre-set extension gallery in VSCodium. Using the extension view in VSCodium will therefore by default use it.
 See [this article](https://www.gitpod.io/blog/open-vsx/) for more information on the motivation behind Open VSX.
 
 ### <a id="howto-switch-marketplace"></a>How to use a different extension gallery
@@ -96,7 +100,7 @@ Individual developers and enterprise companies in regulated or security-consciou
 
 There are likely other options, but the following were reported to work:
 
-* [Open VSX](https://github.com/eclipse/openvsx) eclipse open-source project  
+* [Open VSX](https://github.com/eclipse/openvsx) eclipse open-source project
   While the public instance which is run by the Eclipse Foundation is the pre-set endpoint in VSCodium, you can host your own instance.
 
     > Open VSX is a [vendor-neutral](https://projects.eclipse.org/projects/ecd.openvsx) open-source alternative to the [Visual Studio Marketplace](https://marketplace.visualstudio.com/vscode). It provides a server application that manages [VS Code extensions](https://code.visualstudio.com/api) in a database, a web application similar to the VS Code Marketplace, and a command-line tool for publishing extensions similar to [vsce](https://code.visualstudio.com/api/working-with-extensions/publishing-extension#vsce).
@@ -107,7 +111,7 @@ There are likely other options, but the following were reported to work:
 
 ### <a id="howto-vscode-marketplace"></a>How to use the VS Code Marketplace
 
-As with any online service, ensure you've understood [its terms of use](https://aka.ms/vsmarketplace-ToU).  
+As with any online service, ensure you've understood [its terms of use](https://aka.ms/vsmarketplace-ToU).
 Also note that this extension gallery hosts multiple extensions that are non-free and have license-agreements that explicitly forbid using them in non-Microsoft products, along with using telemetry.
 
 The endpoint URLs are given in the [example above](#howto-switch-marketplace).

docs/troubleshooting.md

@@ -0,0 +1,51 @@
+# Troubleshooting
+
+## Table of Contents
+
+- [Linux](#linux)
+  - [Fonts showing up as rectangles](#linux-fonts-rectangle)
+  - [Global menu workaround for KDE](#linux-kde-global-menu)
+- [macOS](#macos)
+  - [App can't be opened because Apple cannot check it for malicious software](#macos-unidentified-developer)
+  - ["VSCodium.app" is damaged and can’t be opened. You should move it to the Bin](#macos-quarantine)
+
+
+## <a id="linux"></a>Linux
+
+#### <a id="linux-fonts-rectangle"></a>*Fonts showing up as rectangles*
+
+The following command should help:
+
+```
+rm -rf ~/.cache/fontconfig
+rm -rf ~/snap/codium/common/.cache
+fc-cache -r
+```
+
+#### <a id="linux-kde-global-menu"></a>*Global menu workaround for KDE*
+
+Install these packages on Fedora:
+
+* libdbusmenu-devel
+* dbus-glib-devel
+* libdbusmenu
+
+On Ubuntu this package called `libdbusmenu-glib4`.
+
+Credits: [Gerson](https://gitlab.com/paulcarroty/vscodium-deb-rpm-repo/-/issues/91)
+
+## <a id="macos"></a>macOS
+
+Since the App is signed with self-signed certificate, on the first launch, you might see the following messages:
+
+#### <a id="macos-unidentified-developer"></a>*App can't be opened because Apple cannot check it for malicious software*
+
+You can right-click the App and choose `Open`.
+
+#### <a id="macos-quarantine"></a>*"VSCodium.app" is damaged and can’t be opened. You should move it to the Bin.*
+
+The following command will remove the quarantine attribute.
+
+```
+xattr -r -d com.apple.quarantine /Applications/VSCodium.app
+```