diff --git a/.github/DISCUSSION_TEMPLATE/ideas.yml b/.github/DISCUSSION_TEMPLATE/ideas.yml new file mode 100755 index 000000000..2c0922bb2 --- /dev/null +++ b/.github/DISCUSSION_TEMPLATE/ideas.yml @@ -0,0 +1,35 @@ +title: '[Ideas and Feature Requests] ' +labels: ['rfc'] +body: + - type: markdown + attributes: + value: | + Have an idea or a proposal for a new feature? Submit an RFC! + + > See our [RFC process documentation](https://github.com/andrew-codes/playnite-web/blob/main/docs/contributing/rfc.md) for more information. + - type: input + id: title + attributes: + label: Title + description: A short description of your idea or proposal + validations: + required: true + - type: textarea + id: rfc_goal + attributes: + label: Goal + description: Describe your proposal in one or two paragraphs. Focus on the goal, without diving too deeply into the "why", "why now", "how", etc. Ensure anyone opening the document will form a clear understanding of the RFCs intent from reading this paragraph(s). + validations: + required: true + - type: textarea + id: rfc_background + attributes: + label: Background + description: Provide the full context for the RFC. This should include the problem you're trying to solve, the current state of things, and any relevant history. This may include any links to additional resources, discussions, or other relevant information. + required: true + - type: textarea + id: rfc_proposal + attributes: + label: Proposal + description: Describe your proposed solution. This should be a detailed explanation of what you're proposing, and how it will solve the problem you've outlined in the background section. + required: true diff --git a/.github/workflows/nightly.yaml b/.github/workflows/main.yml similarity index 99% rename from .github/workflows/nightly.yaml rename to .github/workflows/main.yml index 463128ae3..47ce10283 100755 --- a/.github/workflows/nightly.yaml +++ b/.github/workflows/main.yml @@ -1,10 +1,9 @@ -name: 'Publish latest major- and minor-versions' +name: 'Latest dev version' on: push: branches: - main - - release-* permissions: contents: read diff --git a/.github/workflows/publish-release.yaml b/.github/workflows/publish-release.yml similarity index 100% rename from .github/workflows/publish-release.yaml rename to .github/workflows/publish-release.yml diff --git a/.github/workflows/pull-request-release-closed.yaml b/.github/workflows/pull-request-release-closed.yml similarity index 100% rename from .github/workflows/pull-request-release-closed.yaml rename to .github/workflows/pull-request-release-closed.yml diff --git a/.github/workflows/pull-request-release.yaml b/.github/workflows/pull-request-release.yml similarity index 100% rename from .github/workflows/pull-request-release.yaml rename to .github/workflows/pull-request-release.yml diff --git a/README.md b/README.md index 3d622233e..bb2665067 100755 --- a/README.md +++ b/README.md @@ -1,8 +1,36 @@ # Playnite-Web -Share your game library online with self-hosted Playnite-Web. - -![Browse screenshot](__docs/browse-screenshot.png) +[![Build Status](https://github.com/andrew-codes/playnite-web/actions/workflows/main.yml/badge.svg)](https://github.com/andrew-codes/playnite-web/actions/workflows/main.yml) +[![Latest Release](https://img.shields.io/github/v/release/andrew-codes/playnite-web)](https://github.com/andrew-codes/playnite-web/releases/latest) +[![License](https://img.shields.io/github/license/andrew-codes/playnite-web)](https://github.com/andrew-codes/playnite-web?tab=AGPL-3.0-1-ov-file#readme) +[![GitHub Sponsors](https://img.shields.io/github/sponsors/andrew-codes)](https://github.com/sponsors/andrew-codes) +![Discord](https://img.shields.io/discord/1247204516756066377) + +Share and remote control your game library online with self-hosted Playnite-Web. + +Playnite-web offers: + +- a beautiful web UI for your Playnite library to share with friends +- remote control of staring and stopping games with home automation; locked behind a username/password login screen +- a graph API to help you build other unique experiences + +![Browse screenshot](docs/assets/images/browse-screenshot.png) + +## Table of Contents + +- [Playnite-Web](#playnite-web) + - [Table of Contents](#table-of-contents) + - [Getting Started](#getting-started) + - [Deployment](#deployment) + - [MQTT Broker](#mqtt-broker) + - [Database](#database) + - [Playnite-Web Plugin](#playnite-web-plugin) + - [game-db-updater](#game-db-updater) + - [Environment Variables](#environment-variables) + - [playnite-web-app](#playnite-web-app) + - [Environment Variables](#environment-variables-1) + - [Post Deployment Steps](#post-deployment-steps) + - [Contributing](#contributing) ## Getting Started @@ -44,9 +72,9 @@ Recommended to use docker image [`mongo:focal`](https://hub.docker.com/_/mongo/) 1. Download (latest) version [release](https://github.com/andrew-codes/playnite-web/releases) of Playnite extension (release asset named "PlayniteWeb_ec3439e3-51ee-43cb-9a8a-5d82cf45edac_0_1.pext"). 1. Open Playnite and drag downloaded file into the Playnite. It should prompt to install the plugin. 1. Open the plugin's settings and enter the MQTT connection information to your MQTT broker. - > ![Mqtt connection settings screenshot](__docs/mqtt-connection-screenshot.png) + > ![Mqtt connection settings screenshot](docs/assets/images/mqtt-connection-screenshot.png) 1. Open the plugin's settings and enter the a device ID and device name under Topics. - > ![Topics settings screenshot](__docs/topics-screenshot.png) + > ![Topics settings screenshot](docs/assets/images/topics-screenshot.png) #### game-db-updater @@ -54,18 +82,18 @@ Use the docker [packaged image](https://github.com/andrew-codes/playnite-web/pkg ##### Environment Variables -| Environment Variable | Value | Notes | -| :------------------- | :--------------------------------------- | :--------------------------------------------------- | -| MQTT_HOST | IP address/hostname of MQTT broker. | | -| MQTT_PORT | Port of MQTT broker | Default for MQTT image is 1883 | -| MQTT_USERNAME | Username to access MQTT broker | Optional, only required if disabled anonymous access | -| MQTT_PASSWORD | Password to access MQTT broker | Optional, only required if disabled anonymous access | -| DB_HOST | IP address/hostname of Mongo DB database | | -| DB_PORT | Port of Mongo DB database | Default for MongoDB image is 27017 | -| DB_USERNAME | Username to access database | Optional, only required if disabled anonymous access | -| DB_PASSWORD | Password to access database | Optional, only required if disabled anonymous access | +| Environment Variable | Value | Notes | +| :------------------- | :--------------------------------------- | :-------------------------------------------------------- | +| MQTT_HOST | IP address/hostname of MQTT broker. | | +| MQTT_PORT | Port of MQTT broker | Default for MQTT image is 1883 | +| MQTT_USERNAME | Username to access MQTT broker | Optional, only required if disabled anonymous access | +| MQTT_PASSWORD | Password to access MQTT broker | Optional, only required if disabled anonymous access | +| DB_HOST | IP address/hostname of Mongo DB database | | +| DB_PORT | Port of Mongo DB database | Default for MongoDB image is 27017 | +| DB_USERNAME | Username to access database | Optional, only required if disabled anonymous access | +| DB_PASSWORD | Password to access database | Optional, only required if disabled anonymous access | | DB_URL | MongoDB connection URL | Optional, alternative to individual DB connection options | -| DEBUG | `"game-db-updater/*"` | Optional, for troubleshooting; send logs to STDIO | +| DEBUG | `"game-db-updater/*"` | Optional, for troubleshooting; send logs to STDIO | #### playnite-web-app @@ -73,25 +101,31 @@ Use the docker [packaged image](https://github.com/andrew-codes/playnite-web/pkg ##### Environment Variables -| Environment Variable | Value | Notes | -| :------------------- | :--------------------------------------- | :--------------------------------------------------- | -| PORT | Defaults to 3000 | Port in which web application is accessible. | -| DB_HOST | IP address/hostname of Mongo DB database | | -| DB_PORT | Port of Mongo DB database | Default for MongoDB image is 27017 | -| DB_USERNAME | Username to access database | Optional, only required if disabled anonymous access | -| DB_PASSWORD | Password to access database | Optional, only required if disabled anonymous access | +| Environment Variable | Value | Notes | +| :------------------- | :--------------------------------------- | :-------------------------------------------------------- | +| PORT | Defaults to 3000 | Port in which web application is accessible. | +| DB_HOST | IP address/hostname of Mongo DB database | | +| DB_PORT | Port of Mongo DB database | Default for MongoDB image is 27017 | +| DB_USERNAME | Username to access database | Optional, only required if disabled anonymous access | +| DB_PASSWORD | Password to access database | Optional, only required if disabled anonymous access | | DB_URL | MongoDB connection URL | Optional, alternative to individual DB connection options | -| DEBUG | `"playnite-web/*"` | Optional, for troubleshooting; send logs to STDIO | -| USERNAME | | Username used to login | -| PASSWORD | | Password value used to login | -| SECRET | | Secret used to protect credentials | -| MQTT_HOST | IP address/hostname of MQTT broker. | | -| MQTT_PORT | Port of MQTT broker | Default for MQTT image is 1883 | -| MQTT_USERNAME | Username to access MQTT broker | Optional, only required if disabled anonymous access | -| MQTT_PASSWORD | Password to access MQTT broker | Optional, only required if disabled anonymous access | +| DEBUG | `"playnite-web/*"` | Optional, for troubleshooting; send logs to STDIO | +| USERNAME | | Username used to login | +| PASSWORD | | Password value used to login | +| SECRET | | Secret used to protect credentials | +| MQTT_HOST | IP address/hostname of MQTT broker. | | +| MQTT_PORT | Port of MQTT broker | Default for MQTT image is 1883 | +| MQTT_USERNAME | Username to access MQTT broker | Optional, only required if disabled anonymous access | +| MQTT_PASSWORD | Password to access MQTT broker | Optional, only required if disabled anonymous access | ### Post Deployment Steps 1. Open Playnite and select and "Sync Library" from Playnite Web's menu setting. This is only required once. - > ![Sync Library menu setting](__docs/sync-library-menu-setting.png) + > ![Sync Library menu setting](docs/assets/images/sync-library-menu-setting.png) 1. Navigate to the web app; `http://$PLAYNITE_WEB_APP_IP:$PORT` + +## Contributing + +1. Read through our [contributing guidelines](docs/CONTRIBUTING.md). +2. Next, read and set up your [development environment](docs/contributing/development-environment.md). +3. Additionally, refer to the [design docs](docs/design). diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100755 index 000000000..f60cb8dfe --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,56 @@ +# Contributing + +[![Build Status](https://github.com/andrew-codes/playnite-web/actions/workflows/main.yml/badge.svg)](https://github.com/andrew-codes/playnite-web/actions/workflows/main.yml) +[![Latest Release](https://img.shields.io/github/v/release/andrew-codes/playnite-web)](https://github.com/andrew-codes/playnite-web/releases/latest) +[![License](https://img.shields.io/github/license/andrew-codes/playnite-web)](https://github.com/andrew-codes/playnite-web?tab=AGPL-3.0-1-ov-file#readme) +[![GitHub Sponsors](https://img.shields.io/github/sponsors/andrew-codes)](https://github.com/sponsors/andrew-codes) +![Discord](https://img.shields.io/discord/1247204516756066377) + +## How to contribute to Playnite-Web + +- [Contributing](#contributing) + - [How to contribute to Playnite-Web](#how-to-contribute-to-playnite-web) + - [Did you find a bug?](#did-you-find-a-bug) + - [Did you write a patch that fixes a bug?](#did-you-write-a-patch-that-fixes-a-bug) + - [Did you fix whitespace, format code, or make a purely cosmetic patch?](#did-you-fix-whitespace-format-code-or-make-a-purely-cosmetic-patch) + - [Do you intend to add a new feature or change an existing one?](#do-you-intend-to-add-a-new-feature-or-change-an-existing-one) + - [Do you have questions about the source code?](#do-you-have-questions-about-the-source-code) + - [Thank you](#thank-you) + +### Did you find a bug? + +- **Do not open up a GitHub issue if the bug is a security vulnerability**, and instead refer to our [security policy](./SECURITY.md). + +- **Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/andrew-codes/playnite-web/issues). + +- If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/andrew-codes/playnite-web/issues/new). Be sure to include a **title and clear description**, as much relevant information as possible, and any relevant screenshots demonstrating the expected behavior that is not occurring. **Do not include sensitive information into the issue.** + +### Did you write a patch that fixes a bug? + +- Open a new GitHub pull request with the patch. + +- Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable. + +- Before submitting, please read the [Playnite-Web Conventions](contributing/conventions.md) guide to know more about coding conventions and general guidelines. + +### Did you fix whitespace, format code, or make a purely cosmetic patch? + +Changes that are cosmetic in nature and do not add anything substantial to the stability, functionality, or testability of Rails will generally not be accepted. + +### Do you intend to add a new feature or change an existing one? + +- [Create an ideas discussion](https://github.com/andrew-codes/playnite-web/discussions/new?category=ideas) using the pre-defined template. + +- Do not open an issue on GitHub until you have collected positive feedback about the change. GitHub issues are primarily intended for bug reports and fixes. + +- Learn more about the [RFC](contributing/rfc.md) feature request process. + +### Do you have questions about the source code? + +- Ask any question about Playnite-Web by joining our [Discord](https://discord.gg/J9rNp4C5mC). + +## Thank you + +Playnite-Web is a volunteer effort and we encourage you to pitch in and join! + +Thanks! :heart: :heart: :heart: diff --git a/docs/SECURITY.md b/docs/SECURITY.md new file mode 100755 index 000000000..30cfd43ee --- /dev/null +++ b/docs/SECURITY.md @@ -0,0 +1,6 @@ +# Security + +## I found a security vulnerability + +1. **Do not open up a GitHub issue if the bug is a security vulnerability** +2. Do send a direct message on Discord to [andrew-codes](https://discord.com/users/106497686798094336) diff --git a/__docs/browse-screenshot.png b/docs/assets/images/browse-screenshot.png similarity index 100% rename from __docs/browse-screenshot.png rename to docs/assets/images/browse-screenshot.png diff --git a/__docs/mqtt-connection-screenshot.png b/docs/assets/images/mqtt-connection-screenshot.png similarity index 100% rename from __docs/mqtt-connection-screenshot.png rename to docs/assets/images/mqtt-connection-screenshot.png diff --git a/__docs/sync-library-menu-setting.png b/docs/assets/images/sync-library-menu-setting.png similarity index 100% rename from __docs/sync-library-menu-setting.png rename to docs/assets/images/sync-library-menu-setting.png diff --git a/__docs/topics-screenshot.png b/docs/assets/images/topics-screenshot.png similarity index 100% rename from __docs/topics-screenshot.png rename to docs/assets/images/topics-screenshot.png diff --git a/docs/contributing/conventions.md b/docs/contributing/conventions.md new file mode 100755 index 000000000..e69de29bb diff --git a/docs/contributing/development-environment.md b/docs/contributing/development-environment.md new file mode 100755 index 000000000..e69de29bb diff --git a/docs/contributing/rfc.md b/docs/contributing/rfc.md new file mode 100755 index 000000000..405b4a492 --- /dev/null +++ b/docs/contributing/rfc.md @@ -0,0 +1,14 @@ +# RFC Process + +Please open a discussion item under [Ideas](https://github.com/andrew-codes/playnite-web/discussions/new?category=ideas) to submit feature requests and other ideas. This will provide a public forum for you, the team, and the community to discuss your ideas. + +Once a proposal is accepted, the discussion will be locked/closed with a link to a new GitHub issue created by the Playnite-web team. From there, you can track the progress towards the new feature. + +## Anatomy of an RFC + +| | | +| :--------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Title | A short description of your idea or proposal | +| Goal | Describe your proposal in one or two paragraphs. Focus on the goal, without diving too deeply into the "why", "why now", "how", etc. Ensure anyone opening the document will form a clear understanding of the RFCs intent from reading this paragraph(s). | +| Background | Provide the full context for the RFC. This should include the problem you're trying to solve, the current state of things, and any relevant history. This may include any links to additional resources, discussions, or other relevant information. | +| Proposal | Describe your proposed solution. This should be a detailed explanation of what you're proposing, and how it will solve the problem you've outlined in the background section. | diff --git a/docs/design/README.md b/docs/design/README.md new file mode 100755 index 000000000..e69de29bb