Merge pull request #699 from camcaswell/contrib-streamline

Contrib walk-through and improving guides

Author: mbaruh

pydis_site/apps/content/resources/guides/pydis-guides/contributing.md

@@ -4,7 +4,7 @@ description: A guide to contributing to our open source projects.
 icon: fab fa-github
 ---
 
-Our projects on Python Discord are open source and [available on Github](https://github.com/python-discord).  If you would like to contribute, consider one of the following projects:
+Our projects on Python Discord are open source and [available on GitHub](https://github.com/python-discord).  If you would like to contribute, consider one of the following projects:
 
 <!-- Project cards -->
 <div class="columns is-multiline is-centered is-3 is-variable">
@@ -19,11 +19,7 @@ Our projects on Python Discord are open source and [available on Github](https:/
       </div>
       <div class="card-content">
         <div class="content">
-          Our community-driven Discord bot.
-        </div>
-        <div class="tags has-addons">
-          <span class="tag is-dark">Difficulty</span>
-          <span class="tag is-primary">Beginner</span>
+          Sir Lancebot has a collection of self-contained, for-fun features. If you're new to Discord bots or contributing, this is a great place to start!
         </div>
       </div>
       <div class="card-footer">
@@ -46,11 +42,7 @@ Our projects on Python Discord are open source and [available on Github](https:/
       </div>
       <div class="card-content">
         <div class="content">
-          The community and moderation Discord bot.
-        </div>
-        <div class="tags has-addons">
-          <span class="tag is-dark">Difficulty</span>
-          <span class="tag is-warning">Intermediate</span>
+          Called @Python on the server, this bot handles moderation tools, help channels, and other critical features for our community.
         </div>
       </div>
       <div class="card-footer">
@@ -73,11 +65,7 @@ Our projects on Python Discord are open source and [available on Github](https:/
       </div>
       <div class="card-content">
         <div class="content">
-          The website, subdomains and API.
-        </div>
-        <div class="tags has-addons">
-          <span class="tag is-dark">Difficulty</span>
-          <span class="tag is-danger">Advanced</span>
+          This website itself! This project is built with Django and includes our API, which is used by various services such as @Python.
         </div>
       </div>
       <div class="card-footer">
@@ -91,26 +79,64 @@ Our projects on Python Discord are open source and [available on Github](https:/
   </div>
 </div>
 
-If you don't understand anything or need clarification, feel free to ask any staff member with the  **@PyDis Core Developers** role in the server. We're always happy to help!
+# How do I start contributing?
+Unsure of what contributing to open source projects involves? Have questions about how to use GitHub? Just need to know about our contribution etiquette? Completing these steps will have you ready to make your first contribution no matter your starting point.
+
+Feel free to skip any steps you're already familiar with, but please make sure not to miss the [Contributing Guidelines](#5-read-our-contributing-guidelines).
+
+If you are here looking for the answer to a specific question, check out the sub-articles in the top right of the page to see a list of our guides.
+
+**Note:** We use Git to keep track of changes to the files in our projects. Git allows you to make changes to your local code and then distribute those changes to the other people working on the project. You'll use Git in a couple steps of the contributing process. You can refer to this [**guide on using Git**](./working-with-git/).
+{: .notification }
+
+### 1. Fork and clone the repo
+GitHub is a website based on Git that stores project files in the cloud. We use GitHub as a central place for sending changes, reviewing others' changes, and communicating with each other. You'll need to create a copy under your own GitHub account, a.k.a. "fork" it. You'll make your changes to this copy, which can then later be merged into the Python Discord repository.
+
+*Note: Members of the Python Discord staff can create feature branches directly on the repo without forking it.*
+
+Check out our [**guide on forking a GitHub repo**](./forking-repository/).
+
+Now that you have your own fork you need to be able to make changes to the code. You can clone the repo to your local machine, commit changes to it there, then push those changes to GitHub.
+
+Check out our [**guide on cloning a GitHub repo**](./cloning-repository/).
+
+### 2. Set up the project
+You have the source code on your local computer, now how do you actually run it? We have detailed guides on setting up the environment for each of our main projects:
+
+* [**Sir Lancebot**](./sir-lancebot/)
+
+* [**Python Bot**](./bot/)
+
+* [**Site**](./site/)
+
+### 3. Read our Contributing Guidelines
+We have a few short rules that all contributors must follow. Make sure you read and follow them while working on our projects.
+
+[**Contributing Guidelines**](./contributing-guidelines/).
+
+As mentioned in the Contributing Guidelines, we have a simple style guide for our projects based on PEP 8. Give it a read to keep your code consistent with the rest of the codebase.
+
+[**Style Guide**](./style-guide/)
+
+### 4. Create an issue
+The first step to any new contribution is an issue describing a problem with the current codebase or proposing a new feature. All the open issues are viewable on the GitHub repositories, for instance here is the [issues page for Sir Lancebot](https://github.com/python-discord/sir-lancebot/issues). If you have something that you want to implement open a new issue to present your idea. Otherwise you can browse the unassigned issues and ask to be assigned to one that you're interested in, either in the comments on the issue or in the [`#dev-contrib`](https://discord.gg/2h3qBv8Xaa) channel on Discord.
+
+[**How to write a good issue**](./issues/)
 
-### Useful Resources
+Don't move forward until your issue is approved by a Core Developer. Issues are not guaranteed to be approved so your work may be wasted.
+{: .notification .is-warning }
 
-[Guidelines](./contributing-guidelines/) - General guidelines you should follow when contributing to our projects.<br>
-[Style Guide](./style-guide/) - Information regarding the code styles you should follow when working on our projects.<br>
-[Review Guide](../code-reviews-primer/) - A guide to get you started on doing code reviews.
+### 5. Make changes
+Now it is time to make the changes to fulfill your approved issue. You should create a new Git branch for your feature; that way you can keep your main branch up to date with ours and even work on multiple features at once in separate branches.
 
-## Contributors Community
-We are very happy to have many members in our community that contribute to [our open source projects](https://github.com/python-discord/).
-Whether it's writing code, reviewing pull requests, or contributing graphics for our events, it’s great to see so many people being motivated to help out.
-As a token of our appreciation, those who have made significant contributions to our projects will receive a special **@Contributors** role on our server that makes them stand out from other members.
-That way, they can also serve as guides to others who are looking to start contributing to our open source projects or open source in general.
+This is a good time to review [how to write good commit messages](./contributing-guidelines/commit-messages) if you haven't already.
 
-#### Guidelines for the @Contributors Role
+### 6. Open a pull request
+After your issue has been approved and you've written your code and tested it, it's time to open a pull request. Pull requests are a feature in GitHub; you can think of them as asking the project maintainers to accept your changes. This gives other contributors a chance to review your code and make any needed changes before it's merged into the main branch of the project.
 
-One question we get a lot is what the requirements for the **@Contributors** role are.
-As it’s difficult to precisely quantify contributions, we’ve come up with the following guidelines for the role:
+Check out our [**Pull Request Guide**](./pull-requests/) for help with opening a pull request and going through the review process.
 
-- The member has made several significant contributions to our projects.
-- The member has a positive influence in our contributors subcommunity.
+Check out our [**Code Review Guide**](../code-reviews-primer/) to learn how to be a star reviewer. Reviewing PRs is a vital part of open source development, and we always need more reviewers!
 
-The role will be assigned at the discretion of the Admin Team in consultation with the Core Developers Team.
+### That's it!
+Thank you for contributing to our community projects. If there's anything you don't understand or you just want to discuss with other contributors, come visit the [`#dev-contrib`](https://discord.gg/2h3qBv8Xaa) channel to ask questions. Keep an eye out for staff members with the **@PyDis Core Developers** role in the server; we're always happy to help!

pydis_site/apps/content/resources/guides/pydis-guides/contributing/bot.md

@@ -5,34 +5,9 @@ icon: fab fa-github
 toc: 3
 ---
 The purpose of this guide is to get you a running local version of [the Python bot](https://github.com/python-discord/bot).
-This page will focus on the quickest steps one can take, with mentions of alternatives afterwards.
-
-### Clone The Repository
-First things first, to run the bot's code and make changes to it, you need a local version of it (on your computer).
-
-<div class="card">
-    <button type="button" class="card-header collapsible">
-        <span class="card-header-title subtitle is-6 my-2 ml-2">Getting started with Git and GitHub</span>
-        <span class="card-header-icon">
-            <i class="fas fa-fw fa-angle-down title is-5" aria-hidden="true"></i>
-        </span>
-    </button>
-    <div class="collapsible-content collapsed">
-        <div class="card-content">
-              <p>If you don't have Git on your computer already, <a href="https://git-scm.com/downloads">install it</a>. You can additionally install a Git GUI such as <a href="https://www.gitkraken.com/download">GitKraken</a>, or the <a href="https://cli.github.com/manual/installation">GitHub CLI</a>.</p>
-              <p>To learn more about Git, you can look into <a href="../working-with-git">our guides</a>, as well as <a href="https://education.github.com/git-cheat-sheet-education.pdf">this cheatsheet</a>, <a href="https://learngitbranching.js.org">Learn Git Branching</a>, and otherwise any guide you can find on the internet. Once you got the basic idea though, the best way to learn Git is to use it.</p>
-              <p>Creating a copy of a repository under your own account is called a <em>fork</em>. This is where all your changes and commits will be pushed to, and from where your pull requests will originate from.</p>
-              <p><strong><a href="../forking-repository">Learn about forking a project</a></strong>.</p>
-        </div>
-    </div>
-</div>
-<br>
-
-You will need to create a fork of [the project](https://github.com/python-discord/bot), and clone the fork.
-Once this is done, you will have completed the first step towards having a running version of the bot.
+You should have already forked the repository and cloned it to your local machine. If not, check out our [detailed walkthrough](../#1-fork-and-clone-the-repo).
 
-#### Working on the Repository Directly
-If you are a member of the organisation (a member of [this list](https://github.com/orgs/python-discord/people), or in our particular case, server staff), you can clone the project repository without creating a fork, and work on a feature branch instead.
+This page will focus on the quickest steps one can take, with mentions of alternatives afterwards.
 
 ---
 
@@ -570,10 +545,7 @@ Now that you have everything setup, it is finally time to make changes to the bo
 
 #### Working with Git
 
-If you have not yet [read the contributing guidelines](../contributing-guidelines), now is a good time.
-Contributions that do not adhere to the guidelines may be rejected.
-
-Notably, version control of our projects is done using Git and Github.
+Version control of our projects is done using Git and Github.
 It can be intimidating at first, so feel free to ask for any help in the server.
 
 [**Click here to see the basic Git workflow when contributing to one of our projects.**](../working-with-git/)
@@ -664,4 +636,11 @@ The following is a list of all available environment variables used by the bot:
 | `METABASE_USERNAME` | When you wish to interact with Metabase | The username for a Metabase admin account.
 | `METABASE_PASSWORD` | When you wish to interact with Metabase | The password for a Metabase admin account.
 
+---
+
+# Next steps
+Now that you have everything setup, it is finally time to make changes to the bot! If you have not yet read the [contributing guidelines](../contributing-guidelines.md), now is a good time. Contributions that do not adhere to the guidelines may be rejected.
+
+If you're not sure where to go from here, our [detailed walkthrough](../#2-set-up-the-project) is for you.
+
 Have fun!

pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines.md

@@ -4,22 +4,15 @@ description: Guidelines to adhere to when contributing to our projects.
 ---
 
 Thank you for your interest in our projects!
+This page contains the golden rules to follow when contributing. If you have questions about how to get started contributing, check out our [in-depth walkthrough](../../contributing/).
 
-If you are interested in contributing, **this page contains the golden rules to follow when contributing.**
-Supplemental information [can be found here](./supplemental-information/).
-Do note that failing to comply with our guidelines may lead to a rejection of the contribution.
-
-If you are confused by any of these rules, feel free to ask us in the `#dev-contrib` channel in our [Discord server.](https://discord.gg/python)
-
-# The Golden Rules of Contributing
-
-1. **Lint before you push.** We have simple but strict style rules that are enforced through linting.
-You must always lint your code before committing or pushing.
-[Using tools](./supplemental-information/#linting-and-pre-commit) such as `flake8` and `pre-commit` can make this easier.
-Make sure to follow our [style guide](../style-guide/) when contributing.
+1. **Lint before you push.**
+We have simple but strict style rules that are enforced through linting.
+[Set up a pre-commit hook](../linting/) to lint your code when you commit it.
+Not all of the style rules are enforced by linting, so make sure to read the [style guide](../style-guide/) as well.
 2. **Make great commits.**
 Great commits should be atomic, with a commit message explaining what and why.
-More on that can be found in [this section](./supplemental-information/#writing-good-commit-messages).
+Check out [Writing Good Commit Messages](./commit-messages) for details.
 3. **Do not open a pull request if you aren't assigned to the issue.**
 If someone is already working on it, consider offering to collaborate with that person.
 4. **Use assets licensed for public use.**
@@ -28,4 +21,8 @@ Whenever the assets are images, audio or even code, they must have a license com
 We aim to foster a welcoming and friendly environment on our open source projects.
 We take violations of our Code of Conduct very seriously, and may respond with moderator action.
 
-Welcome to our projects!
+<br/>
+
+Failing to comply with our guidelines may lead to a rejection of the contribution.
+If you have questions about any of the rules, feel free to ask us in the [`#dev-contrib`](https://discord.gg/2h3qBv8Xaa) channel in our [Discord server](https://discord.gg/python).
+{: .notification .is-warning }

pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines/commit-messages.md

@@ -0,0 +1,15 @@
+---
+title: Writing Good Commit Messages
+description: Information about logging in our projects.
+---
+
+A well-structured git log is key to a project's maintainability; it provides insight into when and *why* things were done for future maintainers of the project.
+
+Commits should be as narrow in scope as possible.
+Commits that span hundreds of lines across multiple unrelated functions and/or files are very hard for maintainers to follow.
+After about a week they'll probably be hard for you to follow, too.
+
+Please also avoid making minor commits for fixing typos or linting errors.
+[Don’t forget to lint before you push!](https://soundcloud.com/lemonsaurusrex/lint-before-you-push)
+
+A more in-depth guide to writing great commit messages can be found in Chris Beam's [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/).