Merge branch 'gh-pages' into 312-add-donation-button

Author: kjaymiller

CONTRIBUTING.md

@@ -4,35 +4,83 @@ lang: en
 title: Contributing
 ---
 
-# Contributing to Black Python Devs
+# Contributing at Black Python Devs
 
-First off, thank you for considering contributing to Black Python Devs website. It's people like you that make Black Python Devs such a great community.
+First off, thank you for considering contributing to Black Python Devs website. It's people like you that make Black Python Devs such a great community. Navigate through the following to understand more about contributing here.
+
+- [Before You Get Started](#before-you-get-started)
+- [How to Contribute](#how-to-contribute)
+- [Accessibility](#accessibility)
+- [Translations](#translations)
+
+# Before You Get Started
 
 ## Code of Conduct
 
-Help us keep this project open and inclusive. Please read and follow our [Code of Conduct](https://github.com/BlackPythonDevs/.github/blob/main/CODE_OF_CONDUCT.md).
+Black Python Devs follows the following [Code of Conduct](https://github.com/BlackPythonDevs/.github/blob/main/CODE_OF_CONDUCT.md) . The comfort and safety of Black Python Devs community members are our priority. Please do well to adhere to the Code of Conduct to participate in the Black Python Devs community.
 
-## How Can I Contribute?
+## Issues & Pull Requests
 
-### 1. Create an Issue (and wait to be assigned)
+### Creating an issue
 
-- Click on the Issues tab in the repository.
+Before **creating** an issue i.e for `features`/`bugs`/`improvements` please follow these steps:
 
-  ![Issues tab](/assets/images/issues_tab.png)
+1. Search existing issues before creating a new issue (look to see if the issue has already been created).
+1. If it doesn't exist create a new issue giving as much context as possible (please take note and select the correct issue type, for example `bug`, `documentation` or `feature`.
+1. If you wish to work on the issue add this to the issue description.
 
-- Click on the green button with the label **"New issue"** and you should see the image below:
+### Working on an issue
 
-  ![New issue button](/assets/images/new_issue.png)
+Before working on an existing issue please follow these steps:
 
-- Type in the issue title in the title textbox and type in a clear explanation of the issue in the textarea. You can add images, code snippets, etc to explain your issue.
+1. Comment asking for the issue to be assigned to you.
+1. To best position yourself for issues assignment, we recommend that you:
+   1. Confirm that you have read the CONTRIBUTING.md.
+   1. Have a functional development environment (have built and are able to run the project).
+   1. Convey your intended approach to solving the issue.
+   1. Put each of these items in writing in one or more comments.
+1. After the issue is assigned to you, you can start working on it.
+1. In general, **only** start working on this issue (and open a Pull Request) when it has been assigned to you. Doing so will prevent confusion, duplicate work (some of which may go unaccepted given its duplicity), incidental stepping on toes, and the headache involved for maintainers and contributors alike as issue assignments collide and heads bump together.
+1. Reference the issue in your Pull Request (for example `This PR fixes #123`), so that the corresponding issue is automatically closed upon merge of your Pull Request.
+
+> Notes:
+>
+> - Check the `Assignees` box at the top of the page to see if the issue has been assigned to someone else before requesting this be assigned to you. If the issue has a current Assignee, but appears to be inactive, politely inquire with the current Assignee as to whether they are still working on a solution and/or if you might collaborate with them.
+> - Only request to be assigned an issue if you know how to work on it.
+> - If an issue is unclear, ask questions to get more clarity before asking to have the issue assigned to you; avoid asking "what do I do next? how do I fix this?" (see the item above this line)
+> - An issue can be assigned to multiple people, if you all agree to collaborate on the issue (the Pull Request can contain commits from different collaborators)
+> - Any issues that has no activity after 2 weeks will be unassigned and re-assigned to someone else.
+
+## Reviewing Pull Requests
+
+We welcome everyone to review Pull Requests. It is a great way to learn, network, and support each other.
+
+### DOs
+
+- Use inline comments to explain your suggestions
+- Use inline suggestions to propose changes
+- Exercise patience and empathy while offering critiques of the works of others.
+
+### DON'Ts
+
+- Do not repeat feedback, this creates more noise than value (check the existing conversation), use GitHub reactions if you agree/disagree with a comment
+- Do not blindly approve Pull Requests to improve your GitHub contributors graph
+
+## Discord Community
+
+Join the [Discord](https://discord.gg/XUc3tFqCT3) to discuss suggested new features, possible bugs, enhancement in user experience, and any other aspects of the site. The comment section of each issue is our preferred method of communication as it retains conversations history for future contributors wanting to gain insights/updates on the topic in question, you can, however, inquire in the #community-discussion channel in the Black Python Devs Discord workspace.
 
-- Once you are done, you can preview your issue by selecting the Preview tab. If you are satisfied with the issue presentation, you can click on the green "Submit new issue" button to create ypur issue.
+# Contributing to Black Python Devs Projects
 
-- Now you wait for your issue to be assigned to you by a maintainer. You should get an email notification of the issue being assigned to you or you can view the issue assignment in the issue page. It should look similar to this:
+Please follow these steps and note these guidelines to begin contributing:
 
-  ![Issue assignment](/assets/images/issue_assignment.png)
+1. First step is to set up the local development environment.
+1. Bug fixes are always welcome. Start by reviewing the [list of bugs](https://github.com/BlackPythonDevs/blackpythondevs.github.io/issues).
+1. A good way to easily start contributing is to pick and work on a [good first issue](https://github.com/BlackPythonDevs/blackpythondevs.github.io/labels/good%20first%20issue). We try to make these issues as clear as possible and provide basic info on how the code should be changed, and if something is unclear feel free to ask for more information on the issue.
 
-### 2. Fork the Code
+# How to Contribute
+
+## Fork the repository
 
 - To fork the repository so you have a copy of the codebase, you will click on the **"Fork"** button from the repository main page
 
@@ -42,7 +90,25 @@ Help us keep this project open and inclusive. Please read and follow our [Code o
 
   ![Create new fork page](/assets/images/create_new_fork_page.png)
 
-### 3. Make the changes
+## Createing an issue
+
+- Click on the issues tab in the repository.
+
+  ![issues tab](/assets/images/issues_tab.png)
+
+- Click on the green button with the label **"New issue"** and you should see the image below:
+
+  ![New issue button](/assets/images/new_issue.png)
+
+- Type in the issue title in the title textbox and type in a clear explanation of the issue in the textarea. You can add images, code snippets, etc to explain your issue.
+
+- Once you are done, you can preview your issue by selecting the Preview tab. If you are satisfied with the issue presentation, you can click on the green "Submit new issue" button to create your issue.
+
+- And that's it! If you cose to comment requesting the issue to be assigned to you, wait for a maintainer to do so. You should get an email notification of the issue being assigned to you or you can view the issue assignment in the issue page. It should look similar to this:
+
+  ![issue assignment](/assets/images/issue_assignment.png)
+
+## Working on an issue
 
 - The easiest way to make changes and and test them is by using [![GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/BlackPythonDevs/blackpythondevs.github.io)
 
@@ -52,7 +118,7 @@ Help us keep this project open and inclusive. Please read and follow our [Code o
 
 - The web version of VSCode should open in a new tab in your browser:
 
-  ![BlackPythonDevs Codespace](/assets/images/blackpythondevs_codespace.png)
+  ![Black Python Devs Codespace](/assets/images/BlackPythonDevs_codespace.png)
 
 - Now that you have the code editor set up, you need to install the dependencies. To do this, you have to open the code editor's terminal and run the command `bundle install`.
 
@@ -78,41 +144,39 @@ Help us keep this project open and inclusive. Please read and follow our [Code o
 
 - Test your changes (create new tests as needed)
 
-- Submit a Pull Request
-
-🥳
+- Once you’ve committed and pushed all of your changes to GitHub, go to the page for your fork on GitHub, select your development branch, and click the pull request button. Please ensure that you compare your feature branch to the desired branch of the repo you are supposed to make a PR to. If you need to make any adjustments to your pull request, just push the updates to GitHub. Your pull request will automatically track the changes in your development branch and update it. 🥳
 
-## Accessibility
+# Accessibility
 
 Accessibility (A11y) using the **FastPass** tests for A11y and the [Accessibility Insights for Web
 ][1] browser extension.
 
-### 1: Reproduce the Tests
+## 1: Reproduce the Tests
 
 First, reproduce the **FastPass** tests for A11y using the [Accessibility Insights for Web
 ][1] browser extension. This extension is designed to help you identify and fix accessibility issues on your website.
 
 ![image](https://github.com/BlackPythonDevs/blackpythondevs.github.io/assets/44526468/222e6653-c963-4518-a297-262d656216a7)
 
-### 2: Capture the Issues
+## 2: Capture the issues
 
-If the Accessibility Insights for Web extension identifies any issues, capture a screenshot of the issues on the [BPDevs](https://blackpythondevs.github.io/) website. You can do this by pressing <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>S</kbd> on your keyboard.
+If the Accessibility Insights for Web extension identifies any issues, capture a screenshot of the issues on the [BPDevs](https://BlackPythonDevs.github.io/) website. You can do this by pressing <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>S</kbd> on your keyboard.
 
-### 3: Make the Necessary Changes
+## 3: Make the Necessary Changes
 
 Next, make the necessary changes to fix the identified issues. This might involve modifying the CSS of the website.
 
-### 4: Test the Changes
+## 4: Test the Changes
 
 After making the changes, run the **FastPass** test again and capture a screenshot showing no accessibility issues. This will serve as proof that the issues have been successfully resolved.
 
 ![image](https://github.com/BlackPythonDevs/blackpythondevs.github.io/assets/44526468/9a284f43-3cde-4370-9eab-1d302ed65e9e)
 
-### 5: Check and Pass Other Tests
+## 5: Check and Pass Other Tests
 
 Finally, check and pass other tests, such as the rules with `pre-commit`. This ensures that your changes are in line with the existing codebase and do not introduce any new issues.
 
-## Translations
+# Translations
 
 We welcome translations for the Black Python Devs website in all languages! Here's how you can contribute: