From e81287b37685f851f94f16ffa87a2e0dcdcf383f Mon Sep 17 00:00:00 2001 From: Ankit Kumar <109648585+ankitkumar748846@users.noreply.github.com> Date: Tue, 5 Mar 2024 17:05:08 +0530 Subject: [PATCH] docs: update documentation --- CONTRIBUTING.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 44 ++++++------------------ SETUP.md | 77 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 179 insertions(+), 33 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 SETUP.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..53de6d8 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,91 @@ +# Contributing to OneBusAway Developer + +- All discussions about this project must be respectful and harassment-free. +- Remember that communication is the lifeblood of any Open Source project. We are all working on this together, and we are all benefiting from this software. +- It's very easy to misunderstand one another in asynchronous, text-based conversations. When in doubt, assume everyone has the best intentions. +- If you feel anyone has violated our Code of Conduct, you should anonymously contact the team with our abuse report form via [Slack](https://onebusaway.slack.com/ssb/redirect), necessary action will be taken by the team. + +## Issue label + +Please note: If you wanted to work on an issue, let us know by leaving a comment on the issue. If someone is already assigned or working on the issue, do not try to start working without asking in a thread. Also let us know later if you are no longer working on it. + + +- [good first issue](https://github.com/OneBusAway/onebusaway-docs/labels/good%20first%20issue) labeled issues are meant for newer developers. +- [bugs](https://github.com/OneBusAway/onebusaway-docs/labels/bug) labeled issues are meant to have errors in existing code base. +- [documentation](https://github.com/OneBusAway/onebusaway-docs/labels/documentation) labeled issues are meant to have typo errors in documentation. +- `difficulty: easy` issues are usually confined to isolated areas of existing code. +- `difficulty: medium` issues sometimes entail new features and might affect a significant area of the codebase, but aren't overly complex. +- `difficulty: hard` issues are typically far-reaching, and might need architecture decisions during implementation. This label might also denote highly complex issues. +- `duplicate` labeled issues are meant to be already existing issue in the repository. +- `priority: less` labeled issues are meant to have priority comparatavily lesser than other issues. +- `priority: medium` labeled issues are meant to have priority comparatively intermediate than other issues. +- `priority: high` labeled issues are meant to have the highest priority and need to fix as soon as possible. +- `help wanted` labeled issues signify that the contributor requires help with something specific in the issue and your help is very much appreciated. + +## Creating an issue. + +- Check if the issue you are going to propose is not duplicate of another issue. +- Open a new issue according to type i.e., if issue is a bug open a new issue by clicking on `Get Started` in the scope of `Bug Report`. +- Give a precise and meaningful name of the issue. +- Describe your issue as good as possible that may ease the process of issue-reviewing by a community member. + +## How to contribute + +1. Fork the project and clone it to your local machine. Follow the [setup](SETUP.md) guideline. +2. Always take a pull from the remote repository to your master branch to keep it at par with the main project(updated repository). + + git pull upstream master + +3. Create a branch. For example, if you are going to work on issue number #22 (which is, say, a new feature for ‘forgot password’ management): + + git checkout -b forgot-password#22 + + This both creates and checks out that branch in one command. + The feature name should provide a (short) description of the issue. + +4. Update the README.md with details of changes to the interface, this includes new environment variables, exposed ports, useful file locations and container parameters. +5. Commit your changes and push it to your fork of the repository. +6. Create Pull Request (PR). Make sure to comment the issue that your PR is supposed to solve. + +## Create a pull request + +- Try to keep the pull requests small. A pull request should try its very best to address only a single concern. +- For work in progress pull requests, please use the Draft PR feature. +- Make sure all tests pass and add additional tests for the code you submit. +- Document your reasoning behind the changes. Explain why you wrote the code in the way you did. The code should explain what it does. +- If there's an existing issue, reference to it by adding something like `References/Closes/Fixes/Resolves #123`, where 123 is the issue number. +- Please fill out the PR Template when making a PR. + +> Please note: maintainers may close your PR if it has gone stale or if we don't plan to merge the code. + +## Pull request reviews + +- Requested changes must be resolved (with code or discussion) before merging. +- If you make changes to a PR, be sure to re-request a review. +- Don't repeadetely tag someone(may be it is not the right time to review your PR), be patient. +- Do not 'resolve conversation' unnecessary raised by a community member or any workflow tools(codeclimate or hound) as they may have some purpose, try to resolve the request changes and if any help wanted tag a community member to give views about that. + +#### PR Labels + +- `under-review` labeled PRs are under review by core team. +- `waiting for contributor` labeled PRs are meant to waiting for contributor to respond. +- `waiting for design` labeled PRs are meant to waiting for review from UI/UX core team. +- `no activity` labeled PRs are meant to have no activity in the PR from since a while. +- `blocked` labeled PRs are meant not to go ahead for review. +- `do not merge` labeled PRs are meant not to merge the PR right now(may be later). + +## Community +See the [README](README.md) for more information on communication channels. + +### Code Contributors + +This project exists because of all the people who have [contributed](CONTRIBUTING.md). + + + + + + +## The bottom line + +We are all humans trying to work together to improve the community. Let's always be kind and appreciate the importance of making compromises. ❤️ diff --git a/README.md b/README.md index b5f9401..2faad62 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,21 @@ -# OneBusAway Developer Documentation - +# OneBusAway Developer +The OneBusAway logo

