From a5aec2b1fbd889776a0420632ee13bf07cc394d2 Mon Sep 17 00:00:00 2001 From: Zack Krida Date: Wed, 22 Feb 2023 08:48:45 -0500 Subject: [PATCH 1/3] Monorepo archive notice --- README.md | 342 +----------------------------------------------------- 1 file changed, 3 insertions(+), 339 deletions(-) diff --git a/README.md b/README.md index 976f4f80ea..13063ff2d4 100644 --- a/README.md +++ b/README.md @@ -1,341 +1,5 @@ - +# This repository has moved -

- Project Board | Community Site | #openverse @ Slack | Handbook | Figma Mockups | Figma Design Library -

+The Openverse frontend is now part of the Openverse monorepo. Please use https://github.com/wordpress/openverse instead. -# Openverse Frontend - -![openverse-frontend-ci](https://github.com/wordpress/openverse-frontend/workflows/openverse-frontend-ci/badge.svg) - -This repository is the frontend UI for accessing and exploring the -openly-licensed content provided by the -[Openverse API](https://github.com/wordpress/openverse-api). - -You can view [the application](https://wordpress.org/openverse) live on -WordPress.org. - -## Technology - -The frontend app is built using [Vue.js](https://vuejs.org/) and -[Nuxt.js](https://nuxtjs.org). - -## Local Development - -**Note for Windows users:** Please use -[WSL](https://docs.microsoft.com/en-us/windows/wsl/install) for developing on -the Openverse frontend. Several scripts, primarily support scripts, rely on a -general \*nix type environment. Maintaining parity for cross platform scripts -proved complicated without significant duplication. If you run into issues with -running the Openverse frontend in WSL please let us know by opening an issue or -[joining us on Slack](https://make.wordpress.org/chat/) in the `#openverse` room -and ask for help. - -We use [Volta](https://volta.sh/) to manage our local environment tools. Please -install it using the instructions on their website. - -Before installing pnpm, make sure to switch to node version 16 using Volta: - -```bash -volta install node@16 -``` - -Once you have volta installed, manually install `pnpm` using volta. -[Volta does not currently officially support `pnpm`](https://github.com/volta-cli/volta/issues/737) -so this is a stop gap solution until that support is implemented: - -```bash -volta install pnpm -``` - -Run the following commands in order to have the code up and running on your -machine: - -```bash -# Builds and serves assets with hot-reload -# Automatically invokes pnpm install and pnpm i18n -volta run pnpm dev -``` - -If you intend to change any text in the app, you will need to edit -`src/locales/scripts/en.json5`. To ensure your changes are reflected -immediately, run the following command. - -```bash -# Watches the en.json5 file and updates the en.json file for every change. -pnpm i18n:watch-en -``` - -### Using HTTPS Locally - -To enable SSL support in local development, use the `pnpm dev:secure` command. -This requires you to have a private key and certificate in the root of the -repository with the following names: - -```shell -localhost+1-key.pem # The private key file -localhost+1.pem # The certificate file -``` - -The easiest way to create these files is with a local development tool called -[mkcert](https://github.com/FiloSottile/mkcert). First make sure you have -[mkcert installed](https://github.com/FiloSottile/mkcert#installation) and -activated with `mkcert -install`. Then use `mkcert` to create a certificate for -`localhost` and for the external IP address used by Nuxt's development process. -That command looks like this: - -```shell -mkcert localhost 192.168.50.119 -``` - -Be sure to replace the IP address in the example with your own. See the next -section for how to identify that IP address. - -#### Finding your local IP address - -You can find the local IP address Nuxt uses by looking at the output of -`nuxt dev`. Look in your console for a box of configuration details that looks -like this: - -```bash -# ╭───────────────────────────────────────────╮ -# │ │ -# │ Nuxt @ v2.15.8 │ -# │ │ -# │ ▸ Environment: development │ -# │ ▸ Rendering: server-side │ -# │ ▸ Target: server │ -# │ │ -# │ Listening: http://192.168.50.119:8443/ │ # <-- Use this IP Address -# │ │ -# ╰───────────────────────────────────────────╯ -``` - -You will need to regenerate the certificate if this IP address changes for any -reason, like by enabling a VPN or changing networks. - -### Choosing which API to use - -You don't need to have the Openverse API running locally to be able to run the -frontend application. It's configured to communicate, by default, with the -[production API](https://api.openverse.engineering) that's already publicly -available. If you need to test against changes in your local API, set the -`API_URL` environment variable when run the development server. - -```shell -API_URL=http://localhost:8000 pnpm dev -``` - -### Standalone and embedded modes - -The application can run in two modes. By default, it runs in embedded mode, -which is loaded in an iframe on -[WordPress.org/openverse](https://make.wordpress.org/openverse). It has a small -header without logo and no footer. The standalone mode which has a large header -with logo and a footer, can be enabled by adding `?embedded=false` query -parameter to the URL. For example, when running locally, you can go to -[http://localhost:8443?embedded=false](http://localhost:8443?embedded=false) to -view the standalone application. - -### Running tests - -Refer to the [`TESTING_GUIDELINES.md` file](./TESTING_GUIDELINES.md) for -instructions on how to run tests. - -### localhost tunneling - -If you want to make your local development server accessible to the internet -(for testing or showing someone something you're working on), you can use -[`ngrok`](https://ngrok.com/). Follow the documentation on the `ngrok` site to -install it and set it up. Once you have it installed, get the development server -for Openverse running and in a separate window/tab, run: - -``` -# The extra parameters are required to ensure that ngrok redirects to the HTTPS version of the site -# and that the host header matches one that is accepted by the server -# (ngrok's default hostname is randomly generated and is not whitelisted). -ngrok http http://localhost:8443 -host-header="localhost:8443" -``` - -If you need to run an HTTP version (for example, if you're testing against -third-party websites that do not accept the self-signed certificate generated by -the dev server), run the dev server using `pnpm dev` and use the following -command to start `ngrok`: - -```bash -ngrok http 8443 -host-header="localhost:8443" -``` - -## Frontend Components - -The frontend app is composed of a number of components that are documented in -our [Storybook](https://wordpress.github.io/openverse-frontend). - -### How to create a component - -To create a component you can run: - -```shell -# Make sure you have run `pnpm install` at least once before. -pnpm run create:component [component name in PascalCase] -for example: pnpm run create:component VButtonGreen -``` - -This command will create a component file, a story file for the component, a -unit test file, and a regression test file. It also adds the component name to -tsconfig.ts `include` property. Each file will have a basic template to start -working with. We use the -[itsjonq/remake](https://www.npmjs.com/package/@itsjonq/remake?activeTab=readme) -package to create files out of templates. - -You can also create all those files manually by running the following commands: - -create a component file - -``` -pnpm run create:component-sfc --output=[path] --name=[component name] -``` - -create a story file - -``` -pnpm run create:story --output=[path] --name=[component name] -``` - -create a component unit test file - -``` -pnpm run create:component-unit-test --output=[path] --name=[component name] --fileName=[component name in kebab-case] -``` - -create a component regression test file - -``` -pnpm run create:component-storybook-test --output=[path] --name=[component name kebab-case] --fileName=[component name in kebab-case] -``` - -### CSS Framework - -To design our components, we use the [TailwindCSS](https://tailwindcss.com/) -utility-first CSS framework. We have compiled a list of TailwindCSS classes that -are used in the frontend app. You can view the list -[here](https://wordpress.github.io/openverse-frontend/tailwind/). - -### Development Tips - -If you use VS Code, you can install the -[Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) -extension to get autocomplete for TailwindCSS classes. - -## Docker and Openverse frontend - -We do not currently support local development using Docker or `docker-compose`. -It was supported in the past, but it was not used by the core contributors. It -remained broken for many months without ever being noticed, so the assumption is -that it was also not being used active community members. Local `nuxt` -development is still easy across platforms, so maintaining a separate Docker -development stack for the frontend did not make sense. - -However, we do build and actively deploy the frontend using Docker images. If -you wish to build the production image for yourself, run the following: - -```shell -pnpm docker:build -``` - -You can also find the latest `openverse-frontend` images on our -[GitHub packages page](https://github.com/WordPress/openverse-frontend/pkgs/container/openverse-frontend). - -You can then run using either the locally built image or the `ghcr.io` image -from the link above: - -```shell -pnpm docker:run -``` - -The app will be available at . - -> **Note**: If you are _not_ using HTTPS locally, do not use the URL provided by -> Nuxt - this will cause certificate errors because it gets rerouted to HTTPS. -> E.g. this link will not work: -> -> ``` -> $ pnpm docker:run -> -> > openverse-frontend@2.2.1 start -> > nuxt start -> -> ℹ Sentry reporting is disabled ("disabled" option has been set) nuxt:sentry 18:22:32 -> -> ╭─────────────────────────────────────────╮ -> │ │ -> │ Nuxt @ v2.15.8 │ -> │ │ -> │ ▸ Environment: production │ -> │ ▸ Rendering: server-side │ -> │ ▸ Target: server │ -> │ │ -> │ Memory usage: 48.2 MB (RSS: 152 MB) │ -> │ │ -> │ Listening: http://172.17.0.2:8443/ │ <-- Won't work unless HTTPS is set up -> │ │ -> ╰─────────────────────────────────────────╯ -> ``` - -## Formatting and Linting - -The code in this repository is formatted using `prettier`. If you have prettier -setup in your code editor it should work out of the box; otherwise you can use -the `pnpm lint:fix` script to format and fix lint errors in your code. Checks -are run to lint your code and validate the formatting on git precommit using -[husky](https://github.com/typicode/husky). - -You will need to fix any linting issues before committing. We recommend -formatting your JavaScript files on save in your text editor. You can learn how -to do this in Visual Studio Code -[here](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode#format-on-save). - -### File name conventions - -All files and folders should be written in `kebab-case`, with the exception of -Vue single file components. If it ends in `.vue`, please use `PascalCase`. This -distinction makes our component files stand out clearly and is -[recommended by the Vue community](https://vuejs.org/v2/style-guide/#Single-file-component-filename-casing-strongly-recommended). - -## Redirects - -| From | To | Status code | Setup level | -| ------------ | ----------- | ----------- | ---------------------- | -| /photos/\_id | /image/\_id | 301 | Nuxt server middleware | - -## Just - -If [`just`](https://github.com/casey/just) is your preferred command runner, you -can also use `just run {script}` to run any pnpm script and `just` on its own to -list the available scripts (e.g. `just run docker:build`). Our other projects -use `just` as their primary script runner, so this allows parity with both the -API and the catalog. - -## Contributing - -Pull requests are welcome! Feel free to -[join us on Slack](https://make.wordpress.org/chat/) and discuss the project -with the engineers and community members on #openverse. - -You are welcome to take any open issue in the tracker labeled -[`help wanted`](https://github.com/wordpress/openverse-frontend/labels/help%20wanted) -or -[`good first issue`](https://github.com/wordpress/openverse-frontend/labels/good%20first%20issue); -**there's no need to ask for permission in advance**. Other issues are open for -contribution as well, but may be less accessible or well defined in comparison -to those that are explicitly labeled. - -## Acknowledgments - -Openverse, previously known as CC Search, was conceived and built at -[Creative Commons](https://creativecommons.org). We thank them for their -commitment to open source and openly licensed content, with particular thanks to -previous team members @ryanmerkley, @janetpkr, @lizadaly, @sebworks, @pa-w, -@kgodey, @annatuma, @mathemancer, @aldenstpage, @brenoferreira, and @sclachar, -along with their -[community of volunteers](https://opensource.creativecommons.org/community/community-team/). +The frontend code can specifically be found in the [`./frontend/` directory](https://github.com/WordPress/openverse/tree/main/frontend). From 285fac1d88826ac44d7c7d532a658f761619e6be Mon Sep 17 00:00:00 2001 From: Zack Krida Date: Wed, 22 Feb 2023 09:53:57 -0500 Subject: [PATCH 2/3] Update README.md Co-authored-by: Dhruv Bhanushali --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 13063ff2d4..d6838c5cf0 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ # This repository has moved -The Openverse frontend is now part of the Openverse monorepo. Please use https://github.com/wordpress/openverse instead. +The Openverse frontend is now part of the Openverse monorepo. Please use https://github.com/WordPress/openverse instead. The frontend code can specifically be found in the [`./frontend/` directory](https://github.com/WordPress/openverse/tree/main/frontend). From a1aa2e3aa0e575fb2131ea6847a94271d1f178e5 Mon Sep 17 00:00:00 2001 From: Zack Krida Date: Wed, 22 Feb 2023 11:36:04 -0500 Subject: [PATCH 3/3] Format README --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d6838c5cf0..25ce2255d5 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # This repository has moved -The Openverse frontend is now part of the Openverse monorepo. Please use https://github.com/WordPress/openverse instead. +The Openverse frontend is now part of the Openverse monorepo. Please use +https://github.com/WordPress/openverse instead. -The frontend code can specifically be found in the [`./frontend/` directory](https://github.com/WordPress/openverse/tree/main/frontend). +The frontend code can specifically be found in the +[`./frontend/` directory](https://github.com/WordPress/openverse/tree/main/frontend).