diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 70886906d..e9afa4833 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,6 +12,8 @@ If you have questions or would like to communicate with the team, please [join u # **Contents** +- [First steps as a contributor](#first-steps) +- [Learning the tech stack](#learning-the-tech) - [Development environment](#dev-env) - [Issues and projects](#issues-projects) - [Bug reports](#bug-reports) @@ -20,16 +22,97 @@ If you have questions or would like to communicate with the team, please [join u - [Data edits](#data-edits) - [Documentation](#documentation) + + +## First steps as a contributor [`⇧`](#contents) + +Thank you for your interest in contributing to Scribe-Data! We look forward to welcoming you to the community and working with you to build an tools for language learners to communicate effectively :) The following are some suggested steps for people interested in joining our community: + +- Please join the [public Matrix chat](https://matrix.to/#/#scribe_community:matrix.org) to connect with the community + - [Matrix](https://matrix.org/) is a network for secure, decentralized communication + - Scribe would suggest that you use the [Element](https://element.io/) client + - The [General](https://matrix.to/#/!yQJjLmluvlkWttNhKo:matrix.org?via=matrix.org) and [Data](https://matrix.to/#/#ScribeData:matrix.org) channels would be great places to start! + - Feel free to introduce yourself and tell us what your interests are if you're comfortable :) +- Read through this contributing guide for all the information you need to contribute +- Look into issues marked [`good first issue`](https://github.com/scribe-org/Scribe-Data/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) and the [Projects board](https://github.com/orgs/scribe-org/projects/1) to get a better understanding of what you can work on +- Check out our [public designs on Figma](https://www.figma.com/file/c8945w2iyoPYVhsqW7vRn6/scribe_public_designs?type=design&node-id=405-464&mode=design&t=E3ccS9Z8MDVSizQ4-0) to understand Scribes's goals and direction +- Consider joining our [bi-weekly developer sync](https://etherpad.wikimedia.org/p/scribe-dev-sync)! + +> [!NOTE] +> Those new to Python or wanting to work on their Python skills are more than welcome to contribute! The team would be happy to help you on your development journey :) + + + +## Learning the tech stack [`⇧`](#contents) + +Scribe is very open to contributions from people in the early stages of their coding journey! The following is a select list of documentation pages to help you understand the technologies we use. + +
Docs for those new to programming +

+ +- [Mozilla Developer Network Learning Area](https://developer.mozilla.org/en-US/docs/Learn) + - Doing MDN sections for HTML, CSS and JavaScript is the best ways to get into web development! + +

+
+ +
Python learning docs +

+ +- [Python getting started guide](https://docs.python.org/3/tutorial/introduction.html) +- [Python getting started resources](https://www.python.org/about/gettingstarted/) + +

+
+ # Development environment [`⇧`](#contents) -The development environment for Scribe-Data can be installed via the following command with [Anaconda](https://www.anaconda.com/) in the root directory of your local copy of the project: +The development environment for Scribe-Data can be installed via the following steps: + +1. [Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the [Scribe-Data repo](https://github.com/scribe-org/Scribe-Data), clone your fork, and configure the remotes: + +> [!NOTE] +> +>
Consider using SSH +> +>

+> +> Alternatively to using HTTPS as in the instructions below, consider SSH to interact with GitHub from the terminal. SSH allows you to connect without a user-pass authentication flow. +> +> To run git commands with SSH, remember then to substitute the HTTPS URL, `https://github.com/...`, with the SSH one, `git@github.com:...`. +> +> - e.g. Cloning now becomes `git clone git@github.com:/activist.git` +> +> GitHub also has their documentation on how to [Generate new SSH key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). 🔑 +> +>

+>
+ +```bash +# Clone your fork of the repo into the current directory. +git clone https://github.com//Scribe-Data.git +# Navigate to the newly cloned directory. +cd Scribe-Data +# Assign the original repo to a remote called "upstream". +git remote add upstream https://github.com/scribe-org/Scibe-Data.git +``` + +Now, if you run `git remote -v` you should see two remote repositories named: + +- `origin` (forked repository) +- `upstream` (Scribe-Data repository) + +2. Use [Anaconda](https://www.anaconda.com/) to create the local development environment within your Scribe-Data directory: ```bash conda env create -f environment.yml ``` +> [!NOTE] +> Feel free to contact the team in the [General room on Matrix](https://matrix.to/#/!yQJjLmluvlkWttNhKo:matrix.org?via=matrix.org) if you're having problems getting your environment setup! + # Issues and projects [`⇧`](#contents) @@ -63,63 +146,60 @@ Guidelines for bug reports: - What actually happens - Notes (why this might be happening, things tried that didn't work, etc) +To make the above steps easier, the Scribe team asks that contributors report bugs using the [bug report template](https://github.com/scribe-org/Scribe-Data/issues/new?assignees=&labels=feature&template=bug_report.yml), with these issues further being marked with the [`bug`](https://github.com/scribe-org/Scribe-Data/issues?q=is%3Aopen+is%3Aissue+label%3Abug) label. + Again, thank you for your time in reporting issues! # Feature requests [`⇧`](#contents) -Feature requests are more than welcome! Please take a moment to find out whether your idea fits with the scope and aims of the project. When making a suggestion, provide as much detail and context as possible, and further make clear the degree to which you would like to contribute in its development. +Feature requests are more than welcome! Please take a moment to find out whether your idea fits with the scope and aims of the project. When making a suggestion, provide as much detail and context as possible, and further make clear the degree to which you would like to contribute in its development. Feature requests are marked with the [`feature`](https://github.com/scribe-org/Scribe-Data/issues?q=is%3Aopen+is%3Aissue+label%3Afeature) label, and can be made using the [feature request](https://github.com/scribe-org/Scribe-Data/issues/new?assignees=&labels=feature&template=feature_request.yml) template. # Pull requests [`⇧`](#contents) -Good pull requests - patches, improvements and new features - are a fantastic help. They should remain focused in scope and avoid containing unrelated commits. Note that all contributions to this project will be made under [the specified license](https://github.com/scribe-org/Scribe-Data/blob/main/LICENSE.txt) and should follow the coding indentation and style standards (contact us if unsure). +Good pull requests - patches, improvements and new features - are the foundation of our community making Scribe-Data. They should remain focused in scope and avoid containing unrelated commits. Note that all contributions to this project will be made under [the specified license](https://github.com/scribe-org/Scribe-Data/blob/main/LICENSE.txt) and should follow the coding indentation and style standards (contact us if unsure). **Please ask first** before embarking on any significant pull request (implementing features, refactoring code, etc), otherwise you risk spending a lot of time working on something that the developers might not want to merge into the project. With that being said, major additions are very appreciated! When making a contribution, adhering to the [GitHub flow](https://guides.github.com/introduction/flow/index.html) process is the best way to get your work merged: -1. [Fork](http://help.github.com/fork-a-repo/) the repo, clone your fork, and configure the remotes: - - ```bash - # Clone your fork of the repo into the current directory - git clone https://github.com// - # Navigate to the newly cloned directory - cd - # Assign the original repo to a remote called "upstream" - git remote add upstream https://github.com// - ``` - -2. If you cloned a while ago, get the latest changes from upstream: +1. If you cloned a while ago, get the latest changes from upstream: ```bash git checkout git pull upstream ``` -3. Create a new topic branch (off the main project development branch) to contain your feature, change, or fix: +2. Create a new topic branch (off the main project development branch) to contain your feature, change, or fix: ```bash git checkout -b ``` -4. Commit your changes in logical chunks, and please try to adhere to [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). Use Git's [interactive rebase](https://docs.github.com/en/github/getting-started-with-github/about-git-rebase) feature to tidy up your commits before making them public. +3. Commit your changes in logical chunks, and please try to adhere to [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). + +> [!NOTE] +> The following are tools and methods to help you write good commit messages ✨ +> +> - [commitlint](https://commitlint.io/) helps write [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) +> - Git's [interactive rebase](https://docs.github.com/en/github/getting-started-with-github/about-git-rebase) cleans up commits -5. Locally merge (or rebase) the upstream development branch into your topic branch: +4. Locally merge (or rebase) the upstream development branch into your topic branch: ```bash git pull --rebase upstream ``` -6. Push your topic branch up to your fork: +5. Push your topic branch up to your fork: ```bash git push origin ``` -7. [Open a Pull Request](https://help.github.com/articles/using-pull-requests/) with a clear title and description. +6. [Open a Pull Request](https://help.github.com/articles/using-pull-requests/) with a clear title and description. Thank you in advance for your contributions! diff --git a/README.md b/README.md index 290c8f588..e9a89f159 100644 --- a/README.md +++ b/README.md @@ -26,22 +26,11 @@ Scribe applications are available on [iOS](https://github.com/scribe-org/Scribe- # **Contents** -- [Setup](#setup) - [Process](#process) - [Contributing](#contributing) - [Supported Languages](#supported-languages) - [Featured By](#featured-by) - - -# Setup [`⇧`](#contents) - -The development environment for Scribe-Data can be installed via the following command with [Anaconda](https://www.anaconda.com/) in the root directory of your local copy of the project: - -```bash -conda env create -f environment.yml -``` - # Process [`⇧`](#contents) @@ -65,7 +54,7 @@ Please see the [contribution guidelines](https://github.com/scribe-org/Scribe-Da > [!NOTE]\ > Just because an issue is assigned on GitHub doesn't mean that the team isn't interested in your contribution! Feel free to write [in the issues](https://github.com/scribe-org/Scribe-Data/issues) and we can potentially reassign it to you. -Those interested can further check the [`-next release-`](https://github.com/scribe-org/Scribe-Data/labels/-next%20release-) and [`-priority-`](https://github.com/scribe-org/Scribe-Data/labels/-priority-) labels in the [issues](https://github.com/scribe-org/Scribe-iOS/issues) for those that are most important, as well as those marked [`good first issue`](https://github.com/scribe-org/Scribe-Data/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) that are tailored for first time contributors. +Those interested can further check the [`-next release-`](https://github.com/scribe-org/Scribe-Data/labels/-next%20release-) and [`-priority-`](https://github.com/scribe-org/Scribe-Data/labels/-priority-) labels in the [issues](https://github.com/scribe-org/Scribe-Data/issues) for those that are most important, as well as those marked [`good first issue`](https://github.com/scribe-org/Scribe-Data/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) that are tailored for first time contributors. After your first few pull requests organization members would be happy to discuss granting you further rights as a contributor, with a maintainer role then being possible after continued interest in the project. Scribe seeks to be an inclusive and supportive organization. We'd love to have you on the team! @@ -80,6 +69,52 @@ After your first few pull requests organization members would be happy to discus The Scribe road map can be followed in the organization's [project board](https://github.com/orgs/scribe-org/projects/1) where we list the most important issues along with their priority, status and an indication of which sub projects they're included in (if applicable). +### Development environment [`⇧`](#contents) + +The development environment for Scribe-Data can be installed via the following steps: + +1. [Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the [Scribe-Data repo](https://github.com/scribe-org/Scribe-Data), clone your fork, and configure the remotes: + +> [!NOTE] +> +>
Consider using SSH +> +>

+> +> Alternatively to using HTTPS as in the instructions below, consider SSH to interact with GitHub from the terminal. SSH allows you to connect without a user-pass authentication flow. +> +> To run git commands with SSH, remember then to substitute the HTTPS URL, `https://github.com/...`, with the SSH one, `git@github.com:...`. +> +> - e.g. Cloning now becomes `git clone git@github.com:/activist.git` +> +> GitHub also has their documentation on how to [Generate new SSH key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). 🔑 +> +>

+>
+ +```bash +# Clone your fork of the repo into the current directory. +git clone https://github.com//Scribe-Data.git +# Navigate to the newly cloned directory. +cd Scribe-Data +# Assign the original repo to a remote called "upstream". +git remote add upstream https://github.com/scribe-org/Scibe-Data.git +``` + +Now, if you run `git remote -v` you should see two remote repositories named: + +- `origin` (forked repository) +- `upstream` (Scribe-Data repository) + +2. Use [Anaconda](https://www.anaconda.com/) to create the local development environment within your Scribe-Data directory: + +```bash +conda env create -f environment.yml +``` + +> [!NOTE] +> Feel free to contact the team in the [General room on Matrix](https://matrix.to/#/!yQJjLmluvlkWttNhKo:matrix.org?via=matrix.org) if you're having problems getting your environment setup! + ### Data Edits [`⇧`](#contents) > [!NOTE]\