Welcome to the GitHub project that powers the official [OneBusAway Developer Documentation](http://developer.onebusaway.org). -# Improve the Documentation - -Want to help improve the documentation? Thank you! You can easily improve the official OneBusAway documentation by modifying the Markdown files that comprise it. We welcome any size of contribution, ranging from typos and corrected links, to brand-new tutorials. - -# Develop New Features/Fix Bugs - -## Prerequisites +## Community +We would love to hear from you! We communicate on Slack: -* [Ruby](https://www.ruby-lang.org/en/downloads/) >= 2.7 -* [Node](https://nodejs.org) >= 12 -* [Yarn](https://yarnpkg.com) +[![Slack](https://img.shields.io/badge/chat-on_slack-purple.svg?style=for-the-badge&logo=slack)](https://onebusaway.slack.com/ssb/redirect) -## Install -```sh -git clone https://github.com/OneBusAway/onebusaway-docs.git -cd onebusaway-docs -bundle install && yarn install -``` - -## Development - -To start your site in development mode, run `bin/bridgetown start` and navigate to [localhost:4000](https://localhost:4000/)! - -### Commands +# Improve the Documentation +Want to help improve the documentation? Thank you! You can easily improve the official OneBusAway documentation by modifying the Markdown files that comprise it. We welcome any size of contribution, ranging from typos and corrected links, to brand-new tutorials. -```sh -# running locally -bin/bridgetown start +# Setup +See [`SETUP.md`](SETUP.md) for more information on setting up OneBusAway. -# load the site up within a Ruby console (IRB) -bin/bridgetown console -``` +## Contributing +See [`CONTRIBUTING.md`](CONTRIBUTING.md) for more information on contributing to OneBusAway. -> Learn more: [Bridgetown CLI Documentation](https://www.bridgetownrb.com/docs/command-line-usage) -## Deployment -The website built from this project is deployed automatically to a static hosting service on [Render](https://www.render.com). Please contact the maintainers with any questions. diff --git a/SETUP.md b/SETUP.md new file mode 100644 index 0000000..c56dfcf --- /dev/null +++ b/SETUP.md @@ -0,0 +1,77 @@ +# Setting up OneBusAway Developer +[Back to `README.md`](README.md) +## Prerequisites + +* [Ruby](https://www.ruby-lang.org/en/downloads/) >= 2.7 +* [Node](https://nodejs.org) >= 12 +* [Yarn](https://yarnpkg.com) + +## Install + +```sh +git clone https://github.com/OneBusAway/onebusaway-docs.git +cd onebusaway-docs +bundle install && yarn install +``` + +## Setting Up Development Environment + +### For Windows Users (via Windows Subsystem for Linux - WSL) + +1. Install the [Windows Subsystem for Linux (WSL)](https://gorails.com/setup/windows/10) if you haven't already. +2. After setting up WSL, navigate to the project directory in your Linux subsystem. +3. Fork the repository by clicking the "Fork" button on the [repository page](https://github.com/OneBusAway/onebusaway-docs). +4. Clone the forked repository: + + ```sh + git clone https://github.com/YourUsername/onebusaway-docs.git + cd onebusaway-docs + ``` + +5. Install dependencies: + + ```sh + bundle install + yarn install + ``` + + If you encounter any errors, you may run: + + ```sh + yarn add glob + ``` +6. If CSS is not working properly, rebuild frontend assets: + + ```sh + bin/bridgetown frontend:build + ``` +### For Linux Users + +1. Fork and clone the repository as described above. +2. Navigate to the project directory. +3. Install dependencies: + + ```sh + bundle install + yarn install + ``` + +## Development + +To start your site in development mode, run `bin/bridgetown start` and navigate to [localhost:4000](https://localhost:4000/)! + +### Commands + +```sh +# running locally +bin/bridgetown start + +# load the site up within a Ruby console (IRB) +bin/bridgetown console +``` +> Learn more: [Bridgetown CLI Documentation](https://www.bridgetownrb.com/docs/command-line-usage) + +## Deployment +The website built from this project is deployed automatically to a static hosting service on [Render](https://www.render.com). Please contact the maintainers with any questions. + +