From 839c68685d8aee9933fbdbd155104def12ad5dff Mon Sep 17 00:00:00 2001 From: Oleg Silkin <16809287+osilkin98@users.noreply.github.com> Date: Wed, 10 Nov 2021 22:03:41 +0000 Subject: [PATCH 1/3] update contributing doc --- CONTRIBUTING.md | 191 +++++------------------------------------------- 1 file changed, 17 insertions(+), 174 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 63d21c91b6..f617fa7302 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,188 +1,31 @@ # Contributing to MicroShift -If you would like to develop MicroShift locally, you can follow this guide on getting -it installed and running through the provided Makefile. +Welcome to MicroShift! We are glad you are interested in this project. +Pull Requests are always welcome. If you’d like to jump right in with MicroShift, +check out the [open issues](https://github.com/redhat-et/microshift/issues). +No pull request is too small, we’re pretty sure you might see some typos in the code, +so please help us to fix anything you see! -This guide will primarily focus on running MicroShift within a VM using Vagrant. +## Documentation -## (optional) Developing with Vagrant +Looking for the docs? Well, look no further; [microshift.io](https://microshift.io) has the answers. +If the docs aren’t fulfilling enough, you can add to them by contributing in the [documentation repo](https://github.com/redhat-et/microshift-documentation). -To get started with development, it is recommended to use Vagrant for VM provisioning, -however it is not necessary. -You can find a guide on how to install it for your system [here](https://www.vagrantup.com/downloads). +## Issues -Once Vagrant is installed, you will need to create a Vagrant box for the operating -system of your choice. For this example we will be looking at a [fedora 34 cloud -image](https://app.vagrantup.com/fedora/boxes/34-cloud-base), however you can substitute any vagrant image of your choice. +Notice a bug? File an issue [here](https://github.com/redhat-et/microshift/issues/new/choose) and provide as much information as possible. +## Enhancement Proposals -First, navigate to the MicroShift directory on your host system, or another designated -directory where we will be storing the Vagrantfile. +MicroShift’s goal is to create a minimal core that can functionally operate as close to OpenShift as +possible while maintaining a low resource impact. We are always looking for enhancement proposals, +so feel free to create a pull-request and an additional document explaining your proposal. +## Community +Join us on [Slack](https://microshift.slack.com)! ([Invite to the Slack space](https://join.slack.com/t/microshift/shared_invite/zt-uxncbjbl-XOjueb1ShNP7xfByDxNaaA)) -Next, download the vagrant image. For this example we will use -a fedora 34 cloud image: - -```sh -vagrant box add fedora/34-cloud-base -``` - -Depending on the image, Vagrant will ask you to select a Virtualization provider, -just select the first one. - -Once that downloads, initialize the repository for launching your image: - -``` -vagrant init fedora/34-cloud-base -``` - -Running this command will create a `Vagrantfile` in your working directory which -is used to configure your vagrant box. - -Before we start our Vagrant box, we will need to increase the amount of RAM available -to the system. -To do this, edit the Vagrantfile and configure your provider settings to include -the following: - -```rb - config.vm.provider "libvirt" do |v| - # provides 3GB of memory - v.memory = 3072 - # for parallelization - v.cpus = 2 - end -``` - -The value of `config.vm.provider` depends on the provider you selected when you -ran `vagrant add` earlier. For example, if you selected virtualbox then the first -line should be: `config.vm.provider "virtualbox" do |v|` - - -Now we can start the VM: - -``` -vagrant up -``` - -Once the VM is up, connect to it: - -``` -vagrant ssh -``` - -### (Extra Optional) Connecting VSCode to Vagrant - -If you're using VSCode, you can connect to your vagrant box with a few extra steps. - -#### Increasing Memory Requirements - -Since VS Code leans more on the heavy side of development, the RAM usage on your Vagrant environment -can go up to 5GB, and therefore we will need to modify the `Vagrantfile` to -increase the amount of available RAM from 3GB to 5GB (or 6GB if you want to be safe). -To do this, set `v.memory` to the following in your `Vagrantfile`: - -```rb - # provides 5GB of memory - v.memory = 5120 - # provides 6GB of memory - v.memory = 6144 -``` - -#### Setting up an SSH Profile - -First we need to ask Vagrant for an SSH config file. From your host machine, run: - -``` -vagrant ssh-config > ssh-config.conf -``` - -*You can edit the `ssh-config.conf` file to change the hostname from `default` to -`vagrant` to be more easily identifiable, but that's up to you. :)* - -Here's an example of my working SSH config file: -``` -Host default - HostName 127.0.0.1 - User vagrant - Port 2222 - UserKnownHostsFile /dev/null - StrictHostKeyChecking no - PasswordAuthentication no - IdentityFile /path/to/microshift/.vagrant/machines/default/virtualbox/private_key - IdentitiesOnly yes - LogLevel FATAL -``` - - -Next, you'll want to install the `Remote - SSH` extension from the [VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) - - - -With the extension installed, you'll click on the green bottom in the bottom-left -corner of VSCode to open a dropdown menu for SSH options: - -![VSCode Remote Button](./docs/pics/vscode-remote-button.png) - -Select the option to open an SSH configuration file: -![Dropdown Menu](./docs/pics/remote-ssh-dropdown.png) - -Next you'll want to navigate to the "Remote Explorer" tab on the left-hand side -of VSCode, then select on the vagrant target (default if you haven't renamed it) -and click on the button to connect to it in a remote window. - - -*(Credits to Andrés Lopez for this guide: [Connect Visual Studio Code with Vagrant in your local machine -](https://medium.com/@lopezgand/connect-visual-studio-code-with-vagrant-in-your-local-machine-24903fb4a9de))* - - -## Running MicroShift Locally - -### Pre-Installation - -You will need to install the required binaries: -- git -- make -- golang -- glibc -- podman - -```sh -# Fedora/CentOS -sudo dnf install \ - git \ - make \ - golang \ - glibc-static - -# Ubuntu -sudo apt install \ - git \ - build-essential \ # provides Make - golang-go \ - glibc -``` - -To install podman, you can find the appropriate guide for your respective system: -[Install Podman](https://podman.io/getting-started/installation) - - -Next you'll want to clone the repository and cd into it: -```sh -git clone https://github.com/redhat-et/microshift.git -cd microshift -``` - -### Building MicroShift - -Now we can build MicroShift: - -```sh -make build -CONFIG_ENV_ONLY=true ./install.sh -sudo ./microshift run -``` - +Community meetings are held weekly, Wednesdays at 10:30AM - 11:00AM EST. Be sure to join the community [calendar](https://calendar.google.com/calendar/embed?src=nj6l882mfe4d2g9nr1h7avgrcs%40group.calendar.google.com&ctz=America%2FChicago)! Click "Google Calendar" in the lower right-hand corner to subscribe. From 149972723de239f0ecf566e4c6bdbc4548813f4a Mon Sep 17 00:00:00 2001 From: Oleg Silkin <16809287+osilkin98@users.noreply.github.com> Date: Thu, 11 Nov 2021 00:29:41 +0000 Subject: [PATCH 2/3] touchup on proposal section --- CONTRIBUTING.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f617fa7302..231efc8529 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,7 +21,8 @@ Notice a bug? File an issue [here](https://github.com/redhat-et/microshift/issue MicroShift’s goal is to create a minimal core that can functionally operate as close to OpenShift as possible while maintaining a low resource impact. We are always looking for enhancement proposals, -so feel free to create a pull-request and an additional document explaining your proposal. +so feel free to create an enhancement issue with a link to a document that explains your proposal. +The enhancement will be considered as long as it aligns with [MicroShift's design goals](https://github.com/redhat-et/microshift/blob/main/docs/design/design.md). ## Community From fa32ffe22025d16f73dce2b4d90552439f1e0dee Mon Sep 17 00:00:00 2001 From: Oleg Silkin <16809287+osilkin98@users.noreply.github.com> Date: Thu, 11 Nov 2021 09:01:21 +0000 Subject: [PATCH 3/3] reword contributing doc --- CONTRIBUTING.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 231efc8529..412177bb90 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,16 +1,12 @@ # Contributing to MicroShift Welcome to MicroShift! We are glad you are interested in this project. -Pull Requests are always welcome. If you’d like to jump right in with MicroShift, -check out the [open issues](https://github.com/redhat-et/microshift/issues). -No pull request is too small, we’re pretty sure you might see some typos in the code, -so please help us to fix anything you see! - +If you’d like to jump right in with MicroShift then check out the [open issues](https://github.com/redhat-et/microshift/issues), pull requests are always welcome. ## Documentation Looking for the docs? Well, look no further; [microshift.io](https://microshift.io) has the answers. -If the docs aren’t fulfilling enough, you can add to them by contributing in the [documentation repo](https://github.com/redhat-et/microshift-documentation). +If you would like to contribute to the documentation pages, check out the [documentation repo](https://github.com/redhat-et/microshift-documentation). ## Issues