From 98af6d06db789e8d84d83fc5bc66ee8a237ad7da Mon Sep 17 00:00:00 2001 From: dst27 Date: Mon, 11 Jul 2022 14:49:52 +0000 Subject: [PATCH 1/3] docs: Add how-to for remote dev (Gitpod) --- docs/how-to-guides/use-gitpod.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 docs/how-to-guides/use-gitpod.md diff --git a/docs/how-to-guides/use-gitpod.md b/docs/how-to-guides/use-gitpod.md new file mode 100644 index 0000000000000..dc894b2b163b1 --- /dev/null +++ b/docs/how-to-guides/use-gitpod.md @@ -0,0 +1,32 @@ +# Using Gitpod for Remote Development + +[Gitpod](https://gitpod.io) provides powerful ready-to-code developer environments in the cloud eliminating the friction +of setting up local environments and IDEs with Perl, Docker and plugins, making it possible for even new contributors to +OpenFoodFacts Server to get started in minutes instead of hours! + +Note that while this how-to is tailored for Gitpod, using alternatives like [Github Codespaces][github-codespaces] should be +similar. + +For the most part, development on Gitpod is similar to developing locally as documented +in the [quickstart guide](../introduction/dev-environment-quick-start-guide.md) +and [docker-developer-guide](docker-developer-guide.md), however accessing your dev-deployment of +`openfoodfacts-server` requires an extra step. + +## Accessing Your Developer Deployment + +Since Gitpod runs your code in a remote machine, your dev-deployment spun up with `make dev` or `make up` will not +accessible when you open the default https://openfoodfacts.localhost in your browser. This occurs because the server +running on the remote machine is not accessible on your local network interface. + +To overcome this, we can make use of SSH tunnel that listens to your local port 80 and forwards traffic to the port 80 +of the remote machine. Gitpod makes it really simple to SSH into your dev environment by letting you copy the `ssh` +command required to reach your remote environment. To start, follow the ssh instructions on Gitpod's offical +guide: [SSH for workspaces as easy as copy/paste][gitpod-ssh-guide]. Once you have copied the ssh command and ensure it +works as-is, add a `-L 80:localhost:80` to the command to make it look like: +`ssh -L 80:localhost:80 'openfoodfac-openfoodfac-tok-openfoodfac-r9f61214h9vt.ssh.ws-c.gitpod.io'`. + +Once you execute the altered command in your terminal, you should be able to access OpenFoodFacts +on https://openfoodfacts.localhost just as documented in the quickstart guide! + +[gitpod-ssh-guide]: https://www.gitpod.io/blog/copy-paste-ssh-workspace-access +[github-codespaces]: https://github.com/features/codespaces From 2b0a8157a13a3ea80012896caef999bc9d77b349 Mon Sep 17 00:00:00 2001 From: dst27 Date: Mon, 11 Jul 2022 15:16:38 +0000 Subject: [PATCH 2/3] docs: Add references/badges for gitpod environments --- README.md | 2 ++ docs/introduction/dev-environment-quick-start-guide.md | 5 +++++ 2 files changed, 7 insertions(+) diff --git a/README.md b/README.md index 96f24427d447c..c58d0952175c0 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,7 @@ [![Open Source Helpers](https://www.codetriage.com/openfoodfacts/openfoodfacts-server/badges/users.svg)](https://www.codetriage.com/openfoodfacts/openfoodfacts-server) [![Backers on Open Collective](https://opencollective.com/openfoodfacts-server/backers/badge.svg)](#backers) [![Sponsors on Open Collective](https://opencollective.com/openfoodfacts-server/sponsors/badge.svg)](#sponsors) +[![Contribute with Gitpod](https://img.shields.io/badge/Contribute%20with-Gitpod-908a85?logo=gitpod)](https://gitpod.io/#https://github.com/openfoodfacts/openfoodfacts-server) ## Tests [![Perl::Critic](https://github.com/openfoodfacts/openfoodfacts-server/actions/workflows/perlcritic.yml/badge.svg)](https://github.com/openfoodfacts/openfoodfacts-server/actions/workflows/perlcritic.yml) @@ -49,6 +50,7 @@ Data about food is of public interest and has to be open. The complete database * Developer documentation: * [Quick start guide (Docker)](./docs/introduction/dev-environment-quick-start-guide.md) * [Developer guide (Docker)](./docs/how-to-guides/docker-developer-guide.md) + * [Developer guide (Gitpod)](./docs/how-to-guides/use-gitpod.md) * [Manual installation](https://wiki.openfoodfacts.org/Product_Opener/Installation) * Configuration [TBA] * Dependencies [TBA] diff --git a/docs/introduction/dev-environment-quick-start-guide.md b/docs/introduction/dev-environment-quick-start-guide.md index 118c416dd231a..b5714ac601738 100644 --- a/docs/introduction/dev-environment-quick-start-guide.md +++ b/docs/introduction/dev-environment-quick-start-guide.md @@ -1,5 +1,10 @@ # Dev environment quick start guide +[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/https://github.com/openfoodfacts/openfoodfacts-server/) +> Gitpod will automatically clone and build the repository for you and comes with Docker pre-installed. It is one of the fastest +> ways to spin up an environment for `openfoodfacts-servbr`, but requires some additional setup to access your development deployment documented +> in [use-gitpod how-to](../how-to-guides/use-gitpod.md). + This guide will allow you to rapidly build a ready-to-use development environment for **Product Opener** running in Docker. First setup time estimate is `~10min` with the following specs: From 8cc44136b7cb2f448f38f82d519678b6be8f72a5 Mon Sep 17 00:00:00 2001 From: dst27 Date: Wed, 13 Jul 2022 17:08:32 +0000 Subject: [PATCH 3/3] docs: Improve Gitpod reference --- CONTRIBUTING.md | 15 +++++++------- README.md | 9 ++++----- docs/how-to-guides/use-gitpod.md | 20 ++++++++++++++----- .../dev-environment-quick-start-guide.md | 9 +++------ 4 files changed, 30 insertions(+), 23 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8c6d2951dfc15..119f7168a2bac 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,8 +4,9 @@ * If you would like to work on an issue, drop in a comment at the issue. If it is already assigned to someone, but there is no sign of any work being done, please free to drop in a comment so that the issue can be assigned to you if the previous assignee has dropped it entirely. ## Contributing +[![Contribute with Gitpod](https://img.shields.io/badge/Contribute%20with-Gitpod-908a85?logo=gitpod)](https://gitpod.io/#https://github.com/openfoodfacts/openfoodfacts-server) -When contributing to this repository, please first discuss the change you wish to make via issue, or the official [slack channel](https://openfoodfacts.slack.com/). +When contributing to this repository, please first discuss the change you wish to make via issue, or the official [Slack channel](https://openfoodfacts.slack.com/). Get started running server in development mode, see [Dev environment quick start guide](./docs/introduction/dev-environment-quick-start-guide.md) @@ -15,11 +16,11 @@ Get started running server in development mode, see [Dev environment quick start 1. Ensure any install or build dependencies are removed before the end of the layer when doing a build. 2. Check that there are no conflicts and your request passes [Travis](https://travis-ci.org) build. Check the log of the pass test if it fails the build. 3. Give the description of the issue that you want to resolve in the pull request message. - * The format of the commit message to be fixed is - **fix:[Description of the issue] Fixes #[issue number]** + * The format of the commit message to be fixed is + **fix:[Description of the issue] Fixes #[issue number]** Example: **fix: Add toast warning in `MainActivity.java` Fixes #529** * We are following [conventional commit](https://www.conventionalcommits.org/en/v1.0.0-beta.2/) - we a [set of standard prefixes](https://github.com/commitizen/conventional-commit-types/blob/master/index.json) + with a [set of standard prefixes](https://github.com/commitizen/conventional-commit-types/blob/master/index.json) (`fix`, `feat`, `doc`, `build`, `test`…), with the addition of: * `l10n` for translations @@ -28,7 +29,7 @@ Get started running server in development mode, see [Dev environment quick start ## Contributions Best Practices -### Check before commiting +### Check before committing You can save you sometime by running some checks locally before committing. @@ -38,8 +39,8 @@ You can save you sometime by running some checks locally before committing. * Write clear meaningful git commit messages (Do read [here](https://chris.beams.io/posts/git-commit/)). * Make sure your PR's description contains GitHub's special keyword references that automatically close the related issue when the PR is merged(For more info click [here](https://github.com/blog/1506-closing-issues-via-pull-requests)). -* When you make very very minor changes to a PR of yours (like for example fixing a failing Travis build or some small style corrections or minor changes requested by reviewers) make sure you squash your commits afterward so that you don't have an absurd number of commits for a very small fix(Learn how to squash at [here](https://davidwalsh.name/squash-commits-git)). -* When you're submitting a PR for a UI-related issue, it would be really awesome if you add a screenshot of your change or a link to a deployment where it can be tested out along with your PR. It makes it very easy for the reviewers and you'll also get reviews quicker. +* When you make very, very minor changes to a PR of yours (like for example fixing a failing Travis build or some small style corrections or minor changes requested by reviewers) make sure you squash your commits afterward so that you don't have an absurd number of commits for a very small fix(Learn how to squash at [here](https://davidwalsh.name/squash-commits-git)). +* When you're submitting a PR for a UI-related issue, it would be really awesome if you add a screenshot of your change or a link to a deployment where it can be tested out along with your PR. It makes it very easy for the reviewers, and you'll also get reviews quicker. ### Feature Requests and Bug Reports diff --git a/README.md b/README.md index c58d0952175c0..fae117f5366b8 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ - +openfoodfacts-logo # Open Food Facts - Product Opener (Web Server) @@ -7,7 +7,6 @@ [![Open Source Helpers](https://www.codetriage.com/openfoodfacts/openfoodfacts-server/badges/users.svg)](https://www.codetriage.com/openfoodfacts/openfoodfacts-server) [![Backers on Open Collective](https://opencollective.com/openfoodfacts-server/backers/badge.svg)](#backers) [![Sponsors on Open Collective](https://opencollective.com/openfoodfacts-server/sponsors/badge.svg)](#sponsors) -[![Contribute with Gitpod](https://img.shields.io/badge/Contribute%20with-Gitpod-908a85?logo=gitpod)](https://gitpod.io/#https://github.com/openfoodfacts/openfoodfacts-server) ## Tests [![Perl::Critic](https://github.com/openfoodfacts/openfoodfacts-server/actions/workflows/perlcritic.yml/badge.svg)](https://github.com/openfoodfacts/openfoodfacts-server/actions/workflows/perlcritic.yml) @@ -15,7 +14,7 @@ ## What is Product Opener? -**Product Opener** is the server software for **Open Food Facts** and **Open Beauty Facts**. It is released under the AGPL license and is being developed in Perl, HTML and JavaScript as [Free and Open-Source Software](https://en.wikipedia.org/wiki/Free_and_open-source_software). +**Product Opener** is the server software for **Open Food Facts** and **Open Beauty Facts**. It is released under the AGPL license and is being developed in Perl, HTML and JavaScript as [Free and Open-Source Software](https://en.wikipedia.org/wiki/Free_and_open-source_software). It works together with [Robotoff](https://github.com/openfoodfacts/robotoff), Open Food Facts' AI system (in Python, which can also be installed locally) and the [Open Food Facts apps](https://github.com/openfoodfacts/smooth-app) (which can work with your local instance after enabling dev mode) @@ -37,7 +36,7 @@ Data about food is of public interest and has to be open. The complete database * ## Priorities -* Please list priority issues here +* Please list priority issues here * Please add roadmaps here * [P1 problems](https://github.com/openfoodfacts/openfoodfacts-server/labels/P1) * [P1 candidates](https://github.com/openfoodfacts/openfoodfacts-server/labels/P1%20candidate) @@ -62,7 +61,7 @@ Note: documentation follows the [Diátaxis Framework](https://diataxis.fr/) ## Contribution guidelines -If you're new to Open-Source, we recommend you to Checkout our [_Contributing Guidelines_](https://github.com/openfoodfacts/openfoodfacts-server/blob/master/CONTRIBUTING.md). Feel free to fork the project and send us a pull request. +If you're new to Open-Source, we recommend you to check out our [_Contributing Guidelines_](https://github.com/openfoodfacts/openfoodfacts-server/blob/master/CONTRIBUTING.md). Feel free to fork the project and send us a pull request. * Writing tests * Code review diff --git a/docs/how-to-guides/use-gitpod.md b/docs/how-to-guides/use-gitpod.md index dc894b2b163b1..d1c1e1ae0b2d6 100644 --- a/docs/how-to-guides/use-gitpod.md +++ b/docs/how-to-guides/use-gitpod.md @@ -4,7 +4,7 @@ of setting up local environments and IDEs with Perl, Docker and plugins, making it possible for even new contributors to OpenFoodFacts Server to get started in minutes instead of hours! -Note that while this how-to is tailored for Gitpod, using alternatives like [Github Codespaces][github-codespaces] should be +Note that while this how-to is tailored for Gitpod, using alternatives like [GitHub Codespaces][github-codespaces] should be similar. For the most part, development on Gitpod is similar to developing locally as documented @@ -12,21 +12,31 @@ in the [quickstart guide](../introduction/dev-environment-quick-start-guide.md) and [docker-developer-guide](docker-developer-guide.md), however accessing your dev-deployment of `openfoodfacts-server` requires an extra step. -## Accessing Your Developer Deployment +## Get Started + +[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/https://github.com/openfoodfacts/openfoodfacts-server/) +> Gitpod will automatically clone and open the repository for you in VSCode by default. It will also automatically build +> the project for you on opening and comes with Docker and other tools pre-installed making it one of the fastest ways +> to spin up an environment for `openfoodfacts-server`. + +Once the repository is open in Gitpod, other instructions in the +[quick-start guide](../introduction/dev-environment-quick-start-guide.md) can be generally followed. + +## Accessing your development instance of OpenFoodFacts Web Since Gitpod runs your code in a remote machine, your dev-deployment spun up with `make dev` or `make up` will not -accessible when you open the default https://openfoodfacts.localhost in your browser. This occurs because the server +accessible when you open the default http://openfoodfacts.localhost in your browser. This occurs because the server running on the remote machine is not accessible on your local network interface. To overcome this, we can make use of SSH tunnel that listens to your local port 80 and forwards traffic to the port 80 of the remote machine. Gitpod makes it really simple to SSH into your dev environment by letting you copy the `ssh` -command required to reach your remote environment. To start, follow the ssh instructions on Gitpod's offical +command required to reach your remote environment. To start, follow the ssh instructions on Gitpod's official guide: [SSH for workspaces as easy as copy/paste][gitpod-ssh-guide]. Once you have copied the ssh command and ensure it works as-is, add a `-L 80:localhost:80` to the command to make it look like: `ssh -L 80:localhost:80 'openfoodfac-openfoodfac-tok-openfoodfac-r9f61214h9vt.ssh.ws-c.gitpod.io'`. Once you execute the altered command in your terminal, you should be able to access OpenFoodFacts -on https://openfoodfacts.localhost just as documented in the quickstart guide! +on http://openfoodfacts.localhost just as documented in the quickstart guide! [gitpod-ssh-guide]: https://www.gitpod.io/blog/copy-paste-ssh-workspace-access [github-codespaces]: https://github.com/features/codespaces diff --git a/docs/introduction/dev-environment-quick-start-guide.md b/docs/introduction/dev-environment-quick-start-guide.md index b5714ac601738..e3a24e63e44ae 100644 --- a/docs/introduction/dev-environment-quick-start-guide.md +++ b/docs/introduction/dev-environment-quick-start-guide.md @@ -1,11 +1,8 @@ # Dev environment quick start guide -[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/https://github.com/openfoodfacts/openfoodfacts-server/) -> Gitpod will automatically clone and build the repository for you and comes with Docker pre-installed. It is one of the fastest -> ways to spin up an environment for `openfoodfacts-servbr`, but requires some additional setup to access your development deployment documented -> in [use-gitpod how-to](../how-to-guides/use-gitpod.md). - This guide will allow you to rapidly build a ready-to-use development environment for **Product Opener** running in Docker. +As an alternative to setting up your environment locally, follow the [Gitpod how-to guide](../how-to-guides/use-gitpod.md) +to instantly provision a ready-to-code development environment in the cloud. First setup time estimate is `~10min` with the following specs: * `8 GB` of RAM dedicated to Docker client @@ -111,7 +108,7 @@ make dev ``` > **Note:** -> +> > If docker complains about > ``` > ERROR: could not find an available, non-overlapping IPv4 address pool among the defaults to assign to the network