Skip to content

Commit

Permalink
docs: update readme and contributing with new info (#683)
Browse files Browse the repository at this point in the history
  • Loading branch information
@bhajneet
bhajneet authored May 16, 2023
1 parent 39bd099 commit 98989ba
Show file tree
Hide file tree
Showing 2 changed files with 40 additions and 220 deletions.
142 changes: 21 additions & 121 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -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.

<!-- #### Prerequisites for compile tool chain
Currently, the program uses precompiled binaries. If a need to compile native Node modules arises in the future, the following prerequisites would be needed.
**PROTIP**: The following instructions are **not** required to build, run, package, or distribute Shabad OS Presenter.
- [Python](https://www.python.org/downloads/release/python-2715/), at least version 2.7 (version 3 is not supported).
- Run `npm i` in the root directory.
- `npm start`

**PROTIP**: Windows users will automatically install Python 2.7 when installing `windows-build-tools` npm module (see below)
The above command spins up development servers. It launches a frontend on [port `3000`](https://localhost:3000) and backend on [port `42425`](https://localhost:42425). Any changes to the backend will result in a restart. A manual restart can be triggered by entering `rs` into the terminal.

- A C/C++ compiler tool chain for your platform:
- **Windows**
- **NOTE**: Make sure your profile path only contains ASCII letters, otherwise it can lead to node-gyp usage problems ([nodejs/node-gyp issue #297](https://github.com/nodejs/node-gyp/issues/297))
- **NOTE**: If you have Visual Studio 2019 installed, you may face issues when using the default version of `node-gyp`. You may need to follow the solutions in [nodejs/node-gyp issue #1747](https://github.com/nodejs/node-gyp/issues/1747).
- Start Powershell as Administrator.
- Run `npm install --global windows-build-tools --vs2015`. (Try the `--debug` flag or check [Windows Build Tools](https://github.com/felixrieseberg/windows-build-tools) if you encounter any problems.)
- Restart your computer.
- **macOS**
- [Xcode](https://developer.apple.com/xcode/downloads/) can be used to install Command Line Tools containing `gcc` and the related tool-chain containing `make`.
- Open a terminal and run `xcode-select --install`.
- **Linux**
- `make`, `pkg-config`, GCC or another compile tool-chain
- Building packages has not been tested, so requirements are unknown -->
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 <command>
```

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`.

Expand All @@ -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
<type>(<scope>): <subject>
```

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.
118 changes: 19 additions & 99 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,42 +1,20 @@
<img src="https://raw.githubusercontent.com/shabados/presenter/dev/resources/icon.png" width="128" alt="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
Expand All @@ -46,85 +24,27 @@ See:
- Jump to line _N_ of shabad
- Autoselect line based on context/position

### Screenshots
## Screenshots

<img src="docs/readme-screenshot-presenter.png" width="640">
<img src="docs/readme-screenshot-controller.png" width="640">
<img src="docs/readme-screenshot-settings.png" width="640">

## 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 <https://www.gnu.org/licenses/>.
- 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.

0 comments on commit 98989ba

Please sign in to comment.