From 40bb274538b80eacc7e2435391af9a87d90ab23d Mon Sep 17 00:00:00 2001 From: Cam Caswell Date: Sun, 13 Mar 2022 16:15:49 -0400 Subject: Preliminary structure --- .../resources/guides/pydis-guides/contributing.md | 55 ++++++++++++++++++---- 1 file changed, 46 insertions(+), 9 deletions(-) (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md index 4013962c..2f4cce9d 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md +++ b/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:
@@ -91,14 +91,6 @@ Our projects on Python Discord are open source and [available on Github](https:/
-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! - -### Useful Resources - -[Guidelines](./contributing-guidelines/) - General guidelines you should follow when contributing to our projects.
-[Style Guide](./style-guide/) - Information regarding the code styles you should follow when working on our projects.
-[Review Guide](../code-reviews-primer/) - A guide to get you started on doing code reviews. - ## 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. @@ -114,3 +106,48 @@ As it’s difficult to precisely quantify contributions, we’ve come up with th - The member has a positive influence in our contributors subcommunity. The role will be assigned at the discretion of the Admin Team in consultation with the Core Developers Team. + + +# How do I start contributing? + Completing these steps will have you ready to make your first contribution. If you've already been using Git or GitHub feel free to skip those steps, but please make sure to read about the PyDis contributing process and ettiquette. 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. + + + +### Fork the repo + GitHub is a website based on the Git version control system that stores project files in the cloud. The people working on the project can use GitHub as a central place for sending their changes, getting their teammates' changes, and communicating with each other. Forking the repository that you want to work on will create a copy under your own GitHub account. You'll make your changes to this copy, then later we can bring them back to the PyDis repository. + + [Check out our guide on forking a GitHub repo](./forking-repository/) + +### Clone the repo + Now that you have your own fork you could make changes to it directly on GitHub, but that's not a convenient way to write code. Instead you can use Git to clone the repo to your local machine, commit changes to it there, then push those changes to GitHub. + + [Check out our guide on forking a GitHub repo](./forking-repository/) + +### Set up the project + You have the source code on your local computer, but how do you actually run it? + + [Sir Lancebot](./sir-lancebot/) + + [Python Bot](./bot/) + + [Site](./site/) + +### Ettiquette + [Guidelines](./contributing-guidelines/) +### Read the style guide + [Style Guide](./style-guide/) + +### Open a pull request + +### The review process + [Review Guide](../code-reviews-primer/) +### Create an issue + + +### Learn the basics of Git + Git is a *Version Control System*, software for carefully tracking changes to the files in a project. Git allows the same project to be worked on by people in different places. You can make changes to your local code and then distribute those changes to the other people working on the project. + + [Check out these resources to get started using Git](./working-with-git/) + + +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! -- cgit v1.2.3 From 92b1f701b3d1b159b3353db954ce06fe631e56bc Mon Sep 17 00:00:00 2001 From: Cam Caswell Date: Sun, 13 Mar 2022 16:27:45 -0400 Subject: Move Contributors role info to the Roles page --- .../resources/guides/pydis-guides/contributing.md | 17 ----------------- pydis_site/apps/content/resources/server-info/roles.md | 8 ++++++-- 2 files changed, 6 insertions(+), 19 deletions(-) (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md index 2f4cce9d..596afb53 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md @@ -91,23 +91,6 @@ Our projects on Python Discord are open source and [available on GitHub](https:/ -## 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. - -#### Guidelines for the @Contributors Role - -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: - -- The member has made several significant contributions to our projects. -- The member has a positive influence in our contributors subcommunity. - -The role will be assigned at the discretion of the Admin Team in consultation with the Core Developers Team. - - # How do I start contributing? Completing these steps will have you ready to make your first contribution. If you've already been using Git or GitHub feel free to skip those steps, but please make sure to read about the PyDis contributing process and ettiquette. 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. diff --git a/pydis_site/apps/content/resources/server-info/roles.md b/pydis_site/apps/content/resources/server-info/roles.md index 716f5b1e..d9e0af15 100644 --- a/pydis_site/apps/content/resources/server-info/roles.md +++ b/pydis_site/apps/content/resources/server-info/roles.md @@ -28,8 +28,12 @@ There are multiple requirements listed there for getting the role. This includes writing pull requests for open issues, and also for reviewing open pull requests (**we really need reviewers!**) **How to get it:** Contribute to the projects! -There is no minimum requirements, but the role is **not** assigned for every single contribution. -Read more about this in the [Guidelines for the Contributors Role](/pages/contributing/#guidelines-for-the-contributors-role) on the Contributing page. +It’s difficult to precisely quantify contributions, but we’ve come up with the following guidelines for the role: + +- The member has made several significant contributions to our projects. +- The member has a positive influence in our contributors subcommunity. + +The role will be assigned at the discretion of the Admin Team in consultation with the Core Developers Team. Check out our [walkthrough](/pages/contributing/) to get started contributing. --- -- cgit v1.2.3 From 0de454f00fd7de1991a68078eea99a3b8e7004b1 Mon Sep 17 00:00:00 2001 From: Cam Caswell Date: Sun, 13 Mar 2022 18:11:16 -0400 Subject: Remove forking and cloning sections in set-up guides --- .../guides/pydis-guides/contributing/bot.md | 27 ---------------------- .../pydis-guides/contributing/sir-lancebot.md | 19 --------------- .../guides/pydis-guides/contributing/site.md | 12 ---------- .../pydis-guides/contributing/working-with-git.md | 6 +++-- 4 files changed, 4 insertions(+), 60 deletions(-) (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/bot.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/bot.md index 2aa10aa3..0f783ef6 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/bot.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/bot.md @@ -7,33 +7,6 @@ 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). - -
- - -
-
- -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. - -#### 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. - --- ### Set Up a Test Server diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/sir-lancebot.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/sir-lancebot.md index e3cd8f0c..6e5a9199 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/sir-lancebot.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/sir-lancebot.md @@ -41,16 +41,6 @@ The requirements for Docker are: * This is only a required step for linux. Docker comes bundled with docker-compose on Mac OS and Windows. --- - -# Fork the Project -You will need your own remote (online) copy of the project repository, known as a *fork*. - -- [**Learn how to create a fork of the repository here.**](../forking-repository) - -You will do all your work in the fork rather than directly in the main repository. - ---- - # Development Environment 1. Once you have your fork, you will need to [**clone the repository to your computer**](../cloning-repository). 2. After cloning, proceed to [**install the project's dependencies**](../installing-project-dependencies). (This is not required if using Docker) @@ -121,13 +111,4 @@ After installing project dependencies use the poetry command `poetry run task st $ poetry run task start ``` ---- - -# Working with Git -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](https://github.com/python-discord/sir-lancebot/blob/main/CONTRIBUTING.md), 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. 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/) - Have fun! diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/site.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/site.md index f2c3bd95..7eda027a 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/site.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/site.md @@ -26,18 +26,6 @@ Without Docker: - [PostgreSQL](https://www.postgresql.org/download/) - Note that if you wish, the webserver can run on the host and still use Docker for PostgreSQL. ---- -# Fork the project - -You will need access to a copy of the git repository of your own that will allow you to edit the code and push your commits to. -Creating a copy of a repository under your own account is called a _fork_. - -- [Learn how to create a fork of the repository here.](../forking-repository/) - -This is where all your changes and commits will be pushed to, and from where your PRs will originate from. - -For any Core Developers, since you have write permissions already to the original repository, you can just create a feature branch to push your commits to instead. - --- # Development environment diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/working-with-git.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/working-with-git.md index 26c89b56..59c57859 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/working-with-git.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/working-with-git.md @@ -19,5 +19,7 @@ Below are links to regular workflows for working with Git using PyCharm or the C **Resources to learn Git** * [The Git Book](https://git-scm.com/book) -* [Corey Schafer's Youtube Tutorials](https://www.youtube.com/watch?v=HVsySz-h9r4&list=PL-osiE80TeTuRUfjRe54Eea17-YfnOOAx) -* [GitHub Git Resources Portal](https://try.github.io/) +* [Corey Schafer's YouTube tutorials](https://www.youtube.com/watch?v=HVsySz-h9r4&list=PL-osiE80TeTuRUfjRe54Eea17-YfnOOAx) +* [GitHub Git resources portal](https://try.github.io/) +* [Git cheatsheet](https://education.github.com/git-cheat-sheet-education.pdf) +* [Learn Git branching](https://learngitbranching.js.org) -- cgit v1.2.3 From 36b43f94cb1f8c622914048696efec8ccdeb608f Mon Sep 17 00:00:00 2001 From: Cam Caswell Date: Sat, 19 Mar 2022 23:42:45 -0400 Subject: Add guide for pull requests and reviews This covers the GitHub UI for opening a pull request, getting it reviewed, and draft PRs. --- .../pydis-guides/contributing/pull-requests.md | 41 +++++++++++++++++++++ .../images/content/contributing/pull_request.png | Bin 0 -> 10190 bytes 2 files changed, 41 insertions(+) create mode 100644 pydis_site/apps/content/resources/guides/pydis-guides/contributing/pull-requests.md create mode 100644 pydis_site/static/images/content/contributing/pull_request.png (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/pull-requests.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/pull-requests.md new file mode 100644 index 00000000..f7dee491 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/pull-requests.md @@ -0,0 +1,41 @@ +--- +title: Pull Requests +description: A guide for opening pull requests. +--- + +As stated in our [Contributing Guidelines](../contributing-guidelines/), do not open a pull request if you aren't assigned to an approved issue. You can check out our [Issues Guide](../issues/) for help with opening an issue or getting assigned to an existing one. +{: .notification .is-warning } + + +Before opening a pull request you should have: + +1. Committed your changes to your local repository +2. [Linted](../contributing-guidelines/#linting-and-pre-commit) your code +3. Tested your changes +4. Pushed the branch to your fork of the project on GitHub + +## Opening a Pull Request + +Navigate to your fork on GitHub and make sure you're on the branch with your changes. Click on `Contribute` and then `Open pull request`. + +![Pull Request UI](/static/images/content/contributing/pull_request.png) + +In the page that it opened, write an overview of the changes you made and why. This should explain how you resolved the issue that spawned this PR and highlight any differences from the proposed implementation. You should also [link the issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue). + +At this stage you can also request reviews from individual contributors. If someone showed interest in the issue or has specific knowledge about it, they may be a good reviewer. It isn't necessary to request your reviewers; someone will review your PR either way. + +## The Review Process + +Before your changes are merged, your PR needs to be reviewed by other contributors. They will read the issue and your description of your PR, look at your code, test it, and then leave comments on the PR if they find any problems, possibly with suggested changes. Sometimes this can feel intrusive or insulting, but remember that the reviewers are there to help you make your code better. + +#### If the PR is already open, how do I make changes to it? + +A pull request is between a source branch and a target branch. Updating the source branch with new commits will automatically update the PR to include those commits; they'll even show up in the comment thread of the PR. Sometimes for small changes the reviewer will even write the suggested code themself, in which case you can simply accept them with the click of a button. + +If you truly disagree with a reviewer's suggestion, leave a reply in the thread explaining why or proposing an alternative change. Also feel free to ask questions if you want clarification about suggested changes or just want to discuss them further. + +## Draft Pull Requests + +GitHub [provides a PR feature](https://github.blog/2019-02-14-introducing-draft-pull-requests/) that allows the PR author to mark it as a draft when opening it. This provides both a visual and functional indicator that the contents of the PR are in a draft state and not yet ready for formal review. This is helpful when you want people to see the changes you're making before you're ready for the final pull request. + +This feature should be utilized in place of the traditional method of prepending `[WIP]` to the PR title. diff --git a/pydis_site/static/images/content/contributing/pull_request.png b/pydis_site/static/images/content/contributing/pull_request.png new file mode 100644 index 00000000..87b7ffbe Binary files /dev/null and b/pydis_site/static/images/content/contributing/pull_request.png differ -- cgit v1.2.3 From d198b3e02236e65bc2d8fceb9d7d8776dc306b87 Mon Sep 17 00:00:00 2001 From: Cam Caswell Date: Sun, 20 Mar 2022 14:56:05 -0400 Subject: Split up Supplemental Info and touch up Contrib Guidelines Created new pages: * Linting * Logging * Writing Good Commit Messages Moved Draft PR section to new pull requests guide Moved type hinting section to style guide --- .../contributing/contributing-guidelines.md | 25 +++--- .../contributing-guidelines/commit-messages.md | 15 ++++ .../supplemental-information.md | 99 ---------------------- .../guides/pydis-guides/contributing/linting.md | 14 +++ .../guides/pydis-guides/contributing/logging.md | 31 +++++++ .../pydis-guides/contributing/pull-requests.md | 2 +- .../pydis-guides/contributing/style-guide.md | 24 +++--- 7 files changed, 82 insertions(+), 128 deletions(-) create mode 100644 pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines/commit-messages.md delete mode 100644 pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines/supplemental-information.md create mode 100644 pydis_site/apps/content/resources/guides/pydis-guides/contributing/linting.md create mode 100644 pydis_site/apps/content/resources/guides/pydis-guides/contributing/logging.md (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines.md index de1777f2..f13b05be 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines.md +++ b/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! +
+ +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` channel in our [Discord server](https://discord.gg/python). +{: .notification .is-warning } diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines/commit-messages.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines/commit-messages.md new file mode 100644 index 00000000..ba476b65 --- /dev/null +++ b/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/). diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines/supplemental-information.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines/supplemental-information.md deleted file mode 100644 index e64e4fc6..00000000 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines/supplemental-information.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Supplemental Information -description: Additional information related to our contributing guidelines. ---- - -This page contains additional information concerning a specific part of our development pipeline. - -## Writing Good Commit Messages - -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/).* - -## Code Style - -All of our projects have a certain project-wide style that contributions should attempt to maintain consistency with. -During PR review, it's not unusual for style adjustments to be requested. - -[This page](../../style-guide/) will reference the differences between our projects and what is recommended by [PEP 8.](https://www.python.org/dev/peps/pep-0008/) - -## Linting and Pre-commit - -On most of our projects, we use `flake8` and `pre-commit` to ensure that the code style is consistent across the code base. - -Running `flake8` will warn you about any potential style errors in your contribution. -You must always check it **before pushing**. -Your commit will be rejected by the build server if it fails to lint. - -**Some style rules are not enforced by flake8. Make sure to read the [style guide](../../style-guide/).** - -`pre-commit` is a powerful tool that helps you automatically lint before you commit. -If the linter complains, the commit is aborted so that you can fix the linting errors before committing again. -That way, you never commit the problematic code in the first place! - -Please refer to the project-specific documentation to see how to setup and run those tools. -In most cases, you can install pre-commit using `poetry run task precommit`, and lint using `poetry run task lint`. - -## Type Hinting - -[PEP 484](https://www.python.org/dev/peps/pep-0484/) formally specifies type hints for Python functions, added to the Python Standard Library in version 3.5. -Type hints are recognized by most modern code editing tools and provide useful insight into both the input and output types of a function, preventing the user from having to go through the codebase to determine these types. - -For example: - -```python -import typing - -def foo(input_1: int, input_2: typing.Dict[str, str]) -> bool: - ... -``` - -This tells us that `foo` accepts an `int` and a `dict`, with `str` keys and values, and returns a `bool`. - -If the project is running Python 3.9 or above, you can use `dict` instead of `typing.Dict`. -See [PEP 585](https://www.python.org/dev/peps/pep-0585/) for more information. - -All function declarations should be type hinted in code contributed to the PyDis organization. - -## Logging - -Instead of using `print` statements for logging, we use the built-in [`logging`](https://docs.python.org/3/library/logging.html) module. -Here is an example usage: - -```python -import logging - -log = logging.getLogger(__name__) # Get a logger bound to the module name. -# This line is usually placed under the import statements at the top of the file. - -log.trace("This is a trace log.") -log.warning("BEEP! This is a warning.") -log.critical("It is about to go down!") -``` - -Print statements should be avoided when possible. -Our projects currently defines logging levels as follows, from lowest to highest severity: - -- **TRACE:** These events should be used to provide a *verbose* trace of every step of a complex process. This is essentially the `logging` equivalent of sprinkling `print` statements throughout the code. -- **Note:** This is a PyDis-implemented logging level. It may not be available on every project. -- **DEBUG:** These events should add context to what's happening in a development setup to make it easier to follow what's going while workig on a project. This is in the same vein as **TRACE** logging but at a much lower level of verbosity. -- **INFO:** These events are normal and don't need direct attention but are worth keeping track of in production, like checking which cogs were loaded during a start-up. -- **WARNING:** These events are out of the ordinary and should be fixed, but can cause a failure. -- **ERROR:** These events can cause a failure in a specific part of the application and require urgent attention. -- **CRITICAL:** These events can cause the whole application to fail and require immediate intervention. - -Any logging above the **INFO** level will trigger a [Sentry](https://sentry.io) issue and alert the Core Developer team. - -## Draft Pull Requests - -Github [provides a PR feature](https://github.blog/2019-02-14-introducing-draft-pull-requests/) that allows the PR author to mark it as a Draft when opening it. This provides both a visual and functional indicator that the contents of the PR are in a draft state and not yet ready for formal review. - -This feature should be utilized in place of the traditional method of prepending `[WIP]` to the PR title. diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/linting.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/linting.md new file mode 100644 index 00000000..48f1cafc --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/linting.md @@ -0,0 +1,14 @@ +--- +title: Linting +description: A guide for linting and setting up pre-commit. +--- + +Your commit will be rejected by the build server if it fails to lint. +On most of our projects, we use `flake8` and `pre-commit` to ensure that the code style is consistent across the code base. + +`pre-commit` is a powerful tool that helps you automatically lint before you commit. +If the linter complains, the commit is aborted so that you can fix the linting errors before committing again. +That way, you never commit the problematic code in the first place! + +Please refer to the project-specific documentation to see how to setup and run those tools. +In most cases, you can install pre-commit using `poetry run task precommit`, and lint using `poetry run task lint`. diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/logging.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/logging.md new file mode 100644 index 00000000..1291a7a4 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/logging.md @@ -0,0 +1,31 @@ +--- +title: Logging +description: Information about logging in our projects. +--- + +Instead of using `print` statements for logging, we use the built-in [`logging`](https://docs.python.org/3/library/logging.html) module. +Here is an example usage: + +```python +import logging + +log = logging.getLogger(__name__) # Get a logger bound to the module name. +# This line is usually placed under the import statements at the top of the file. + +log.trace("This is a trace log.") +log.warning("BEEP! This is a warning.") +log.critical("It is about to go down!") +``` + +Print statements should be avoided when possible. +Our projects currently defines logging levels as follows, from lowest to highest severity: + +- **TRACE:** These events should be used to provide a *verbose* trace of every step of a complex process. This is essentially the `logging` equivalent of sprinkling `print` statements throughout the code. +- **Note:** This is a PyDis-implemented logging level. It may not be available on every project. +- **DEBUG:** These events should add context to what's happening in a development setup to make it easier to follow what's going while workig on a project. This is in the same vein as **TRACE** logging but at a much lower level of verbosity. +- **INFO:** These events are normal and don't need direct attention but are worth keeping track of in production, like checking which cogs were loaded during a start-up. +- **WARNING:** These events are out of the ordinary and should be fixed, but can cause a failure. +- **ERROR:** These events can cause a failure in a specific part of the application and require urgent attention. +- **CRITICAL:** These events can cause the whole application to fail and require immediate intervention. + +Any logging above the **INFO** level will trigger a [Sentry](https://sentry.io) issue and alert the Core Developer team. diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/pull-requests.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/pull-requests.md index f7dee491..a9b6385e 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/pull-requests.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/pull-requests.md @@ -10,7 +10,7 @@ As stated in our [Contributing Guidelines](../contributing-guidelines/), do not Before opening a pull request you should have: 1. Committed your changes to your local repository -2. [Linted](../contributing-guidelines/#linting-and-pre-commit) your code +2. [Linted](../linting/) your code 3. Tested your changes 4. Pushed the branch to your fork of the project on GitHub diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/style-guide.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/style-guide.md index f9962990..4dba45c8 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/style-guide.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/style-guide.md @@ -191,21 +191,17 @@ Present tense defines that the work being done is now, in the present, rather th **Use:** "Build an information embed."
**Don't use:** "Built an information embed." or "Will build an information embed." -# Type Annotations -Functions are required to have type annotations as per the style defined in [PEP 484](https://www.python.org/dev/peps/pep-0484/). +# Type Hinting +Functions are required to have type annotations as per the style defined in [PEP 484](https://www.python.org/dev/peps/pep-0484/). Type hints are recognized by most modern code editing tools and provide useful insight into both the input and output types of a function, preventing the user from having to go through the codebase to determine these types. -A function without annotations might look like: -```py -def divide(a, b): - """Divide the two given arguments.""" - return a / b -``` - -With annotations, the arguments and the function are annotated with their respective types: -```py -def divide(a: int, b: int) -> float: - """Divide the two given arguments.""" - return a / b +A function with type hints looks like: +```python +def foo(input_1: int, input_2: dict[str, int]) -> bool: + ... ``` +This tells us that `foo` accepts an `int` and a `dict`, with `str` keys and `int` values, and returns a `bool`. In previous examples, we have purposely omitted annotations to keep focus on the specific points they represent. + +> **Note:** if the project is running Python 3.8 or below you have to use `typing.Dict` instead of `dict`, but our three main projects are all >=3.9. +> See [PEP 585](https://www.python.org/dev/peps/pep-0585/) for more information. -- cgit v1.2.3 From 79694efe7bb13a9d6791844e7a836b7f4350308d Mon Sep 17 00:00:00 2001 From: Cam Caswell Date: Sun, 20 Mar 2022 17:08:08 -0400 Subject: Write walkthrough --- .../resources/guides/pydis-guides/contributing.md | 60 +++++++++++++--------- 1 file changed, 36 insertions(+), 24 deletions(-) (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md index 596afb53..759ed1dc 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md @@ -92,45 +92,57 @@ Our projects on Python Discord are open source and [available on GitHub](https:/ # How do I start contributing? - Completing these steps will have you ready to make your first contribution. If you've already been using Git or GitHub feel free to skip those steps, but please make sure to read about the PyDis contributing process and ettiquette. 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. + 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. + 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. -### Fork the repo - GitHub is a website based on the Git version control system that stores project files in the cloud. The people working on the project can use GitHub as a central place for sending their changes, getting their teammates' changes, and communicating with each other. Forking the repository that you want to work on will create a copy under your own GitHub account. You'll make your changes to this copy, then later we can bring them back to the PyDis repository. +### 1. Learn the basics of Git + Git is a _Version Control System_, software for carefully tracking changes to the files in a project. Git allows the same project to be worked on by people in different places. You can make changes to your local code and then distribute those changes to the other people working on the project. - [Check out our guide on forking a GitHub repo](./forking-repository/) + Check out these [**resources to get started using Git**](./working-with-git/). -### Clone the repo - Now that you have your own fork you could make changes to it directly on GitHub, but that's not a convenient way to write code. Instead you can use Git to clone the repo to your local machine, commit changes to it there, then push those changes to GitHub. +### 2. Fork the repo + GitHub is a website based on the Git version control system that stores project files in the cloud. The people working on the project can use GitHub as a central place for sending their changes, getting their teammates' changes, and communicating with each other. Forking the repository that you want to work on will create a copy under your own GitHub account. You'll make your changes to this copy, then later we can bring them back to the PyDis repository. - [Check out our guide on forking a GitHub repo](./forking-repository/) + Check out our [**guide on forking a GitHub repo**](./forking-repository/). -### Set up the project - You have the source code on your local computer, but how do you actually run it? +### 3. Clone the repo + 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. - [Sir Lancebot](./sir-lancebot/) + Check out our [**guide on cloning a GitHub repo**](./cloning-repository/). - [Python Bot](./bot/) +### 4. 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 projects: - [Site](./site/) + * [**Sir Lancebot**](./sir-lancebot/) -### Ettiquette - [Guidelines](./contributing-guidelines/) -### Read the style guide - [Style Guide](./style-guide/) + * [**Python Bot**](./bot/) -### Open a pull request + * [**Site**](./site/) -### The review process - [Review Guide](../code-reviews-primer/) -### Create an issue +### 5. 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/). -### Learn the basics of Git - Git is a *Version Control System*, software for carefully tracking changes to the files in a project. Git allows the same project to be worked on by people in different places. You can make changes to your local code and then distribute those changes to the other people working on the project. + 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. - [Check out these resources to get started using Git](./working-with-git/) + [**Style Guide**](./style-guide/) +### 6. 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 an idea that you want to implement, open a new issue (and check out our [**guide on writing an issue**](./issues/)). 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`channel on Discord. -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! + 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 } + +### 7. 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. + + Check out our [**Pull Request Guide**](./contributing/pull-requests/) for help with opening a pull request and going through the review process. + + 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! + +### That's it! +Thank you for contributing to our community projects. If you don't understand anything or need clarification, feel free to ask a question in the`dev-contrib`channel and keep an eye out for staff members with the **@PyDis Core Developers** role in the server. We're always happy to help! -- cgit v1.2.3 From e76e0a5f2d80a4f5ec31fe015155b0349f9f607b Mon Sep 17 00:00:00 2001 From: Cam Caswell Date: Sun, 20 Mar 2022 18:55:16 -0400 Subject: Fix PR page link --- pydis_site/apps/content/resources/guides/pydis-guides/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md index 759ed1dc..51991d9c 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md @@ -140,7 +140,7 @@ Our projects on Python Discord are open source and [available on GitHub](https:/ ### 7. 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. - Check out our [**Pull Request Guide**](./contributing/pull-requests/) for help with opening a pull request and going through the review process. + Check out our [**Pull Request Guide**](./pull-requests/) for help with opening a pull request and going through the review process. 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! -- cgit v1.2.3 From 1017676bea05d423d86a29c2ede769a6288a3d4a Mon Sep 17 00:00:00 2001 From: Cam Caswell Date: Sat, 26 Mar 2022 22:33:03 -0400 Subject: Fix commit-messages link --- .../guides/pydis-guides/contributing/contributing-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines.md index f13b05be..1917ee43 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines.md @@ -12,7 +12,7 @@ We have simple but strict style rules that are enforced through linting. 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. -Check out [Writing Good Commit Messages](/commit-messages) for details. +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.** -- cgit v1.2.3 From 15a32db18b72291913cf80b9fc85ac578b824f34 Mon Sep 17 00:00:00 2001 From: Cam Caswell Date: Sun, 27 Mar 2022 00:06:14 -0400 Subject: Make small wording improvements --- .../apps/content/resources/guides/pydis-guides/contributing.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md index 51991d9c..4b53d978 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md @@ -92,7 +92,7 @@ Our projects on Python Discord are open source and [available on GitHub](https:/ # 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. + 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). @@ -107,7 +107,6 @@ Our projects on Python Discord are open source and [available on GitHub](https:/ GitHub is a website based on the Git version control system that stores project files in the cloud. The people working on the project can use GitHub as a central place for sending their changes, getting their teammates' changes, and communicating with each other. Forking the repository that you want to work on will create a copy under your own GitHub account. You'll make your changes to this copy, then later we can bring them back to the PyDis repository. Check out our [**guide on forking a GitHub repo**](./forking-repository/). - ### 3. Clone the repo 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. @@ -145,4 +144,4 @@ Our projects on Python Discord are open source and [available on GitHub](https:/ 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! ### That's it! -Thank you for contributing to our community projects. If you don't understand anything or need clarification, feel free to ask a question in the`dev-contrib`channel and keep an eye out for staff members with the **@PyDis Core Developers** role in the server. We're always happy to help! +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`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! -- cgit v1.2.3 From 788c8fc1b3fc54fa35dc8282b8a1267314e85a77 Mon Sep 17 00:00:00 2001 From: Cam Caswell Date: Thu, 7 Apr 2022 22:44:09 -0400 Subject: Replace difficulty badges with more description --- .../resources/guides/pydis-guides/contributing.md | 18 +++--------------- 1 file changed, 3 insertions(+), 15 deletions(-) (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md index 4b53d978..e4b3e621 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md @@ -19,11 +19,7 @@ Our projects on Python Discord are open source and [available on GitHub](https:/
- Our community-driven Discord bot. -
-
- Difficulty - Beginner + 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!
@@ -46,11 +42,7 @@ Our projects on Python Discord are open source and [available on GitHub](https:/
- The community and moderation Discord bot. -
-
- Difficulty - Intermediate + Called @Python on the server, this bot handles moderation tools, help channels, and other critical features for our community.
@@ -73,11 +65,7 @@ Our projects on Python Discord are open source and [available on GitHub](https:/
- The website, subdomains and API. -
-
- Difficulty - Advanced + This website itself! This project is built with Django and includes our API, which is used by various services such as @Python.
-- cgit v1.2.3 From 1290df613d23441afc61191b78fe2de26df839f7 Mon Sep 17 00:00:00 2001 From: camcaswell <38672443+camcaswell@users.noreply.github.com> Date: Thu, 7 Apr 2022 23:24:50 -0400 Subject: Clarify main projects Co-authored-by: Boris Muratov <8bee278@gmail.com> --- pydis_site/apps/content/resources/guides/pydis-guides/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md index e4b3e621..868b5899 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md @@ -101,7 +101,7 @@ Our projects on Python Discord are open source and [available on GitHub](https:/ Check out our [**guide on cloning a GitHub repo**](./cloning-repository/). ### 4. 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 projects: + 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/) -- cgit v1.2.3 From 734d26c8c260eab0f2edb4e784da5bf42e07bbda Mon Sep 17 00:00:00 2001 From: Cam Caswell Date: Fri, 8 Apr 2022 14:33:55 -0400 Subject: Add links to #dev-contrib --- pydis_site/apps/content/resources/guides/pydis-guides/contributing.md | 4 ++-- .../guides/pydis-guides/contributing/contributing-guidelines.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md index e4b3e621..0c95abe0 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md @@ -119,7 +119,7 @@ Our projects on Python Discord are open source and [available on GitHub](https:/ [**Style Guide**](./style-guide/) ### 6. 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 an idea that you want to implement, open a new issue (and check out our [**guide on writing an issue**](./issues/)). 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`channel on Discord. + 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 an idea that you want to implement, open a new issue (and check out our [**guide on writing an issue**](./issues/)). 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. 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 } @@ -132,4 +132,4 @@ Our projects on Python Discord are open source and [available on GitHub](https:/ 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! ### 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`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! +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! diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines.md index 1917ee43..b7a22677 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines.md @@ -24,5 +24,5 @@ We take violations of our Code of Conduct very seriously, and may respond with m
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` channel in our [Discord server](https://discord.gg/python). +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 } -- cgit v1.2.3 From f3811ad0a5f06f524f678003594ad173a2dddbb5 Mon Sep 17 00:00:00 2001 From: Cam Caswell Date: Fri, 8 Apr 2022 17:03:54 -0400 Subject: Shorten and combine steps --- .../resources/guides/pydis-guides/contributing.md | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md index 6e500500..a7701d4f 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md @@ -86,21 +86,19 @@ Our projects on Python Discord are open source and [available on GitHub](https:/ 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. -### 1. Learn the basics of Git - Git is a _Version Control System_, software for carefully tracking changes to the files in a project. Git allows the same project to be worked on by people in different places. You can make changes to your local code and then distribute those changes to the other people working on the project. + **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 } - Check out these [**resources to get started using Git**](./working-with-git/). - -### 2. Fork the repo - GitHub is a website based on the Git version control system that stores project files in the cloud. The people working on the project can use GitHub as a central place for sending their changes, getting their teammates' changes, and communicating with each other. Forking the repository that you want to work on will create a copy under your own GitHub account. You'll make your changes to this copy, then later we can bring them back to the PyDis repository. +### 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 fork the repository to create a copy under your own GitHub account. You'll make your changes to this copy, which can then later be merged into the PyDis repository. Check out our [**guide on forking a GitHub repo**](./forking-repository/). -### 3. Clone the repo + 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/). -### 4. Set up the project +### 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/) @@ -109,7 +107,7 @@ Our projects on Python Discord are open source and [available on GitHub](https:/ * [**Site**](./site/) -### 5. Read our Contributing Guidelines +### 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/). @@ -118,13 +116,13 @@ Our projects on Python Discord are open source and [available on GitHub](https:/ [**Style Guide**](./style-guide/) -### 6. Create an issue +### 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 an idea that you want to implement, open a new issue (and check out our [**guide on writing an issue**](./issues/)). 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. 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 } -### 7. Open a pull request +### 5. 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. Check out our [**Pull Request Guide**](./pull-requests/) for help with opening a pull request and going through the review process. -- cgit v1.2.3 From 85755c99adaffee2d65bc3d09ff45b79f10bde91 Mon Sep 17 00:00:00 2001 From: Cam Caswell Date: Fri, 8 Apr 2022 17:31:50 -0400 Subject: Add link to forking guide --- .../content/resources/guides/pydis-guides/contributing/sir-lancebot.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/sir-lancebot.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/sir-lancebot.md index 6e5a9199..1621abb6 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/sir-lancebot.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/sir-lancebot.md @@ -19,7 +19,7 @@ toc: 1 ## Using Gitpod Sir Lancebot can be edited and tested on Gitpod. Gitpod will automatically install the correct dependencies and Python version, so you can get straight to coding. -To do this, you will need a Gitpod account, which you can get [here](https://www.gitpod.io/#get-started), and a fork of Sir Lancebot. This guide covers forking the repository [here](#fork-the-project). +To do this, you will need a Gitpod account, which you can get [here](https://www.gitpod.io/#get-started), and a fork of Sir Lancebot. This guide covers forking the repository [here](../forking-repository). Afterwards, click on [this link](https://gitpod.io/#/github.com/python-discord/sir-lancebot) to spin up a new workspace for Sir Lancebot. Then run the following commands in the terminal after the existing tasks have finished running: ```sh -- cgit v1.2.3 From 7f6547e812c633464a68ed027dd79413384cb218 Mon Sep 17 00:00:00 2001 From: camcaswell <38672443+camcaswell@users.noreply.github.com> Date: Thu, 21 Apr 2022 16:15:13 -0400 Subject: Change period to colon Co-authored-by: Bluenix --- .../content/resources/guides/pydis-guides/contributing/pull-requests.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/pull-requests.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/pull-requests.md index a9b6385e..c1ce1bf6 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/pull-requests.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/pull-requests.md @@ -16,7 +16,7 @@ Before opening a pull request you should have: ## Opening a Pull Request -Navigate to your fork on GitHub and make sure you're on the branch with your changes. Click on `Contribute` and then `Open pull request`. +Navigate to your fork on GitHub and make sure you're on the branch with your changes. Click on `Contribute` and then `Open pull request`: ![Pull Request UI](/static/images/content/contributing/pull_request.png) -- cgit v1.2.3 From e09fade2fb9de84180539d58c00a229f8812c9fb Mon Sep 17 00:00:00 2001 From: Cam Caswell Date: Thu, 21 Apr 2022 16:22:23 -0400 Subject: Remove redundant newline --- .../content/resources/guides/pydis-guides/contributing/pull-requests.md | 1 - 1 file changed, 1 deletion(-) (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/pull-requests.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/pull-requests.md index c1ce1bf6..d193a455 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/pull-requests.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/pull-requests.md @@ -6,7 +6,6 @@ description: A guide for opening pull requests. As stated in our [Contributing Guidelines](../contributing-guidelines/), do not open a pull request if you aren't assigned to an approved issue. You can check out our [Issues Guide](../issues/) for help with opening an issue or getting assigned to an existing one. {: .notification .is-warning } - Before opening a pull request you should have: 1. Committed your changes to your local repository -- cgit v1.2.3 From 2e741c3e756e5a0cdf7ea2a061857709d5e828ce Mon Sep 17 00:00:00 2001 From: camcaswell <38672443+camcaswell@users.noreply.github.com> Date: Thu, 21 Apr 2022 16:28:03 -0400 Subject: Add clarification about poetry console commands Co-authored-by: Bluenix --- .../apps/content/resources/guides/pydis-guides/contributing/linting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/linting.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/linting.md index 48f1cafc..f6f8a5f2 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/linting.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/linting.md @@ -11,4 +11,4 @@ If the linter complains, the commit is aborted so that you can fix the linting e That way, you never commit the problematic code in the first place! Please refer to the project-specific documentation to see how to setup and run those tools. -In most cases, you can install pre-commit using `poetry run task precommit`, and lint using `poetry run task lint`. +In most cases, you can install pre-commit using `poetry run task precommit`, and lint using `poetry run task lint` in the console. -- cgit v1.2.3 From 55ab3e2f72f79e981ed13bd5788ffe1d85f73b28 Mon Sep 17 00:00:00 2001 From: Cam Caswell Date: Thu, 21 Apr 2022 16:44:44 -0400 Subject: Remove unneeded indentation --- .../resources/guides/pydis-guides/contributing.md | 36 +++++++++++----------- 1 file changed, 18 insertions(+), 18 deletions(-) (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md index a7701d4f..a3e51440 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md @@ -90,44 +90,44 @@ Our projects on Python Discord are open source and [available on GitHub](https:/ {: .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 fork the repository to create a copy under your own GitHub account. You'll make your changes to this copy, which can then later be merged into the PyDis repository. +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 fork the repository to create a copy under your own GitHub account. You'll make your changes to this copy, which can then later be merged into the PyDis repository. - Check out our [**guide on forking a GitHub repo**](./forking-repository/). +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. +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/). +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: +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/) +* [**Sir Lancebot**](./sir-lancebot/) - * [**Python Bot**](./bot/) +* [**Python Bot**](./bot/) - * [**Site**](./site/) +* [**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. +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/). +[**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. +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/) +[**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 an idea that you want to implement, open a new issue (and check out our [**guide on writing an issue**](./issues/)). 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. +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 an idea that you want to implement, open a new issue (and check out our [**guide on writing an issue**](./issues/)). 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. - 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 } +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 } ### 5. 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. +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. - Check out our [**Pull Request Guide**](./pull-requests/) for help with opening a pull request and going through the review process. +Check out our [**Pull Request Guide**](./pull-requests/) for help with opening a pull request and going through the review process. - 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! +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! ### 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! -- cgit v1.2.3 From ece0657d143a5663a76e658a0975fed478a513e6 Mon Sep 17 00:00:00 2001 From: Cam Caswell Date: Thu, 21 Apr 2022 17:12:39 -0400 Subject: Add spaces around code snippets --- pydis_site/apps/content/resources/guides/pydis-guides/contributing.md | 4 ++-- .../guides/pydis-guides/contributing/contributing-guidelines.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md index a3e51440..411ad9d4 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md @@ -117,7 +117,7 @@ As mentioned in the Contributing Guidelines, we have a simple style guide for ou [**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 an idea that you want to implement, open a new issue (and check out our [**guide on writing an issue**](./issues/)). 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. +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 an idea that you want to implement, open a new issue (and check out our [**guide on writing an issue**](./issues/)). 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. 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 } @@ -130,4 +130,4 @@ Check out our [**Pull Request Guide**](./pull-requests/) for help with opening a 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! ### 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! +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! diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines.md index b7a22677..73c5dcab 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines.md @@ -24,5 +24,5 @@ We take violations of our Code of Conduct very seriously, and may respond with m
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). +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 } -- cgit v1.2.3 From 557d839e20abbcc5c5c1bedf6c866abbcd81af8c Mon Sep 17 00:00:00 2001 From: Cam Caswell Date: Thu, 21 Apr 2022 17:27:38 -0400 Subject: Removed double space --- pydis_site/apps/content/resources/guides/pydis-guides/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md index 411ad9d4..33b5f066 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md @@ -82,7 +82,7 @@ Our projects on Python Discord are open source and [available on GitHub](https:/ # 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). + 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. -- cgit v1.2.3 From ed7886a6a420be27082e1a0babe83fa883dde998 Mon Sep 17 00:00:00 2001 From: Cam Caswell Date: Sun, 24 Apr 2022 14:58:46 -0400 Subject: Pydis -> Python Discord --- pydis_site/apps/content/resources/guides/pydis-guides/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md index 33b5f066..03e5fe18 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md @@ -90,7 +90,7 @@ Our projects on Python Discord are open source and [available on GitHub](https:/ {: .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 fork the repository to create a copy under your own GitHub account. You'll make your changes to this copy, which can then later be merged into the PyDis repository. +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 fork the repository to create a copy under your own GitHub account. You'll make your changes to this copy, which can then later be merged into the Python Discord repository. Check out our [**guide on forking a GitHub repo**](./forking-repository/). -- cgit v1.2.3 From 32cf915246fbec5d3dc792d717b50af635108ca3 Mon Sep 17 00:00:00 2001 From: Cam Caswell Date: Sun, 24 Apr 2022 15:04:22 -0400 Subject: Make it clearer what forking is --- pydis_site/apps/content/resources/guides/pydis-guides/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md index 03e5fe18..603e81ad 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md @@ -90,7 +90,7 @@ Our projects on Python Discord are open source and [available on GitHub](https:/ {: .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 fork the repository to create a copy under your own GitHub account. You'll make your changes to this copy, which can then later be merged into the Python Discord repository. +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 of the repository under your own GitHub account, aka "fork" it. You'll make your changes to this copy, which can then later be merged into the Python Discord repository. Check out our [**guide on forking a GitHub repo**](./forking-repository/). -- cgit v1.2.3 From 8edb7f95b75b144c21fded1c723605d0cfa84ff8 Mon Sep 17 00:00:00 2001 From: Cam Caswell Date: Sun, 24 Apr 2022 15:05:19 -0400 Subject: Annihilate some indent holdouts --- .../apps/content/resources/guides/pydis-guides/contributing.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md index 603e81ad..fa829c9f 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md @@ -80,14 +80,14 @@ Our projects on Python Discord are open source and [available on GitHub](https:/
# 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. +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). +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. +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 } +**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 of the repository under your own GitHub account, aka "fork" it. You'll make your changes to this copy, which can then later be merged into the Python Discord repository. -- cgit v1.2.3 From d4150fdf04b3712655239a4fd77ee066f0920eda Mon Sep 17 00:00:00 2001 From: Cam Caswell Date: Sun, 24 Apr 2022 15:13:28 -0400 Subject: Move link to issue guide to match others --- pydis_site/apps/content/resources/guides/pydis-guides/contributing.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md index fa829c9f..e19e2cea 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md @@ -117,7 +117,9 @@ As mentioned in the Contributing Guidelines, we have a simple style guide for ou [**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 an idea that you want to implement, open a new issue (and check out our [**guide on writing an issue**](./issues/)). 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. +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/) 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 } -- cgit v1.2.3 From 371a5b7650b4fbea1ff30e0afd63563882f33b3f Mon Sep 17 00:00:00 2001 From: Cam Caswell Date: Sun, 24 Apr 2022 15:14:08 -0400 Subject: Revert "Make it clearer what forking is" This reverts commit 32cf915246fbec5d3dc792d717b50af635108ca3. --- pydis_site/apps/content/resources/guides/pydis-guides/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md index e19e2cea..db466029 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md @@ -90,7 +90,7 @@ If you are here looking for the answer to a specific question, check out the sub {: .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 of the repository under your own GitHub account, aka "fork" it. You'll make your changes to this copy, which can then later be merged into the Python Discord repository. +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 fork the repository to create a copy under your own GitHub account. You'll make your changes to this copy, which can then later be merged into the Python Discord repository. Check out our [**guide on forking a GitHub repo**](./forking-repository/). -- cgit v1.2.3 From d75612d9431c330481a16d61d43aaefea733eb8f Mon Sep 17 00:00:00 2001 From: Cam Caswell Date: Sun, 24 Apr 2022 15:15:59 -0400 Subject: Make it more clear what forking is --- pydis_site/apps/content/resources/guides/pydis-guides/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md index db466029..bed2ffa1 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md @@ -90,7 +90,7 @@ If you are here looking for the answer to a specific question, check out the sub {: .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 fork the repository to create a copy under your own GitHub account. You'll make your changes to this copy, which can then later be merged into the Python Discord repository. +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. Check out our [**guide on forking a GitHub repo**](./forking-repository/). -- cgit v1.2.3 From 56648f34bb48b40668a4ae48f4117fcbaaadea23 Mon Sep 17 00:00:00 2001 From: Cam Caswell Date: Sat, 7 May 2022 21:52:57 -0400 Subject: Add 'Next steps' section to ends of the setup guides --- .../resources/guides/pydis-guides/contributing/bot.md | 12 ++++++++---- .../guides/pydis-guides/contributing/sir-lancebot.md | 6 ++++++ .../resources/guides/pydis-guides/contributing/site.md | 9 +++++++++ 3 files changed, 23 insertions(+), 4 deletions(-) (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/bot.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/bot.md index 0f783ef6..e98db596 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/bot.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/bot.md @@ -543,10 +543,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/) @@ -637,4 +634,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! diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/sir-lancebot.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/sir-lancebot.md index 1621abb6..f5f1ae4c 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/sir-lancebot.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/sir-lancebot.md @@ -110,5 +110,11 @@ After installing project dependencies use the poetry command `poetry run task st ```shell $ poetry run task start ``` +--- + +# 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! diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/site.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/site.md index 7eda027a..00115516 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/site.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/site.md @@ -166,3 +166,12 @@ The website is configured through the following environment variables: - **`STATIC_ROOT`**: The root in which `python manage.py collectstatic` collects static files. Optional, defaults to `/app/staticfiles` for the standard Docker deployment. + +--- + +# Next steps +Now that you have everything setup, it is finally time to make changes to the site! 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! -- cgit v1.2.3 From 2b45c6c0b13b1183051659b7ea3660b1d6efc90b Mon Sep 17 00:00:00 2001 From: Cam Caswell Date: Sat, 7 May 2022 22:57:24 -0400 Subject: Add reminders at tops of set-up guides to fork and clone --- .../resources/guides/pydis-guides/contributing/bot.md | 2 ++ .../guides/pydis-guides/contributing/sir-lancebot.md | 12 +++++++----- .../resources/guides/pydis-guides/contributing/site.md | 7 ++++--- 3 files changed, 13 insertions(+), 8 deletions(-) (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/bot.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/bot.md index e98db596..ad446cc8 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/bot.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/bot.md @@ -5,6 +5,8 @@ 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). +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). + This page will focus on the quickest steps one can take, with mentions of alternatives afterwards. --- diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/sir-lancebot.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/sir-lancebot.md index f5f1ae4c..c9566d23 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/sir-lancebot.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/sir-lancebot.md @@ -5,10 +5,11 @@ icon: fab fa-github toc: 1 --- -> Before contributing, please ensure you read the [contributing guidelines](../contributing-guidelines) in full. +You should have already forked the [`sir-lancebot`](https://github.com/python-discord/sir-lancebot) repository and cloned it to your local machine. If not, check out our [detailed walkthrough](../#1-fork-and-clone-the-repo). ---- -# Requirements +Remember to ensure that you have read the [contributing guidelines](../contributing-guidelines) in full before you start contributing. + +### Requirements - [Python 3.9](https://www.python.org/downloads/) - [Poetry](https://github.com/python-poetry/poetry#installation) - [Git](https://git-scm.com/downloads) @@ -16,6 +17,8 @@ toc: 1 - [MacOS Installer](https://git-scm.com/download/mac) or `brew install git` - [Linux](https://git-scm.com/download/linux) +--- + ## Using Gitpod Sir Lancebot can be edited and tested on Gitpod. Gitpod will automatically install the correct dependencies and Python version, so you can get straight to coding. @@ -42,8 +45,7 @@ The requirements for Docker are: --- # Development Environment -1. Once you have your fork, you will need to [**clone the repository to your computer**](../cloning-repository). -2. After cloning, proceed to [**install the project's dependencies**](../installing-project-dependencies). (This is not required if using Docker) +If you aren't using Docker, you will need to [install the project's dependencies](../installing-project-dependencies) yourself. --- # Test Server and Bot Account diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/site.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/site.md index 00115516..520e41ad 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/site.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/site.md @@ -5,7 +5,9 @@ icon: fab fa-github toc: 1 --- -# Requirements +You should have already forked the [`site`](https://github.com/python-discord/site) repository and cloned it to your local machine. If not, check out our [detailed walkthrough](../#1-fork-and-clone-the-repo). + +### Requirements - [Python 3.9](https://www.python.org/downloads/) - [Poetry](https://python-poetry.org/docs/#installation) @@ -29,8 +31,7 @@ Without Docker: --- # Development environment -1. [Clone your fork to a local project directory](../cloning-repository/) -2. [Install the project's dependencies](../installing-project-dependencies/) +[Install the project's dependencies](../installing-project-dependencies/) ## Without Docker -- cgit v1.2.3 From 0cce77e26b19949ed14da740f3bb9ed843af4255 Mon Sep 17 00:00:00 2001 From: Cam Caswell Date: Sun, 8 May 2022 12:06:26 -0400 Subject: Add note that staff members can create feature branches --- pydis_site/apps/content/resources/guides/pydis-guides/contributing.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md index bed2ffa1..d67a827f 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md @@ -92,6 +92,8 @@ If you are here looking for the answer to a specific question, check out the sub ### 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. -- cgit v1.2.3 From 2470557cb6f4ce9eb10bdf1759f67b03e1506b6e Mon Sep 17 00:00:00 2001 From: Cam Caswell Date: Sun, 8 May 2022 12:33:59 -0400 Subject: Add Making Changes step --- .../apps/content/resources/guides/pydis-guides/contributing.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md index d67a827f..6231fe87 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md @@ -126,7 +126,12 @@ The first step to any new contribution is an issue describing a problem with the 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 } -### 5. Open a pull request +### 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. + +This is a good time to review [how to write good commit messages](./contributing-guidelines/commit-messages) if you haven't already. + +### 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. Check out our [**Pull Request Guide**](./pull-requests/) for help with opening a pull request and going through the review process. -- cgit v1.2.3