diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d423bf06..0a59c0ad 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,113 +1,31 @@ -# Contributing to Presenter +# Contributing -Thank you for your interest in participating! +Anyone providing assistance to the future of this project is considered a contributor. If you wish to play a part in this project, then thank you! This document outlines some of the ways to help. -There are many ways to contribute, beyond writing code or programming, by: logging bugs, reporting issues, and creating suggestions. To do so, please [create a ticket](https://github.com/shabados/presenter/issues/new) in our issue tracker. (See other ways to [Contribute](README.md#Contributing) or give [Feedback](README.md#Feedback). +The easiest way to communicate is via [GitHub issues](https://github.com/shabados/presenter/issues). Please search for similar issues regarding your concerns before opening a new issue. For everything else we ask to chat about it on [GitHub Discussions](https://github.com/orgs/shabados/discussions) or [Slack](https://chat.shabados.com/). -This document is for developers or programmers contributing to the source code of Presenter. - -**Table of Contents** - -- [Getting Started](#getting-started) - - [Prerequisites](#prerequisites) - - [Build](#build) - - [Start](#start) - - [Run](#run) - - [Package](#package) -- [Codebase Overview](#codebase-overview) -- [Workflow](#workflow) - - [Coding Guidelines](#coding-guidelines) - - [Scope](#scope) -- [Thank you](#thank-you) - -## Getting Started - -If you wish to better understand how Presenter works or want to debug an issue: get the source, build it, and run it locally. - -### Prerequisites - -In order to download necessary tools, clone the repository, and install dependencies, you'll need network access. +## Build & Run You'll need the following: - [Git](https://git-scm.com/) - [Node.JS](https://nodejs.org) (If you need to manage multiple Node.JS versions, [use a node version manager](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) to install) +- Source code of `presenter` repo -Get the source code of `presenter` repo: +E.g. ```shell gh repo fork shabados/presenter --clone=true ``` -**PROTIP**: Use the [`gh` cli tool from GitHub](https://cli.github.com/) to fork the repo to your GitHub account (if not already), clone it to your local machine, and set the appropriate remotes for origin and upstream with the above command. - - +Produce a tree-map of the bundle and look for potential bloat with at least one `npm run build` and then as many `npm run analyze` commands. -### Build - -Run `npm i` in the root directory. - -### Start - -```shell -npm start -``` - -Use the above command to spin up development servers. It will launch a frontend server on [port `3000`](https://localhost:3000) and a backend server on [port `42425`](https://localhost:42425). Any changes to the backend will result in the server restarting. A manual restart can be triggered by entering `rs` into the terminal. - -### Run - -Usage: - -```shell -npm run -``` - -The commands are: - -```shell -lint # ESLint all files -lint:backend # ESLint files in app/ -lint:frontend # ESLint files in app/frontend/ -start:backend # Start app/ -start:frontend # Start app/frontend/ -start:electron # Start electron in app/ -build # Use react-app-rewired to build in app/frontend -install-deps # Run npm install for entire project -install-deps:backend # Run npm install in app/ -install-deps:frontend # Run npm install in app/frontend/ -pack # Create a binary -dist # Create an installer -release # Create an installer (duplicate) -``` - -Run `npm run` or open the `package.json` file(s) for a full list of commands. - -To produce a tree-map of the bundle and look for potential bloat, run `npm run build` at least once, and then `npm run analyze`. - -### Package +## Package Electron-builder is used to generate binaries. Run `npm run pack` for the binaries to test on your platform, and `npm run dist` to build an installer. The production builds launch a frontend server on port `1699` and backend server port `42424`. @@ -119,36 +37,18 @@ The frontend is using `create-react-app`, websockets for synchronizing clients, The backend is using proposed ES+ modules with the `esm` shim module. -## Workflow - -The workflow of development (or Git Flow) is to [choose/create an issue](https://github.com/shabados/presenter/issues) to work on, [create a feature branch](https://docs.shabados.com/community/how-to-contribute#branches), and [submit a pull request](https://docs.shabados.com/community/how-to-contribute#pull-requests). - -**PROTIP**: Read more about our workflow (issue tracking, branching, and pull requests) in the [How To Contribute wiki article](https://github.com/shabados/.github/wiki/How-to-Contribute). +## Workflow & Coding Guidelines -### Coding Guidelines +Please see [our docs for coding guidelines](https://www.shabados.com/docs/community/coding-guidelines/). -Please see the [docs](https://docs.shabados.com/community/coding-guidelines) for Coding Guidelines ([Names](https://docs.shabados.com/community/coding-guidelines#names), [Comments](https://docs.shabados.com/community/coding-guidelines#comments), [Style](https://docs.shabados.com/community/coding-guidelines#style), [Linting](https://docs.shabados.com/community/coding-guidelines#linting), and [Commit Messages](https://docs.shabados.com/community/coding-guidelines#commit-messages)). +**Scopes** -### Scope - -To be used in [commit messages](https://docs.shabados.com/community/coding-guidelines#commit-messages). - -Usage: - -```shell -(): -``` - -The scopes are: - -```shell -backend -frontend/controller -frontend/overlay -frontend/presenter -frontend/settings -``` +- backend +- frontend/controller +- frontend/overlay +- frontend/presenter +- frontend/settings -## Thank you +## Thank You -Your contributions to open source, large or small, make great projects like this possible. Thank you for taking the time to participate in this project. +Your contributions to open source (large or small!) make great projects like this possible. Thank you for taking the time to participate in this project. diff --git a/README.md b/README.md index 38a631ab..d4861650 100644 --- a/README.md +++ b/README.md @@ -1,42 +1,20 @@ -Shabad OS - # Presenter Software for searching, navigating, and presenting the Shabad OS Database -[![Release][release-image]][release-url] -[![Next Release][next-image]][next-url] - -**Table of Contents** - -- [Introduction](#introduction) - - [Features](#features) - - [Screenshots](#screenshots) -- [Community](#community) -- [Contributing](#contributing) -- [People](#people) -- [Feedback](#feedback) -- [Related Projects](#related-projects) -- [Code of Conduct](#code-of-conduct) -- [License](#license) - -## Introduction - -The Shabad OS Presenter is a GPL-licensed open source project with ongoing development, project management, and marketing made possible entirely by the support and dedication of unpaid volunteers. - -This app can be used to display bani & gurbani in the home or at the gurdwara. A server model allows multiple devices to act as a display or a controller. The same model enables live captions to be in sync with the projector / presentation device. +## About -Helpful features were added over years of production-ready use. +Shabad OS Presenter can be used to display bani & gurbani in the home or at the gurdwara. A server model allows multiple devices to act as a display or a controller. The same model enables live captions to be in sync with the projector / presentation device. -See: +For more, please see: -- [Our Website][website-url] -- [How to install](https://docs.shabados.com/presenter/guides/installing-shabad-os-presenter) -- [How to add live stream captions](https://docs.shabados.com/presenter/guides/configuring-live-stream-captions) +- [Our Website](https://www.shabados.com/) +- [Install Shabad OS Presenter](https://www.shabados.com/support/install-shabad-os-presenter/) +- [How to Add Bani Captions to a Live Stream](https://www.shabados.com/support/add-bani-captions-to-a-live-stream/) -### Features +## Features -- Multiple displays and controllers in sync +- Multiple displays and controllers synced together - Live broadcast captioning / subtitling - Curated design - Text legibility/readability @@ -46,85 +24,27 @@ See: - Jump to line _N_ of shabad - Autoselect line based on context/position -### Screenshots +## Screenshots -## Community - -Get updates on Shabad OS and chat with the project maintainers and community members. - -- [![Instagram][instagram-image]][instagram-url] Follow Shabad OS on Instagram -- [![Twitter][twitter-image]][twitter-url] Follow Shabad OS on Twitter. -- [![Chat][chat-image]][chat-url] Join the official Slack channel. - -## Contributing - -There are multiple ways to contribute whether you are a user or developer. For example: +## Contribute -- [Submit bugs and feature requests][new-issue-url]. -- Review documentation and make pull requests for anything from typos to new content. -- Give feedback on the onboarding process to make it easier for others to join the project. +If you want to help, please get started with the [CONTRIBUTING.md](./CONTRIBUTING.md) doc. -If you're interested in contributing to the source code of Presenter, then please see [Contributing Guidelines](./CONTRIBUTING.md). - -## People - -The original authors are Bhajneet & Bhajanpreet Singh ([@bhajneet](https://github.com/bhajneet) & [@bhajansweet](https://github.com/bhajansweet)). - -The current lead maintainer is Harjot Singh ([@harjot1singh](https://github.com/harjot1singh)). - -"Thank you!" to [all the volunteers][contributor-url] who've contributed to Presenter. - -## Feedback - -- Ask questions and get help in our community chat via [Slack][chat-url] -- [Upvote popular feature requests][upvote-tracker-url] using the thumbs-up/+1 reaction on the first post of a feature request -- Follow [@shabad_os on Instagram](instagram-url) and [@shabad_os on Twitter](twitter-url) and let us know what you think! - -## Related Projects - -Projects in the Shabad OS ecosystem of free and open source software include: - -- [Database](https://github.com/shabados/database) -- [Viewer](https://github.com/shabados/viewer) -- [Mobile](https://github.com/shabados/mobile) -- [Gurmukhi Utils](https://github.com/shabados/gurmukhi-utils) - -## Code of Conduct +## Community -Please note that this project is released under the Contributor Covenant. By participating in this project you agree to abide by its terms. Our intention is to signal a safe open-source community by welcoming all people to contribute, and pledging in return to value them as whole human beings and to foster an atmosphere of kindness, cooperation, and understanding. +The easiest way to communicate is via [GitHub issues](https://github.com/shabados/presenter/issues). Please search for similar issues regarding your concerns before opening a new issue. -> We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. -> -> We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. -> -> [The Contributor Covenant][contributor-covenant-url] +Get organization updates for Shabad OS by following us on [Instagram](https://www.instagram.com/shabad_os/) and [Twitter](https://twitter.com/shabad_os/). We also invite you to join us on our public chat server hosted on [Slack](https://chat.shabados.com/). -## License +Our intention is to signal a safe open-source community. Please help us foster an atmosphere of kindness, cooperation, and understanding. By participating, you agree to abide by the [Contributor Covenant](https://www.contributor-covenant.org/version/2/0/code_of_conduct/). -This project is under v3 of the [GPL](LICENSE.md). It is similar to the Golden Rule: do unto others as you would have them do unto you. In exchange for benefitting from the work completed in this repo, others must share their derivative work under v3 of the [GPL](LICENSE.md). +If you have a concern that doesn't warrant opening a GitHub issue, please reach out to us: -> This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. -> -> This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. -> -> You should have received a copy of the GNU General Public License along with this program. If not, see . +- Harjot Singh, Maintainer: [@harjot1singh](https://github.com/harjot1singh) +- Bhajneet S.K.: [@bhajneet](https://github.com/bhajneet) -[release-image]: https://img.shields.io/circleci/build/github/shabados/presenter/master.svg?label=release -[release-url]: https://app.circleci.com/pipelines/github/shabados/presenter?branch=master -[next-image]: https://img.shields.io/circleci/build/github/shabados/presenter/dev.svg?label=next%20release -[next-url]: https://app.circleci.com/pipelines/github/shabados/presenter?branch=dev -[website-url]: https://shabados.com -[instagram-image]: https://img.shields.io/badge/Instagram-%40shabad__os-C13584.svg?logo=instagram&logoColor=white -[instagram-url]: https://www.instagram.com/shabad_os/ -[twitter-image]: https://img.shields.io/badge/Twitter-%40shabad__os-1DA1F2.svg?logo=twitter&logoColor=white -[twitter-url]: https://www.twitter.com/shabad_os/ -[chat-image]: https://img.shields.io/badge/Chat-Public%20Slack%20Channels-1264a3.svg?logo=slack -[chat-url]: https://chat.shabados.com -[new-issue-url]: https://github.com/shabados/presenter/issues/new -[contributor-url]: https://github.com/shabados/presenter/graphs/contributors -[upvote-tracker-url]: https://github.com/shabados/presenter/issues?q=is%3Aopen+is%3Aissue+label%3A%22Type%3A+Feature%2FEnhancement%22+sort%3Areactions-%2B1-desc -[contributor-covenant-url]: https://www.contributor-covenant.org/version/2/0/code_of_conduct/ +"Thank you!" to [all the volunteers](https://github.com/shabados/presenter/graphs/contributors) who've contributed to Presenter.