diff options
| author |  Leon Sandøy <[email protected]> | 2021-04-25 21:25:10 +0200 |
|---|---|---|
| committer |  GitHub <[email protected]> | 2021-04-25 21:25:10 +0200 |
| commit | bd5f444e86cebb8d3928af0696a4a7b9c6a1a1fb (patch) | |
| tree | 0a98b8040f455a3279ab91cb8510f86fe6ec32d6 /pydis_site/apps | |
| parent | Merge pull request #468 from python-discord/content-app-improvements (diff) | |
| parent | Increase padding between text and images in lists. (diff) | |
Merge pull request #478 from python-discord/content-migration
Dewikification: Migrate site content to markdown.
Diffstat (limited to 'pydis_site/apps')
43 files changed, 3439 insertions, 3 deletions
diff --git a/pydis_site/apps/content/resources/code-of-conduct.md b/pydis_site/apps/content/resources/code-of-conduct.md new file mode 100644 index 00000000..6302438e --- /dev/null +++ b/pydis_site/apps/content/resources/code-of-conduct.md @@ -0,0 +1,100 @@ +--- +title: Python Discord Code of Conduct +description: The Code of Conduct for our community. +icon: fab fa-discord +--- + +# Code of Conduct + +We are committed to providing a friendly, safe and welcoming environment for all, regardless of level of experience, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, nationality, or other similar characteristic. + +##### Examples of behavior that contributes to creating a positive environment include: + +* Being kind and courteous to others +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Collaborating with other community members +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +##### Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and sexual attention or advances +* The use of inappropriate images, including in a community member's avatar +* The use of inappropriate language, including in a community member's nickname +* Any spamming, flaming, baiting or other attention-stealing behavior +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic address, without explicit permission +* Discussing topics that are overly polarizing, sensitive, or incite arguments. This includes the discussion of polarizing political views, violence, suicide, and rape. +* Responding with “RTFM”, "just google it” or similar phrases in response to help requests +* Other conduct which could reasonably be considered inappropriate + +### Our Goal + +The goal of this document is to set the overall tone for our community. +This isn’t an exhaustive list of things you can and can't do. +Rather, take this document in the spirit in which it’s intended, and try to be your best self. + +We value many things beyond technical expertise, including collaboration and supporting others within our community. +Providing a positive experience for other community members can have a much more significant impact than simply providing the correct answer. + +### Scope + +This Code of Conduct applies to all spaces managed by Python Discord. +This includes, but is not limited to, the Discord server, our repositories on GitHub, the YouTube-channel, and meet-ups. +In addition, violations of this code outside these spaces may affect a person's ability to participate within them. + +The Python Code of Conduct applies equally to all members of the community, including staff. + +--- + +# Code of Conduct Policies + +### Moderation Policy + +These are the policies for upholding our community’s rules and the code of conduct. +If you want to report a situation that needs to be reviewed by our moderation team, please see our [reporting guide](#reporting-guide). + +1. The [Python Discord Code of Conduct](#code-of-conduct) and the [Community Rules](/pages/rules) are enforced by the moderation team, which consists of users with the Moderators, Admins or Owners role on the Python Discord server. +2. Behavior that moderators find inappropriate, whether listed in the code of conduct, the community rules, or not, is also not allowed. +3. Complaints about moderation in-channel are not allowed. If a moderator takes an action or makes a decision you do not agree with, please send a Direct Message (DM) to ModMail from our Discord server. +4. If you disagree with a moderation action or decision taken against you, you may appeal the action or decision by following the [Appeal Procedure](#appeal-procedure). + +### Reporting Guide + +Instances of behaviors that violate the Python Discord Code of Conduct or rules may be reported by any member of the community. +Community members are encouraged to report these situations, including situations they witness involving other community members. + +You may report in the following ways: + +* By tagging the `@Moderators` role on the Discord server in situations that require immediate moderator attention. +* By sending a direct message (DM) to ModMail from our Discord server. +* By sending an email to [[email protected]](mailto:[email protected]) + +### Appeal Procedure + +If you wish to appeal a decision or action taken by the moderation team, you can do so in one of the following ways: + +* By sending an email to [[email protected]](mailto:[email protected]) +* By sending a direct message (DM) to ModMail from our Discord server. + +Please provide all relevant information in your appeal, including: + +* Your Discord username and id. +* The decision or action you are appealing. +* The reason for your appeal. + +Appeals will be discussed internally with the moderation team, but will be kept confidential otherwise. + +--- + +#### Attribution + +This Code of Conduct and parts of the policies are adapted from the [Adafruit Community Code of Conduct](https://github.com/adafruit/Adafruit_Community_Code_of_Conduct/blob/master/code-of-conduct.md), [Django Code of Conduct](https://www.djangoproject.com/conduct/), and the [Rust Code of Conduct](https://www.rust-lang.org/en-US/conduct.html). + +#### License + + +All content on this page is licensed under a [Creative Commons Attribution](https://creativecommons.org/licenses/by/3.0/) license. diff --git a/pydis_site/apps/content/resources/frequently-asked-questions.md b/pydis_site/apps/content/resources/frequently-asked-questions.md new file mode 100644 index 00000000..ed797532 --- /dev/null +++ b/pydis_site/apps/content/resources/frequently-asked-questions.md @@ -0,0 +1,131 @@ +--- +title: Frequently Asked Questions +description: The Python Discord FAQ. +icon: fab fa-discord +toc: 4 +--- + +Welcome to Python Discord! Sometimes in our channels we get similar questions asked every so often. +We've compiled the most frequently asked questions and provided our response to them. +This FAQ is aimed at answering questions about the Python Discord community. If you have question about Python, feel free to ask in `#python-general`. + +## Staff & Roles + +#### **Q: How do I get the helper role / become moderator / join staff?** + +There are no applications to be come a Helper, Moderator, Admin, or other staff role. +To become a Helper, which is our base staff role, people are nominated by a staff member and are later put up to a vote by Moderators, Admins, and Owners. +If the candidate received enough votes unanimously, then we offer them the Helper role. +This whole process takes place in channels only viewable to staff members. + +Being a Helper is not only about helping people with Python questions or helping with our projects, but is also about demonstrating an understanding of our community's culture. +To read more about what we look for in a Helper and to read about our internal staff roles (Moderators, Leads, Core Developer, Admin), check out [this page](/pages/server-info/roles/). + + +#### **Q: What is this role on the server?** + +We document the purposes of our most important roles on our website. Check it out [here](/pages/server-info/roles/). + +The roles that are not documented on that page are for seasonal events. These are specific to those events and don't impact permissions on the server. + + +#### **Q: What perks are there for nitro boosters? Can I keep the nitro role once the boost expires?** + +People who boost our server automatically get a bright cyan role color, but this is purely cosmetic and there aren't any other incentives to give us Nitro boosts. +Discord itself manages that specific role, so the role is automatically removed when the boost expires. + +Patrons who donate via [our Patreon](https://www.patreon.com/python_discord) also get a blue role and this is also a purely cosmetic role. +We do appreciate our Patreon supporters and our Nitro Boosters! + +We have received suggestions to give Nitro boosters non-cosmetic perks like a Nitro boosters lounge or the ability to use emoji reactions in certain channels, though that isn't something we will consider as we don't want to gate any part of the server behind a paywall. + + +#### **Q: I'd like to report inappropriate behavior on the server. How do I do that?** + +To report inappropriate or rule-breaking behaviour on the server, please send a direct message to our `@ModMail`. +You should find the ModMail bot at the top of the server member list. +If it's an urgent situation that needs immediate moderator attention, such as spam or NSFW content, then you can ping the `@Moderators` role in the server. + +## Questions about our bots + +#### **Q: Can I get Python bot on my server?** + +There isn't a way to invite `@Python` to other servers. +`@Python` is closely tied to our server architecture and wouldn't be able to properly function without a specific set-up. +If you are interested in `@Python` though, you can host your own instance of it. +The entire project is open source and can be found on [our github](https://github.com/python-discord/bot). + +#### **Q: What is the Zoot bot?** + +Zoot is an instance of [Metricity](https://github.com/python-discord/metricity). +It collects advanced metrics about the usage of the server. +Message content is not stored or collected. +You can view what data we collect in our [data privacy policy](/pages/privacy/). + + +#### **Q: Do any of the bots do X? Can I contribute to the bot?** + +We have two bots that provide functionality in our server: `@Python` and `@Sir Lancebot`. + +* `@Python` is the bot that helps manage certain server functionality (i.e. our help channel and moderation systems). +* `@Sir Lancebot` is our community bot that is designed as an entry level project for people to learn about open source contribution. +* `@Sir Lancebot` contains our fun and silly commands, like `.battleship`, `.BunnyNameGenerator`, `.http_status` which provides dog and cat HTTP status codes, and more! + +You can check out [`@Python` here on github](https://github.com/python-discord/bot), and check out [`@Sir Lancebot` here](https://github.com/python-discord/sir-lancebot). +If you have any questions about how to contribute, drop by the `#dev-contrib` channel in server. + +## Server Specific Questions + +#### **Q: Why are the help channels named after elements/food?** + +We want to keep the help channels uniquely named with it being somewhat easy to remember, so we decided on elements/food. `#help-1` doesn't work as well as `help-carbon` (`help-strawberry`). +If we had them numbered, they would quickly move out of order and possibly cause confusion for newer members. + + +#### **Q: Why can't I upload a specific file type?** + +The only file types that we allow on this server are those that Discord supports a native preview for. +This is because it's easier and safer for people on the server since they do not need to download a file to view it. +It's also to ease the burden on our moderators, otherwise they would have to download and check the files posted to the server. + +If you want to share code please use our hosted hastebin, [paste.pythondiscord.com](http://paste.pythondiscord.com). + + +#### **Q: Why is this permission not allowed in that channel?** + +Our general policy is to allow permissions unless proven that they are negatively affecting the channel. +If a certain channel doesn't have a permission, chances are it was allowed there at some point, but the cost of moderating or managing it outweighed the benefit. +Feel free to ask in `#community-meta` if you'd like the reasoning behind any specific decision. + + +#### **Q: Can we have a channel to show off projects or a channel to find people to work on projects with?** + +We previously had these channels, though they unfortunately did not work out the way we had hoped. +Engagement was low and they were a large burden on our moderators due to the number of low quality or rule violating posts. + +In general, a real-time chat client isn't the best avenue for showing off your projects or finding collaborators because messages are typically only seen by those actively engaged at the time they are posted. +You're welcome to showcase your projects in our off-topic channels or on a different platform like Reddit. + + +#### **Q: Can I make a recommendation about a specific feature in the server?** + +If you want to make a recommendation or suggestion about the server feel free to post in `#community-meta`. +You can also open an issue on our meta repo on GitHub, which can be found [here](https://github.com/python-discord/meta). + + +#### **Q: Why did the icon change?** + +While we love our blurple Python logo, we also enjoy celebrating other events throughout the year, like Advent of Code, Pride Month, Black History Month, Valentine's Day, Diwali, and more! In the spirit of those celebrations, we like to have some fun and change our icon instead. +If you're wondering why it's changed this time, check out `#changelog` on the server, as the reasoning for the recent change will be there. + +If you'd like to contribute and create a Python Discord server icon for us to use, check out [our branding repo](https://github.com/python-discord/branding) for what we currently have and talk to us in the `#media-branding` channel in the server. + +## Misc + +#### **Q: Can I interact with the data collected on the server?** + +Unfortunately we don't allow direct interaction with the metrics we collect on the server. +The data we do collect is used for moderation purposes, please see [our Privacy Policy](/pages/privacy/) on what data is collected and how we use it. +Legend has it that if you say "SQL" or "graphs" enough times, a `@joe` might appear and provide some graphs and run queries you might have in mind. + +We do have some public stats available to view here: [https://stats.pythondiscord.com/](https://stats.pythondiscord.com/) diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/asking-good-questions.md b/pydis_site/apps/content/resources/guides/pydis-guides/asking-good-questions.md new file mode 100644 index 00000000..971989a9 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/asking-good-questions.md @@ -0,0 +1,180 @@ +--- +title: Asking Good Questions +description: A guide for how to ask good questions in our community. +icon: fab fa-discord +toc: 3 +--- + +This document is intended to provide you with the information you need to get help as quickly and effectively as possible. +If you're stuck on a problem or you just don't understand something, you should always feel welcome to ask. + +# Before You Ask + +Before you ask your question, there are a few things you can do to find an answer on your own. +Experienced developers will do the following: + +* Read the official documentation for whatever you're working with +* Use a debugger to inspect your code +* Examine the traceback when your code raises an exception +* Do some research online - for example, on Stack Overflow +* Read the source code for whatever you're working with + +Essentially, doing your research is the first step towards a solution to any problem. +If your problem isn't extremely general, we're going to be doing exactly these steps ourselves when helping you, so doing the legwork beforehand saves everyone a lot of time. + +If none of the above steps help you or you're not sure how to do some of the above steps, feel free to ask us for help. + +# A Good Question + +When you're ready to ask a question, there's a few things you should have to hand before forming a query. + +* A code example that illustrates your problem +* If possible, make this a minimal example rather than an entire application +* Details on how you attempted to solve the problem on your own +* Full version information - for example, "Python 3.6.4 with `discord.py 1.0.0a`" +* The full traceback if your code raises an exception +* Do not curate the traceback as you may inadvertently exclude information crucial to solving your issue + +Your question should be informative, but to the point. +More importantly, how you phrase your question and how you address those that may help you is crucial. +Courtesy never hurts, and please type using correctly-spelled and grammatical language as far as you possibly can. + +When you're inspecting a problem, don't be quick to assume that you've found a bug, or that your approach is correct. +While it helps to detail what exactly you're trying to do, you should also be able to give us the bigger picture - describe the goal, not just the step. +Describe the problem's symptoms in chronological order - not your guesses as to their cause. + +| Bad Questions | Good Questions | +| ------------- | -------------- | +| Where can I find information on discord.py? | I used Google to try to find more information about "discord.py 1.0.0a", but I couldn't really find anything useful. Does anyone know where I might find a guide to writing commands using this library? | +| Pillow puts my text at the bottom of the image instead of where I wanted it. Why is it broken? | Pillow appears to insert text at the bottom of the image if the given X coordinate is negative. I had a look at the documentation and searched Stack Overflow, but I couldn't find any information on using negative coordinates to position text. Has anyone attempted this? | +| I'm having some trouble writing a YouTube random URL generator - can anyone help? | My YouTube random URL generator appears to be returning false positives for tested URLs, stating that a URL points to a real video when that video doesn't actually exist. Obviously there's some issue with how this is checked, but I can't put my finger on it. Is there anything I can check? | +| I was given this assignment by my teacher, but I'm not sure how to approach it. Does anyone have any ideas? | I have a list of numbers - how do I calculate how many of them are even? Is there a way to remove all the odd numbers from my list? Are there quick ways to find the average of a list of numbers, or add them all together? | + + +# What Not To Ask +--- + +#### Q: Can I ask a question? + +Yes. Always yes. Just ask. + +#### Q: Is anyone here good at Flask / Pygame / PyCharm? + +There are two problems with this question: + +1. This kind of question does not manage to pique anyone's interest, so you're less likely to get an answer overall. + On the other hand, a question like `"Is it possible to get PyCharm to automatically compile SCSS into CSS files"` is much more likely to be interesting to someone. + Sometimes, the best answers come from someone who does not already know the answer, but who finds the question interesting enough to go search for the answer on your behalf. +2. When you qualify your question by first asking if someone is good at something, you are filtering out potential answerers. + [Not only are people bad at judging their own skill at something](https://en.wikipedia.org/wiki/Dunning%E2%80%93Kruger_effect), but the truth is that even someone who has zero experience with the framework you're having trouble with might still be of excellent help to you. + +So instead of asking if someone is good at something, simply ask your question right away. + +#### Q: Can I use `str()` on a `discord.py` Channel object? + +Try it yourself and see. Experimentation is a great way to learn, and you'll save a lot of time by just trying things out. Don't be afraid of your computer! + +#### Q: My code doesn't work + +This isn't a question, and it provides absolutely no context or information. +Depending on the mood of the people that are around, you may even find yourself ignored. +Don't be offended by this - just try again with a better question. + +#### Q: Can anyone help me break into someone's Facebook account / write a virus / download videos from YouTube? + +We will absolutely not help you with hacking, pirating, or any other illegal activity. +A question like this is likely to be followed up with a ban if the person asking it doesn't back down quickly. + +#### Q: Can I send you a private message? + +Sure, but keep in mind that our staff members will not provide help via DMs. +We prefer that questions are answered in a public channel so lurkers can learn from them. + +#### Q: Can you help me over Teamviewer? + +No, sorry. + + +# Examining Tracebacks + +Usually, the first sign of trouble is that when you run your code, it raises an exception. +For beginning programmers, the traceback that's generated for the exception may feel overwhelming and discouraging at first. +However, in time, most developers start to appreciate the extensive information contained in the traceback as it helps them track down the error in their code. +So, don't panic and take a moment to carefully review the information provided to you. + +### Reading the Traceback + +```py +Traceback (most recent call last): + File "my_python_file.py", line 6, in <module> + spam = division(a=10, b=0) + File "my_python_file.py", line 2, in division + answer = a / b +ZeroDivisionError: division by zero +``` + +In general, the best strategy is to read the traceback from bottom to top. +As you can see in the example above, the last line of the traceback contains the actual exception that was raised by your code. +In this case, `ZeroDivisionError: division by zero`, clearly indicates the problem: We're trying to divide by zero somewhere in our code and that obviously can't be right. +However, while we now know which exception was raised, we still need to trace the exception back to the error in our code. + +To do so, we turn to the lines above the exception. +Reading from bottom to top again, we first encounter the line where the exception was raised: `answer = a / b`. +Directly above it, we can see that this line of code was `line 2` of the file `my_python_file.py` and that it's in the scope of the function `division`. +At this point, it's a good idea to inspect the code referenced here to see if we can spot an obvious mistake: + +```py +# Python Code +1| def division(a, b): +2| answer = a / b +3| return answer +``` + +Unfortunately, there's no obvious mistake in the code at this point, although one thing we do see here is that this function divides `a` by `b` and that the exception will only occur if `b` is somehow assigned the numeric value `0`. + +Keeping that observation in the back of our minds, we continue reading the traceback from bottom to top. The next thing we encounter is `spam = division(a=10, b=0)` from `line 6` of the file `my_python_file.py`. +In this case, `<module>` tells us that the code is in the global scope of that file. +While it's already clear from the traceback what's going wrong here, we're passing `b=0` to the function `division`, inspecting the code shows us the same: + +```python +5| spam = division(a=10, b=0) +6| print(spam) +``` + +We have now traced back the exception to a line of code calling the division function with a divisor of `0`. +Obviously, this is a simplified example, but the exact same steps apply to more complex situations as well. + +### The Error is Sometimes in the Line Before the Line in the Traceback + +Sometimes, the actual error is in the line just before the one referenced in the traceback. +This usually happens when we've inadvertently omitted a character meant to close an expression, like a brace, bracket, or parenthesis. +For instance, the following snippet of code will generate a traceback pointing at the line after the one in which we've missed the closing parenthesis: + +```python +# Python Code +1| print("Hello, world!" +2| print("This is my first Python program!") + +# Terminal output +Traceback (most recent call last): + File "my_python_file.py", line 2 + print("This is my first Python program!") + ^ +SyntaxError: invalid syntax +``` + +The reason this may happen is that Python allows for [implicit line continuation](https://docs.python.org/3/reference/lexical_analysis.html#implicit-line-joining) and will only notice the error when the expression does not continue as expected on the next line. +So, it's always a good idea to also check the line before the one mentioned in the traceback! + +### More Information on Exceptions + +Further information on exceptions can be found in the official Python documentation: + +* [The built-in exceptions page](https://docs.python.org/3/library/exceptions.html) lists all the built-in exceptions along with a short description of the exception. + If you're unsure of the meaning of an exception in your traceback, this is a good place to start. +* [The errors and exceptions chapter in the official tutorial ](https://docs.python.org/3/tutorial/errors.html) gives an overview of errors and exceptions in Python. + Besides explaining what exceptions are, it also explains how to handle expected exceptions graciously to keep your application from crashing when an expected exception is raised and how to define custom exceptions specific to your application. + +If you encounter an exception specific to an external module or package, it's usually a good idea to check the documentation of that package to see if the exception is documented. +Another option is to paste a part of the traceback, usually the last line, into your favorite search engine to see if anyone else has encountered a similar problem. +More often than not, you will be able to find a solution to your problem this way. diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/code-reviews-primer.md b/pydis_site/apps/content/resources/guides/pydis-guides/code-reviews-primer.md new file mode 100644 index 00000000..cde7d63e --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/code-reviews-primer.md @@ -0,0 +1,165 @@ +--- +title: "Code Reviews: A Primer" +description: An introduction and guide to the world of code reviews! +icon: fab fa-github +toc: 3 +--- + +## The What, the Why, and the How + +##### The What & The Why + +This is a guide that will cover the unsung hero of the coding process: code reviews. +Whether you're working professionally or on an open-source project on GitHub, you'll find that code reviews are an essential part of the process. + +So what exactly is a code review? The closest thing to compare it to is proofreading. +In proofreading, you look at an essay someone wrote and give suggestions on how things could be written better or point out mistakes that the writer may have missed. +Code reviewing is the same way. +You're given some code that someone wrote and see if you can find ways to improve it or point mistakes that the coder may have missed. + +"Hemlock", you might say, "Why should I care? Why would this be important?" The thing to remember is that coding is a team effort. +Code reviews help the programs we write to be the very best they can be. +We're all human, and mistakes are made, but through working together, we can correct those mistakes (as best we can) before they get merged into production. +Even if you're not the best coder in the world, you may spot things that even a professional programmer might miss! + +##### The How + +And now for the most important part of the guide. +This will detail the general process of how to write a code review, what to look for, how to do basic testing, and how to submit your review. +Big thanks to Akarys, who wrote this section of the guide! + +--- + +## Our Code Review Process + +> Note: Everything described in this guide is the writer's way of doing code reviews. +> This is purely informative; there's nothing wrong with branching off of this guide and creating your own method. +> We would even encourage you to do so! + +We usually do reviews in 3 steps: + +1. Analyze the issue(s) and the pull request (PR) +2. Analyze and review the code +3. Test the functionality + +So let's jump right into it! + +## Step 1: Analyzing the Issue(s) and the Pull Request + +Every issue and pull request has a reason for being. +While it's possible to do a code review without knowing that reason, it will make your life easier to get the full context of why it exists and what it's trying to do. +Let's take a look at how we can get that context. + +### Analyzing the Issue(s) + +In almost every case, the PR will have some linked issues. +On the right-hand side of the PR's page in GitHub, you'll see a section labeled "Linked issues". +Reading the issue(s) and their comments will allow you to know why certain decisions were made. +This will be invaluable when you review the implementation. +The author of the issue may suggest the code be written one way but the PR ends up writing it another. +This happens during the development process: New ideas are thought of, optimizations are found, other ideas are removed, etc. +Even if there are changes, functionality or fix that the issue covers should be covered by the PR. + +### Analyzing the PR + +The author of the PR will (or should) have made comments detailing how they implemented the code and whether it differs from the proposed implementation in the issue. +If they do things differently than suggested, they should also have explained why those changes were made. + +Remember that just like in the issue, PR comments have value. +Some of your future concerns about the implementation or even review comments may have already been discussed. +Although, if you disagree with the decision, feel free to comment about it! The more input we get from our reviewers, the better! +The last thing you need to remember is that commit messages are important. They're notes from the PR's author that give details as to what they changed. This can help you keep track of what change happened at what point in development, which can help you get some context about a given change. + +Now that you know more about the changes, let's start the fun stuff: the code review! + +## Step 2: Reviewing the Code Itself + +After all, that's why we're here! Let's dive right in! + +### The 1st Read: Getting a Sense of the Code + +It's impossible to understand the code in the PR your first time through. +Don't be surprised if you have to read over it a few times in order to get the whole picture. +When reading the code for the first time, we would recommend you to only try to get a sense of how the code flow. +What does this mean, you may ask? +Well, it is about knowing how every individual piece fits together to achieve the desired goal. + +Pay close attention to how the functions and classes are called. +Make sure to read the comments and docstrings; they'll help explain sections of the code that may be confusing. +Finally, remember that your goal at the moment is to get a general idea of how the code achieves its goal. +You don't have to understand the finer points at this stage. + +### The 2nd Read: Looking at Every Little Detail + +Now that you know how the code flows, you can take a closer look at the code. +Comment on anything you think could be done better. +This includes, but is not limited to: + +* The general structure of the code +* The variable names +* The algorithm(s) used +* The use or the lack of use of already existing code or a library +* Blocks of code that could benefit from comments +* Spelling +* Anything you see that doesn't seem quite right is worth commenting on. Discussing the things you find benefits everyone involved! + +Another good technique is to imagine how you would have implemented a specific functionality and compare it with the proposed implementation. +GitHub has a feature allowing you to mark files as read, and it's recommended to take advantage of it so that you don't lose your place if you take a break. +Now that you know what to comment on, let's take a closer look at how to comment. + +### Leaving Good Review Comments + +When leaving a comment, don't forget that we can't know what you're thinking; you have to write it down. +Your comment should describe why you think this should be changed and how you propose to change it. +Note that you can omit the latter in some cases if it is outside of your area of expertise for instance. +There's nothing wrong with using your comments to ask questions! If there's something you're not sure about, don't hesitate to ask in your comment. +It might indicate that the PR's author needs to add comments, change variable or function names, or even change a block of code entirely. + +GitHub has a handy feature that allows you to leave suggestions. +This means that the author can drop your suggestion into their PR with a click of a button. +If you provide one, great! It will speed up the review process even more! +On the opposite side, note that you aren't required to do all of that when leaving a comment. If you are fixing a typo, leaving a suggestion is enough. + +If you have concerns about a particular piece of code for example a race condition, it is totally okay to point it out in a comment, even if you don't have a suggested way to fix it. + +## Testing the Functionalities + +A code review isn't only about looking at the code; it's also about testing it. +Always try to make sure that the code is working properly before approving the changes. + +Something else to note: you are free to review code without testing functionality. +That's totally okay! Just make sure to mention when you submit your review. + +### Reviewing the Functionality + +When reviewing functionality, keep asking yourself how you would have designed it and then compare your idea with the implementation. +Note that you are allowed to give suggestions about how the functionality should be designed. + +Start with the basic usages and work your way up to more complicated ones. +Verify that everything is working as intended. +If it isn't, leave a comment giving what you've done, what should have happened, and what actually happened, along with any potential logs or errors you could have. +If you like, you can even try to pinpoint the issue and find a fix for it. We would be very grateful if you did! + +### Objective: Break it + +Good functionality should be able to handle edge cases. +Try to throw every edge case you might think of and see how it responds. This might not be needed in some cases, but it's essential for security-related work. +If the implementation has a security breach, you should absolutely find it! Just like in the previous section, if you find something and comment on it, great! +If you manage to find a way to fix it and suggest the fix, even better! + +### But what if the Project doesn't even start? + +This is a tricky one. Sometimes the project won't even start, keeping you from testing it all together. + +In this case, you should try to investigate if it is failing because of an error in the code. If it ends up being because of the functionality, you should comment on that. + +If you aren't sure why it isn't starting, feel free to ask us! + +## Final Words + +You did it! +You are now ready to take on the wild world of code reviewing! +We know that process can seem long, tedious, and not feel like a necessary task, but it is! +We are very grateful to you for reading through this and for your potential future code reviews. +We couldn't move forward without you. +Thank you! diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md new file mode 100644 index 00000000..f8baa354 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing.md @@ -0,0 +1,115 @@ +--- +title: Contributing +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: + +<!-- Project cards --> +<div class="columns is-multiline is-centered is-3 is-variable"> + <div class="column is-one-third-desktop is-half-tablet"> + <div class="card github-card"> + <div class="card-header"> + <div class="card-header-title is-centered"> + <a class="is-size-5" href="https://github.com/python-discord/sir-lancebot"> + <i class="fab fa-github"></i> <strong >Sir Lancebot</strong> + </a> + </div> + </div> + <div class="card-content"> + <div class="content"> + Our community-driven Discord bot. + </div> + <div class="tags has-addons"> + <span class="tag is-dark">Difficulty</span> + <span class="tag is-primary">Beginner</span> + </div> + </div> + <div class="card-footer"> + <a href="https://github.com/python-discord/sir-lancebot/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc" class="card-footer-item"><i class="far fa-exclamation-circle"></i> Issues</a> + <a href="https://github.com/python-discord/sir-lancebot/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc" class="card-footer-item"><i class="fas fa-code-merge"></i> PRs</a> + </div> + <div class="card-footer"> + <a href="/pages/guides/pydis-guides/contributing/sir-lancebot" class="card-footer-item"><i class="fas fa-cogs"></i> Setup and Configuration Guide</a> + </div> + </div> + </div> + <div class="column is-one-third-desktop is-half-tablet"> + <div class="card github-card"> + <div class="card-header"> + <div class="card-header-title is-centered"> + <a href="https://github.com/python-discord/bot"> + <strong class="is-size-5"><i class="fab fa-github"></i> Bot</strong> + </a> + </div> + </div> + <div class="card-content"> + <div class="content"> + The community and moderation Discord bot. + </div> + <div class="tags has-addons"> + <span class="tag is-dark">Difficulty</span> + <span class="tag is-warning">Intermediate</span> + </div> + </div> + <div class="card-footer"> + <a href="https://github.com/python-discord/bot/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc" class="card-footer-item"><i class="far fa-exclamation-circle"></i> Issues</a> + <a href="https://github.com/python-discord/bot/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc" class="card-footer-item"><i class="fas fa-code-merge"></i> PRs</a> + </div> + <div class="card-footer"> + <a href="/pages/guides/pydis-guides/contributing/bot" class="card-footer-item"><i class="fas fa-cogs"></i> Setup and Configuration Guide</a> + </div> + </div> + </div> + <div class="column is-one-third-desktop is-half-tablet"> + <div class="card github-card"> + <div class="card-header"> + <div class="card-header-title is-centered"> + <a href="https://github.com/python-discord/site"> + <strong class="is-size-5"><i class="fab fa-github"></i> Site</strong> + </a> + </div> + </div> + <div class="card-content"> + <div class="content"> + The website, subdomains and API. + </div> + <div class="tags has-addons"> + <span class="tag is-dark">Difficulty</span> + <span class="tag is-danger">Advanced</span> + </div> + </div> + <div class="card-footer"> + <a href="https://github.com/python-discord/site/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc" class="card-footer-item"><i class="far fa-exclamation-circle"></i> Issues</a> + <a href="https://github.com/python-discord/site/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc" class="card-footer-item"><i class="fas fa-code-merge"></i> PRs</a> + </div> + <div class="card-footer"> + <a href="/pages/guides/pydis-guides/contributing/site" class="card-footer-item"><i class="fas fa-cogs"></i> Setup and Configuration Guide</a> + </div> + </div> + </div> +</div> + +If you don't understand anything or need clarification, feel free to ask any staff member with the **@PyDis Core Developers** role in the server. We're always happy to help! + +### Useful Resources + +[Style Guide](./style-guide/) - Information regarding the code styles you should follow when working on our projects.<br> +[Review Guide](../code-reviews-primer/) - A guide to get you started on doing code reviews. + +## 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. diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/_info.yml b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/_info.yml new file mode 100644 index 00000000..4a338463 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/_info.yml @@ -0,0 +1,3 @@ +title: Contributing +description: How to contribute to our open source projects on Github. +icon: fab fa-github 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 new file mode 100644 index 00000000..a48b7300 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/bot.md @@ -0,0 +1,209 @@ +--- +title: Contributing to Bot +description: A guide to setting up and configuring Bot. +icon: fab fa-github +toc: 1 +--- + +# Requirements +* [Python 3.8](https://www.python.org/downloads/) +* [Pipenv](https://github.com/pypa/pipenv#installation) + * `pip install pipenv` +* [Git](https://git-scm.com/downloads) + * [Windows](https://git-scm.com/download/win) + * [MacOS](https://git-scm.com/download/mac) or `brew install git` + * [Linux](https://git-scm.com/download/linux) +* A running webserver for the [site](../site) + * Follow the linked guide only if you don't want to use Docker or if you plan to do development on the site project too. + +## Using Docker + +Both the site and the bot can be started using Docker. +Using Docker is generally recommended (but not strictly required) because it abstracts away some additional set up work, especially for the site. +However, if you plan to attach a debugger to either the site or the bot, run the respective project directly on your system (AKA the _host_) instead. + +The requirements for Docker are: + +* [Docker CE](https://docs.docker.com/install/) +* [Docker Compose](https://docs.docker.com/compose/install/) (This already comes bundled on macOS and Windows, so you shouldn't need to install it) + * `pip install docker-compose` + +--- +# 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 staff member, 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 +1. [Clone your fork to a local project directory](../cloning-repository/) +2. [Install the project's dependencies](../installing-project-dependencies/) +3. [Prepare your hosts file (Optional)](../hosts-file/) + +--- +# Test server and bot account +You will need your own test server and bot account on Discord to test your changes to the bot. + +* [**Create a test server**](../setting-test-server-and-bot-account#setting-up-a-test-server) +* [**Create a bot account**](../setting-test-server-and-bot-account#setting-up-a-bot-account) +* Invite it to the server you just created. + +### Privileged Intents + +With `discord.py` 1.5 and later, it is now necessary to explicitly request that your Discord bot receives certain gateway events. +The Python bot requires the `Server Member Intent` to function. +In order to enable it, visit the [Developer Portal](https://discord.com/developers/applications/) (from where you copied your bot's login token) and scroll down to the `Privileged Gateway Intents` section. +The `Presence Intent` is not necessary and can be left disabled. + +If your bot fails to start with a `PrivilegedIntentsRequired` exception, this indicates that the required intent was not enabled. + +### Server Setup + +Setup categories, channels, emojis, roles, and webhooks in your server. To see what needs to be added, please refer to the following sections in the `config-default.yml` file: + +* `style.emojis` +* `guild.categories` +* `guild.channels` +* `guild.roles` +* `guild.webhooks` + +We understand this is tedious and are working on a better solution for setting up test servers. +In the meantime, [here](https://discord.new/zmHtscpYN9E3) is a template for you to use.<br> + +--- +# Configure the bot +You will need to copy IDs of the test Discord server, as well as the created channels and roles to paste in the config file. +If you're not sure how to do this, [check out the information over here.](../setting-test-server-and-bot-account#obtain-the-ids) + +1. Create a copy of `config-default.yml` named `config.yml` in the same directory. +2. Set `guild.id` to your test servers's ID. +3. Change the IDs in the [sections](#server-setup) mentioned earlier to match the ones in your test server. +4. Set `urls.site_schema` and `urls.site_api_schema` to `"http://"`. +5. Set `urls.site`: + - If running the webserver in Docker, set it to `"web:8000"`. + - If the site container is running separately (i.e. started from a clone of the site repository), then [COMPOSE_PROJECT_NAME](../docker/#compose-project-names) has to be set to use this domain. If you choose not to set it, the domain in the following step can be used instead. + - If running the webserver locally and the hosts file has been configured, set it to `"pythondiscord.local:8000"`. + - Otherwise, use whatever domain corresponds to the server where the site is being hosted. +6. Set `urls.site_api` to whatever value you assigned to `urls.site` with `api` prefixed to it, for example if you set `urls.site` to `web:8000` then set `urls.site_api` to `api.web:8000`. +7. Setup the environment variables listed in the section below. + +### Environment variables + +These contain various settings used by the bot. +To learn how to set environment variables, read [this page](../configure-environment-variables) first. + +The following is a list of all available environment variables used by the bot: + +| Variable | Required | Description | +| -------- | -------- | -------- | +| `BOT_TOKEN` | Always | Your Discord bot account's token (see [Test server and bot account](#test-server-and-bot-account)). | +| `BOT_API_KEY` | When running bot without Docker | Used to authenticate with the site's API. When using Docker to run the bot, this is automatically set. By default, the site will always have the API key shown in the example below. | +| `REDDIT_CLIENT_ID` | reddit cog | OAuth2 client ID for authenticating with the [reddit API](https://github.com/reddit-archive/reddit/wiki/OAuth2). | +| `REDDIT_SECRET` | reddit cog | OAuth2 secret for authenticating with the reddit API. *Leave empty if you're not using the reddit API.* | +| `BOT_SENTRY_DSN` | When connecting the bot to sentry | The DSN of the sentry monitor. | +| `REDIS_PASSWORD` | When not using FakeRedis | The password to connect to the redis database. *Leave empty if you're not using REDIS.* | + +--- + +If you are running on the host, while not required, we advise you set `use_fakeredis` to `true` in the config file during development to avoid the need of setting up a Redis server. +It does mean you may lose persistent data on restart but this is non-critical. +Otherwise, you should set up a Redis instance and fill in the necessary config. +{: .notification .is-warning } + +--- + +Example `.env` file: + +```shell +BOT_TOKEN=YourDiscordBotTokenHere +BOT_API_KEY=badbot13m0n8f570f942013fc818f234916ca531 +REDDIT_CLIENT_ID=YourRedditClientIDHere +REDDIT_SECRET=YourRedditSecretHere +``` + +--- +# Run the project + +The bot can run with or without Docker. +When using Docker, the site, which is a prerequisite, can be automatically set up too. +If you don't use Docker, you have to first follow [the site guide](../site/) to set it up yourself. +The bot and site can be started using independent methods. +For example, the site could run with Docker and the bot could run directly on your system (AKA the _host_) or vice versa. + +## Run with Docker + +The following sections describe how to start either the site, bot, or both using Docker. +If you are not interested in using Docker, see [this page](../site/) for setting up the site and [this section](#run-on-the-host) for running the bot. + +If you get any Docker related errors, reference the [Possible Issues](../docker#possible-issues) section of the Docker page. + +### Site and bot + +This method will start both the site and the bot using Docker. + +Start the containers using Docker Compose while inside the root of the project directory: + +```shell +docker-compose up +``` + +The `-d` option can be appended to the command to run in detached mode. +This runs the containers in the background so the current terminal session is available for use with other things. + +### Site only + +This method will start only the site using Docker. + +```shell +docker-compose up site +``` + +See [this section](#run-on-the-host) for how to start the bot on the host. + +### Bot only + +This method will start only the bot using Docker. +The site has to have been started somehow beforehand. + +Start the bot using Docker Compose while inside the root of the project directory: + +```shell +docker-compose up --no-deps bot +``` + +## Run on the host + +Running on the host is particularly useful if you wish to debug the bot. +The site has to have been started somehow beforehand. + +```shell +pipenv run 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](../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. +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/) + +## Adding new statistics + +Details on how to add new statistics can be found on the [statistic infrastructure page](https://blog.pythondiscord.com/statistics-infrastructure). +We are always open to more statistics so add as many as you can! + +## Running tests + +[This section](https://github.com/python-discord/bot/blob/main/tests/README.md#tools) of the README in the `tests` repository will explain how to run tests. +The whole document explains how unittesting works, and how it fits in the context of our project. + +Have fun! diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/cloning-repository.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/cloning-repository.md new file mode 100644 index 00000000..fad54374 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/cloning-repository.md @@ -0,0 +1,31 @@ +--- +title: Cloning a Repository +description: A guide to cloning git repositories. +icon: fab fa-github +--- + +> **Note:** The process varies depending on your choice of code editor / IDE, so refer to one of the following guides: + +- [Cloning with PyCharm](#cloning-with-pycharm) +- [Cloning with the command line](#cloning-with-the-command-line) + +The following will use the [Sir-Lancebot](https://github.com/python-discord/sir-lancebot/) repository as an example, but the steps are the same for all other repositories. You should have already retrieved your fork's Git URL as described in [**Creating a Fork**](../forking-repository). + +--- + +## Cloning with PyCharm +1. Load up PyCharm and click `Get from VCS`.<br> + +2. Enter the URL of your forked repository. +3. Change the directory if you desire and click `Clone`.<br> + + +--- + +## Cloning with the command line +1. Clone your forked repository using `git clone` followed by your fork's Git URL. Then, change your working directory to the repository. +```shell +$ git clone https://github.com/<your username>/sir-lancebot +... +$ cd sir-lancebot +``` diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/configure-environment-variables.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/configure-environment-variables.md new file mode 100644 index 00000000..8b8e3f95 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/configure-environment-variables.md @@ -0,0 +1,23 @@ +--- +title: Configure Environment Variables +description: A guide to configuring environment variables. +icon: fas fa-cog +--- + +1. Create a text file named **.env** in your project root (that's the base folder of your repository): + * Unix/Git Bash: `touch /path/to/project/.env` + * Windows CMD: `type nul > \path\to\project\.env` (The error *The system cannot find the file specified* can be safely ignored.) +> **Note:** The entire file name is literally `.env` +2. Open the file with any text editor. +3. Each environment variable is on its own line, with the variable and the value separated by a `=` sign. + +Example: + +* Set the environment variable `SEASONALBOT_DEBUG` to `True`: +``` +SEASONALBOT_DEBUG=True +``` +* Set the environment variable `CHANNEL_ANNOUNCEMENTS` to `12345`: +``` +CHANNEL_ANNOUNCEMENTS=12345 +``` 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 new file mode 100644 index 00000000..aa784a50 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines.md @@ -0,0 +1,30 @@ +--- +title: Contributing Guidelines +description: Guidelines to adhere to when contributing to our projects. +--- + +Thank you for your interest in our projects! + +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-precommit) such as `precommit` or `black` can make this easier. +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). +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.** +Whenever the assets are images, audio or even code, they must have a license compatible with our projects. +5. **Follow the [Python Discord Code of Conduct](https://pydis.com/coc).** +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! diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines/_info.yml b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines/_info.yml new file mode 100644 index 00000000..80c8e772 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines/_info.yml @@ -0,0 +1,2 @@ +title: Contributing Guidelines +description: Guidelines to adhere to when contributing to our projects. 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 new file mode 100644 index 00000000..78a27173 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/contributing-guidelines/supplemental-information.md @@ -0,0 +1,97 @@ +--- +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 Precommit + +On most of our projects, we use `flake8` and `precommit` 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. + +`precommit` 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, it is either `pipenv run [lint | precommit]` or `poetry run [lint | precommit]`. + +## 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](http://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/docker.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/docker.md new file mode 100644 index 00000000..63be9f3e --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/docker.md @@ -0,0 +1,120 @@ +--- +title: Working with Docker & Docker Compose +description: Guide to running our projects with Docker and Docker CE. +icon: fab fa-docker +toc: 2 +--- + +Both our [Site](../site/) and [Bot](../bot/) projects use Docker and Docker-Compose during development in order to provide an easy to setup and consistent development environment. + +Consider reading some of the following topics if you're interested in learning more about Docker itself: + + * [**What is Docker?**](https://docs.docker.com/engine/docker-overview/) + * [**How can I learn to use it for my own stuff?**](https://docs.docker.com/get-started/) + * [**What about Docker Compose, what's it for?**](https://docs.docker.com/compose/) + +# Docker Installation +You can find installation guides available for your respective OS from the official Docker documentation: +[https://docs.docker.com/install/](https://docs.docker.com/install/) + +## After Installing on Linux +If you're on Linux, there's a few extra things you should do: + +1. [**Add your user to the `docker` user group so you don't have to use `sudo` when running docker or docker-compose.**](#add-user-group) +2. [**Start up the Docker service.**](#run-the-service) +3. [**Set the Docker service to start on boot.**](#start-on-boot) **(optional)** + +### Run the Service +Most linux distributions **systemd**, you can start the service with: +```shell +$ sudo systemctl start docker +``` + +### Add User Group +```shell +$ sudo groupadd docker +$ sudo usermod -aG docker $USER +``` +Log out and log back in to ensure your group changes work. + +### Start on Boot +```shell +$ sudo systemctl enable docker +``` + +# Possible Issues +### Couldn't connect to Docker daemon +```shell +ERROR: Couldn't connect to Docker daemon at http+docker://localhost - is it running? +``` +**Problem**<br> +Your Docker service is either not started, or you haven't yet installed Docker. + +**Solution**<br> +[Start the service](#run-the-service) or ensure it's installed. +If it's not, [install it](#docker-installation). + +### Error loading config file +```plaintext +WARNING: Error loading config file: /home/user/.docker/config.json - +stat /home/user/.docker/config.json: permission denied +``` +**Problem**<br> +You initially ran Docker using `sudo` before adding your user to the `docker` group, resulting in your `~/.docker/` directory being created with incorrect permissions. + +**Solution**<br> +Remove the existing `~/.docker/` directory. It will be automatically re-created with the correct permissions. + +### Drive has not been shared (Windows users) + +When attempting to run the `docker-compose up` command on a Windows machine, you receive the following or similar error message: +```text +ERROR: for bot_bot_1 Cannot create container for service bot: b'Drive has not been shared' +``` +**Problem**<br> +Windows has not been configured to share drives with Docker. + +**Solution**<br> +> NOTE: Solution requires Windows user credentials for an account that has administrative privileges. + +1. Right-click the Docker icon in the Windows system tray, and choose "Settings" from the context menu.<br> + + +2. Click the "Shared Drives" label at the left, and check the box next to the drive letter where your project is stored.<br> + + +3. Click "Apply" and enter appropriate Windows credentials (likely just your own account, if you have administrative privileges). + +4. Re-run the `docker-compose up` command. + +# Compose Project Names +When you launch services from a docker-compose, you'll notice the name of the containers aren't just the service name. +You'll see this when launching your compose, as well as being able to be seen in the command `docker-compose ps` which will list the containers. +It should match something like this: +``` +site_site_1 +``` +This matched the following container name format: +``` +projectname_servicename_1 +``` +By default, your project name will match the name of the folder your project is inside in all lowercase. + +You can specify a custom project name by adding a `COMPOSE_PROJECT_NAME` variable to your `.env` file before launching the compose: +``` +COMPOSE_PROJECT_NAME=site +``` +Containers with the same project name end up connected to the same network by default. +For example, the `site` container connects with `postgres` via the matching hostname inside the container. +Even if you didn't expose a port to the host, the two containers would be able to talk to each other. + +You can have two different projects able to communicate in the same way by having them use the same project name. +We use this feature to allow the `bot` container to communicate with a separate local copy of `site` that may need to be tested during development. + +By default, the `bot` container could launch with a name of `bot_bot_1` and the `site` container with a name of `site_site_1`. Since the prefixes are different, they're in distinct projects, so can't talk with each other. + +If we got to the bot's `.env` file, and add the line below, we can set `bot` to run in the same project as `site`: +``` +COMPOSE_PROJECT_NAME=site +``` +Now they can talk to each other! diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/forking-repository.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/forking-repository.md new file mode 100644 index 00000000..07535dbe --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/forking-repository.md @@ -0,0 +1,18 @@ +--- +title: Forking a Repository +description: A guide to forking git repositories. +icon: fab fa-github +--- + +Before contributing to any project, you will have to fork the project, ie. create your own online copy of the project. +The following will use the [Sir-Lancebot](https://github.com/python-discord/sir-lancebot/) repository as an example, but the steps are the same for all other repositories. + +1. Navigate to the repository page and press the `Fork` button at the top of the page. + +2. Fork it to your account.<br> + +3. Later, you will need the Git URL of your forked repository in order to clone it. +In your newly forked repository, copy the Git URL by clicking the green `Code` button, then click the Copy Link button. + + +> If you have SSH set up with GitHub, you may instead click the `SSH` button above the Copy Link button to get the SSH URL. diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/hosts-file.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/hosts-file.md new file mode 100644 index 00000000..5d55a7f3 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/hosts-file.md @@ -0,0 +1,46 @@ +--- +title: Preparing Your Hosts file +description: How to setup your hosts file for project usage. +icon: fas fa-cog +toc: 3 +--- + +# What's a hosts file? +The hosts file maps a hostname/domain to an IP address, allowing you to visit a given domain on your browser and have it resolve by your system to the given IP address, even if it's pointed back to your own system or network. + +When staging a local [Site](https://pythondiscord.com/pages/contributing/site/) project, you will need to add some entries to your hosts file so you can visit the site with the domain `http://pythondiscord.local` + +# What to add +You would add the following entries to your hosts file. + +```plaintext +127.0.0.1 pythondiscord.local +127.0.0.1 api.pythondiscord.local +127.0.0.1 staff.pythondiscord.local +127.0.0.1 admin.pythondiscord.local +``` + +# How to add it + +### Linux +1. Run `sudo nano /etc/hosts` +2. Enter your user password. +3. Add the new content at the bottom of the file. +4. Use `CTRL+X` +5. Enter `y` to save. + +_This covers most linux distributions that come with `nano`, however you're welcome to use whatever CLI text editor you're comfortable with instead._ + +### Windows +1. Open Notepad as Administrator. +2. Open the file `C:\Windows\System32\Drivers\etc\hosts` +3. Add the new content at the bottom of the file. +4. Save. + +### MacOS +1. Run `sudo nano /private/etc/hosts` in Terminal. +2. Enter your user password. +3. Add the new content at the bottom of the file. +4. Use `CTRL+X` +5. Enter `y` to save. +6. Flush your DNS by running `dscacheutil -flushcache` diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/installing-project-dependencies.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/installing-project-dependencies.md new file mode 100644 index 00000000..4432236e --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/installing-project-dependencies.md @@ -0,0 +1,38 @@ +--- +title: Installing Project Dependencies +description: A guide to installing the dependencies of our projects. +icon: fab fa-python +--- + +> **Note:** The process varies depending on your choice of code editor / IDE, so refer to one of the following guides: + +- [Installing dependencies with PyCharm](#installing-dependencies-with-pycharm) +- [Installing dependencies with the command line](#installing-dependencies-with-the-command-line) + +The following will use the [Sir-Lancebot](https://github.com/python-discord/sir-lancebot/) repository as an example, but the steps are the same for all other repositories. +You should have already cloned your fork as described in [**Cloning a Repository**](../cloning-repository). + +--- + +## Installing dependencies with PyCharm +1. Load up your project in PyCharm. +2. Go to the Project Settings by clicking `File`, then `Settings...`. Alternatively, use the shortcut key `Ctrl+Alt+S`. +3. Navigate to `Project Interpreter`, then click the gear icon and click `Add`. + +4. In the popup window, click `Pipenv Environment`, make sure `Install packages from Pipfile` is checked, then click `OK`. + +5. PyCharm will automatically install the packages required into a virtual environment. + + +--- + +## Installing dependencies with the command line +1. Make sure you are in the project directory. +2. Install project and development dependencies: +```shell +$ pipenv sync --dev +``` +* Remember to also set up pre-commit hooks to ensure your pushed commits will never fail linting: +```shell +$ pipenv run precommit +``` diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/issues.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/issues.md new file mode 100644 index 00000000..9151e5e3 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/issues.md @@ -0,0 +1,121 @@ +--- +title: Issues +description: Guide to Github issues. +icon: fab fa-github +--- + +## What are Issues? + +Issues are tickets that allow us to manage all the suggested features, bugs noticed and discussions about a project. + +An Issue ticket should have a simple, easy to understand title and a clearly written description outlining any of the available details. +Once an Issue is created, people can comment on it and if work is to be actioned due to it, it can be assigned to a contributor so others know that it's being worked on already. + +## How do I make an Issue? + +**Before making an Issue, search the existing ones!** +Often, an Issue ticket already exists within the scope of what you might be considering, so be sure to do a search beforehand and if there it, add any new information or suggestions to the comments on the existing Issue instead, or just add a thumbs up if you agree with it. + +If you don't see one existing, then: + +1. Click the `Issues` tab in a repository:<br> + + +2. Click `New Issue`:<br> + + +3. Enter the title and description for your issue, then click `Submit new issue`:<br> +{: width="600" } + +## What should I put as a title? + +A good title is short and to the point as to what the Issue is about. + +Avoid some of the following: + +- Writing a long title +- Being too vague +- Using informal language +- Using languages other than English + +## What makes a good description? + +A good description is well structured and contains all the information available to you at the time of creating it. If additional information comes to light, it can either be added in edits to the description afterwards, or as part of comments. + +Try to avoid: + +- Masses of unstructured blocks of never ending text +- Including unnecessary details that aren't constructive to the discussion + +Definitely try to: + +- Include relevant images in the description if it involves visual aspects +- Make use of [Github's markdown syntax](https://help.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax) for text formatting + +## What are labels? + +Labels allow us to better organise Issues by letting us view what type of Issue it is, how it might impact the codebase and at what stage it's at. + +In our repositories, we try to prefix labels belonging to the same group, for example the label groups `status` or `type`. We will be trying to keep to the same general structure across our project repositories, but just have a look at the full lables list in the respective repository to get a clear idea what's available. + +If you're a contributor, you can add relevant labels yourself to any new Issue ticket you create. + +### General label groups + +These label groups should be present on most of our main project repositories and can serve as a guide as to how they're used. + +#### area +Signifies what section of the project/codebase the Issue is focusing on addressing or discussing. Only one area should be selected usually, as the most focused area should be the selected one. Exceptions exist for Issues that impact multiple areas equally, but are generally not the norm. + +#### priority +How urgent the Issue should be addressed: + +- `critical` - Super important, likely a bug that's impacting the project severely at this moment. +- `high` - Important, impacts the project heavily and/or is time sensitive. +- `normal` - Would be convenient if it's addressed. +- `low` - Doesn't require us to look at any time soon. + +#### status +Where this issue is at currently: + +- `deferred` - Is being put off until a later date +- `planning` - The Issue is being discussed, implementation is not decided or ready to begin. +- `stale` - Hasn't been addressed or contributed to in a long time. Worth reconsidering as worth keeping open or bumped in priority if it needs to be done to get it out. +- `stalled` - Something else has prevented this Issue from moving forward for now. +- `WIP` - The issue is actively being worked on by someone already. + +#### type +What's the purpose of the Issue: + +- `bug` - Addresses a bug in the code +- `enhancement` - Changes or improves on an existing feature. +- `feature` - Addresses a possible new feature. +- `question` - Isn't addressing any code changes, only a discussion or clarification. + +#### Non-group labels +There are 4 labels that aren't in groups as they are globally recognised and shouldn't be renamed: + +- `duplicate` - Marks the Issue as being the same or within scope of an existing one +- `good first issue` - Marks the Issue as being suitable to work on by beginners +- `help wanted` - More people are needed to work on this Issue +- `invalid` - Marks the Issue as not being a proper Issue. + +## Assignments + +Once an Issue is not in the planning/discussing stage and is approved to be worked on, it can be assigned to someone interested in it. + +### Can I assign myself? + +Only staff can assign themselves to a ticket. +If a general contributor assigns themself, they'll be unassigned. + +### How do I get assigned? + +**First check that someone else isn't already assigned.** + +Once you're sure it's available and ready to be worked on, you can leave a comment in the Issue ticket. +Generally, it's first-come first served, so a staff member will usually assign you within the day if they confirm it's clear to do so. + +#### Do I get first preference to work on it if I made the Issue ticket? +As long as you say you'd like to work on it within the description of your ticket or be the first to request so in a comment. +If you forget to say so and someone else asks to be assigned, we aren't likely to unassign them afterwards, so it's entirely up to the discretion of the other person in that case. diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/setting-test-server-and-bot-account.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/setting-test-server-and-bot-account.md new file mode 100644 index 00000000..c14fe50d --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/setting-test-server-and-bot-account.md @@ -0,0 +1,68 @@ +--- +title: Setting Up a Test Server and Bot Account +description: How to get started with testing our bots. +icon: fab fa-discord +--- + +## Setting up a Test Server + +1. Create a Discord Server if you haven't got one already to use for testing. + +--- + +## Setting up a Bot Account + +1. Go to the [Discord Developers Portal](https://discordapp.com/developers/applications/). +2. Click on the `New Application` button, enter your desired bot name, and click `Create`. +3. In your new application, go to the `Bot` tab, click `Add Bot`, and confirm `Yes, do it!` +4. Change your bot's `Public Bot` setting off so only you can invite it, save, and then get your **Bot Token** with the `Copy` button. +> **Note:** **DO NOT** post your bot token anywhere public, or it can and will be compromised. +5. Save your **Bot Token** somewhere safe to use in the project settings later. +6. In the `General Information` tab, grab the **Client ID**. +7. Replace `<CLIENT_ID_HERE>` in the following URL and visit it in the browser to invite your bot to your new test server. +```plaintext +https://discordapp.com/api/oauth2/authorize?client_id=<CLIENT_ID_HERE>&permissions=8&scope=bot +``` +Optionally, you can generate your own invite url in the `OAuth` tab, after selecting `bot` as the scope. + +--- + +## Obtain the IDs + +First, enable developer mode in your client so you can easily copy IDs. + +1. Go to your `User Settings` and click on the `Appearance` tab. +2. Under `Advanced`, enable `Developer Mode`. + +#### Guild ID + +Right click the server icon and click `Copy ID`. + +#### Channel ID + +Right click a channel name and click `Copy ID`. + +#### Role ID + +Right click a role and click `Copy ID`. +The easiest way to do this is by going to the role list in the guild's settings. + +#### Emoji ID + +Insert the emoji into the Discord text box, then add a backslash `\` right before the emoji and send the message. +The result should be similar to the following + +```plaintext +<:bbmessage:511950877733552138> +``` + +The long number you see, in this case `511950877733552138`, is the emoji's ID. + +#### Webhook ID + +Once a [webhook](https://support.discordapp.com/hc/en-us/articles/228383668-Intro-to-Webhooks) is created, the ID is found in the penultimate part of the URL. +For example, in the following URL, `661995360146817053` is the ID of the webhook. + +```plaintext +https://discordapp.com/api/webhooks/661995360146817053/t-9mI2VehOGcPuPS_F8R-6mB258Ob6K7ifhtoxerCvWyM9VEQug-anUr4hCHzdbhzfbz +``` 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 new file mode 100644 index 00000000..4ff98095 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/sir-lancebot.md @@ -0,0 +1,119 @@ +--- +title: Contributing to Sir Lancebot +description: A guide to setting up and configuring Sir Lancebot. +icon: fab fa-github +toc: 1 +--- + +> Before contributing, please ensure you read the [contributing guidelines](../contributing-guidelines) in full. + +--- +# Requirements +- [Python 3.8](https://www.python.org/downloads/) +- [Pipenv](https://github.com/pypa/pipenv/blob/master/docs/install.rst#-installing-pipenv) +- [Git](https://git-scm.com/downloads) + - [Windows Installer](https://git-scm.com/download/win) + - [MacOS Installer](https://git-scm.com/download/mac) or `brew install git` + - [Linux](https://git-scm.com/download/linux) + +## Using Docker +Sir Lancebot can be started using Docker. Using Docker is generally recommended (but not strictly required) because it abstracts away some additional set up work. + +The requirements for Docker are: + +* [Docker CE](https://docs.docker.com/install/) +* [Docker Compose](https://docs.docker.com/compose/install/) + * `pip install docker-compose` + * 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) + +--- +# Test Server and Bot Account + +You will need your own test server and bot account on Discord to test your changes to the bot. + +1. [**Create a test server**](../setting-test-server-and-bot-account#setting-up-a-test-server). +2. [**Create a bot account**](../setting-test-server-and-bot-account#setting-up-a-bot-account) and invite it to the server you just created. +3. Create the following text channels: + * `#announcements` + * `#dev-log` + * `#sir-lancebot-commands` +4. Create the following roles: + * `@Admin` +5. Note down the IDs for your server, as well as any channels and roles created. + * [**Learn how to obtain the ID of a server, channel or role here.**](../setting-test-server-and-bot-account#obtain-the-ids) + +--- + +## Environment variables +You will have to setup environment variables: + +* [**Learn how to set environment variables here.**](../configure-environment-variables) + +The following variables are needed for running Sir Lancebot: + +| Environment Variable | Description | +| -------- | -------- | +| `BOT_TOKEN` | Bot Token from the [Discord developer portal](https://discord.com/developers/applications) | +| `BOT_GUILD` | ID of the Discord Server | +| `BOT_ADMIN_ROLE_ID` | ID of the role `@Admins` | +| `ROLE_HELPERS` | ID of the role `@Helpers` | +| `CHANNEL_ANNOUNCEMENTS` | ID of the `#announcements` channel | +| `CHANNEL_DEVLOG` | ID of the `#dev-log` channel | +| `CHANNEL_COMMUNITY_BOT_COMMANDS` | ID of the `#sir-lancebot-commands` channel | + +[**Full environment variable reference for this project.**](./env-var-reference) + +--- + +While not required, we advise you set `USE_FAKEREDIS` to `true` in development to avoid the need of setting up a Redis server. +It does mean you may lose persistent data on restart but this is non-critical. +Otherwise, please see the below linked guide for Redis related variables. +{: .notification .is-warning } + +--- +# Run the project +The sections below describe the two ways you can run this project. We recomend Docker as it requires less setup. + +## Run with Docker +Make sure to have Docker running, then use the Docker command `docker-compose up` in the project root. +The first time you run this command, it may take a few minutes while Docker downloads and installs Sir Lancebot's dependencies. + +```shell +$ docker-compose up +``` + +If you get any Docker related errors, reference the [Possible Issues](./docker/possible-issues) section of the Docker page. +{: .notification .is-warning } + +## Run on the host +After installing project dependencies use the pipenv command `pipenv run start` in the project root. + +```shell +$ pipenv run 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/sir-lancebot/_info.yml b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/sir-lancebot/_info.yml new file mode 100644 index 00000000..349e6149 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/sir-lancebot/_info.yml @@ -0,0 +1,2 @@ +title: Contributing to Sir Lancebot +description: A guide to setting up and configuring Sir Lancebot. diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/sir-lancebot/env-var-reference.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/sir-lancebot/env-var-reference.md new file mode 100644 index 00000000..066b703e --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/sir-lancebot/env-var-reference.md @@ -0,0 +1,68 @@ +--- +title: Sir-Lancebot Environment Variable Reference +description: The full environment variable reference for Sir-Lancebot. +toc: 2 +--- +## General Variables +The following variables are needed for running Sir Lancebot: + +| Environment Variable | Description | +| -------- | -------- | +| `BOT_TOKEN` | Bot Token from the [Discord developer portal](https://discord.com/developers/applications) | +| `BOT_GUILD` | ID of the Discord Server | +| `BOT_ADMIN_ROLE_ID` | ID of the role @Admins | +| `ROLE_HELPERS` | ID of the role @Helpers | +| `CHANNEL_ANNOUNCEMENTS` | ID of the #announcements channel | +| `CHANNEL_DEVLOG` | ID of the #dev-log channel | +| `CHANNEL_COMMUNITY_BOT_COMMANDS` | ID of the #sir-lancebot-commands channel | + +--- +## Debug Variables +Additionally, you may find the following environment variables useful during development: + +| Environment Variable | Description | +| -------- | -------- | +| `BOT_DEBUG` | Debug mode of the bot | False | +| `PREFIX` | The bot's invocation prefix | `.` | +| `CYCLE_FREQUENCY` | Amount of days between cycling server icon | 3 | +| `MONTH_OVERRIDE` | Interger in range `[0, 12]`, overrides current month w.r.t. seasonal decorators | +| `REDIS_HOST` | The address to connect to for the Redis database. | +| `REDIS_PORT` | | +| `REDIS_PASSWORD` | | +| `USE_FAKEREDIS` | If the FakeRedis module should be used. Set this to true if you don't have a Redis database setup. | +| `BOT_SENTRY_DSN` | The DSN of the sentry monitor. | +| `TRASHCAN_EMOJI` | The emoji to use for the trashcan during paginated embeds | + + +--- +## Tokens/APIs +If you will be working with an external service, you might have to set one of these tokens: + +| Token | Description | +| -------- | -------- | +| `GITHUB_TOKEN` | Personal access token for GitHub, raises rate limits from 60 to 5000 requests per hour. | +| `GIPHY_TOKEN` | Required for API access. [Docs](https://developers.giphy.com/docs/api) | +| `OMDB_API_KEY` | Required for API access. [Docs](http://www.omdbapi.com/) | +| `YOUTUBE_API_KEY` | An OAuth Key or Token are required for API access. [Docs](https://developers.google.com/youtube/v3/docs#calling-the-api) | +| `TMDB_API_KEY` | Required for API access. [Docs](https://developers.themoviedb.org/3/getting-started/introduction) | +| `NASA_API_KEY` | Required for API access. [Docs](https://api.nasa.gov/) | +| `IGDB_API_KEY` | Required for API access. A Twitch account is needed. [Docs](https://api-docs.igdb.com/#about) | +| `WOLFRAM_API_KEY` | | +| `UNSPLASH_KEY` | Required for API access. Use the `access_token` given by Unsplash. [Docs](https://unsplash.com/documentation) | + +--- +## Seasonal Cogs +These variables might come in handy while working on certain cogs: + +| Cog | Environment Variable | Description | +| -------- | -------- | -------- | +| Advent of Code | `AOC_LEADERBOARDS` | List of leaderboards seperated by `::`. Each entry should have an `id,session cookie,join code` seperated by commas in that order. | +| Advent of Code | `AOC_STAFF_LEADERBOARD_ID` | Integer ID of the staff leaderboard. | +| Advent of Code | `AOC_ROLE_ID` | ID of the advent of code role. +| Advent of Code | `AOC_IGNORED_DAYS` | Comma seperated list of days to ignore while calulating score. | +| Advent of Code | `AOC_YEAR` | Debug variable to change the year used for AoC. | +| Advent of Code | `AOC_CHANNEL_ID` | The ID of the #advent-of-code channel | +| Advent of Code | `AOC_FALLBACK_SESSION` | | +| Valentines | `LOVEFEST_ROLE_ID` | | +| Wolfram | `WOLFRAM_USER_LIMIT_DAY` | | +| Wolfram | `WOLFRAM_GUILD_LIMIT_DAY` | | 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 new file mode 100644 index 00000000..75d27d99 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/site.md @@ -0,0 +1,144 @@ +--- +title: Contributing to Site +description: A guide to setting up and configuring Site. +icon: fab fa-github +toc: 1 +--- + +# Requirements + +- [Python 3.8](https://www.python.org/downloads/) +- [Pipenv](https://github.com/pypa/pipenv#installation) + - `pip install pipenv` +- [Git](https://git-scm.com/downloads) + - [Windows](https://git-scm.com/download/win) + - [MacOS](https://git-scm.com/download/mac) or `brew install git` + - [Linux](https://git-scm.com/download/linux) + +Using Docker (recommended): + +- [Docker CE](https://docs.docker.com/install/) +- [Docker Compose](https://docs.docker.com/compose/install/) + - `pip install docker-compose` + +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 + +1. [Clone your fork to a local project directory](../cloning-repository/) +2. [Install the project's dependencies](../installing-project-dependencies/) +3. [Prepare your hosts file](../hosts-file/) + +## Without Docker + +Some additional steps are needed when not using Docker. Docker abstracts away these steps which is why using it is generally recommended. + +### 1. PostgreSQL setup + +Enter psql, a terminal-based front-end to PostgreSQL: + +```shell +psql -qd postgres +``` + +Run the following queries to create the user and database: + +```sql +CREATE USER pysite WITH SUPERUSER PASSWORD 'pysite'; +CREATE DATABASE pysite WITH OWNER pysite; +``` + +Finally, enter `/q` to exit psql. + +### 2. Environment variables + +These contain various settings used by the website. To learn how to set environment variables, read [this page](../configure-environment-variables/) first. + +```shell +DATABASE_URL=postgres://pysite:pysite@localhost:7777/pysite +METRICITY_DB_URL=postgres://pysite:pysite@localhost:7777/metricity +DEBUG=1 +SECRET_KEY=suitable-for-development-only +STATIC_ROOT=staticfiles +``` + +#### Notes regarding `DATABASE_URL` + +- If the database is hosted locally i.e. on the same machine as the webserver, then use `localhost` for the host. Windows and macOS users may need to use the [Docker host IP](../hosts-file/#windows) instead. +- If the database is running in Docker, use port `7777`. Otherwise, use `5432` as that is the default port used by PostegreSQL. +- If you configured PostgreSQL in a different manner or you are not hosting it locally, then you will need to determine the correct host and port yourself. +The user, password, and database name should all still be `pysite` unless you deviated from the setup instructions in the previous section. + +--- +# Run the project + +The project can be started with Docker or by running it directly on your system. + +## Run with Docker + +Start the containers using Docker Compose: + +```shell +docker-compose up +``` + +The `-d` option can be appended to the command to run in detached mode. This runs the containers in the background so the current terminal session is available for use with other things. + +If you get any Docker related errors, reference the [Possible Issues](https://pythondiscord.com/pages/contributing/docker/#possible-issues") section of the Docker page. +{: .notification .is-warning } + +## Run on the host + +Running on the host is particularily useful if you wish to debug the site. The [environment variables](#2-environment-variables) shown in a previous section need to have been configured. + +### Database + +First, start the PostgreSQL database. +Note that this can still be done with Docker even if the webserver will be running on the host - simply adjust the `DATABASE_URL` environment variable accordingly. + +If you chose to use Docker for just the database, use Docker Compose to start the container: + +```shell +docker-compose up postgres +``` + +If you're not using Docker, then use [pg_ctl](https://www.postgresql.org/docs/current/app-pg-ctl.html) or your system's service manager if PostgreSQL isn't already running. + +### Webserver + +Starting the webserver is done simply through pipenv: + +```shell +pipenv run start +``` + +--- +# Working on the project + +The development environment will watch for code changes in your project directory and will restart the server when a module has been edited automatically. +Unless you are editing the Dockerfile or docker-compose.yml, you shouldn't need to manually restart the container during a developing session. + +[**Click here to see the basic Git workflow when contributing to one of our projects.**](../working-with-git/) + +--- +# Django admin site + +Django provides an interface for administration with which you can view and edit the models among other things. + +It can be found at [http://admin.pythondiscord.local:8000](http://admin.pythondiscord.local:8000). The default credentials are `admin` for the username and `admin` for the password. 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 new file mode 100644 index 00000000..f9962990 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/style-guide.md @@ -0,0 +1,211 @@ +--- +title: Style Guide +description: Coding conventions for our Open Source projects. +icon: fab fa-python +--- + +> A style guide is about consistency. +> Consistency with this style guide is important. +> Consistency within a project is more important. +> Consistency within one module or function is the most important. + +> However, know when to be inconsistent -- sometimes style guide recommendations just aren't applicable. +> When in doubt, use your best judgment. Look at other examples and decide what looks best. And don't hesitate to ask! + +> — [PEP 8, the general Style Guide for Python Code](https://www.python.org/dev/peps/pep-0008/) + +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 adjustment requests to be commented. + +We've added below a guideline to aid new contributors, allowing them to refer to it during development, to help get more familiar and to hopefully lessen some of the frustrations that come from first-time contributions. + +Anything that isn't defined below falls back onto the [PEP 8 guidelines](https://www.python.org/dev/peps/pep-0008/), so be sure to reference it also. + +# Code Structure +## Maximum Line Length +Each project has specified their respective maximum line lengths. +Generally, we try to keep this at 100 or 120 characters, making our length longer than the typical 79 characters. + +Most IDEs and smarter editors will use the lint settings we store in the project's `tox.ini` or `.flake8` file after you install the appropriate development packages, so should conflict with our suggested project rules. +If your editor does not have this ability but instead requires setting it manually, make sure to change it to the appropriate length specified in these files. + +## Line Breaks +Avoid breaking a line far earlier than necessary, such as: + +```py +array = [ # there was plenty of room on this line + 1, 2, 3, + 4, 5, 6 +] +``` + +Try instead to make use of the space you're allowed to use appropriately: +```py +array = [1, 2, 3, 4, 5, 6] +``` + +Any line continuations must be indented a full level, i.e. 4 spaces. So don't do: +```py +def an_example_function_definition_that_is_kinda_long( + variable_name_of_the_first_positional_argument, # only 2 spaces on the indent + variable_name_of_the_second_positional_argument # same here +) +``` + +Do instead: +```py +def an_example_function_definition_that_is_kinda_long( + variable_name_of_the_first_positional_argument, + variable_name_of_the_second_positional_argument +) +``` + +### Bracket and Item Arrangement +In the case where items contained in brackets need to be broken across multiple lines, items should be dropped to a new line after the opening bracket with an additional level of indentation. +The closing bracket ends on it's own new line, on the same indentation level as the opening bracket. + +Avoid doing: +```py +def long_function_name_that_is_taking_up_too_much_space(var_one, var_two, var_three, # didn't drop a line after the brackets + var_four, var_five, var_six, + var_seven, var_eight): + print(var_one) +``` +```py +def long_function_name_that_is_taking_up_too_much_space( + var_one, + var_two, + var_three, + var_four, + var_five, + var_six, + var_seven, + var_eight): # didn't drop the closing bracket to a new line + print(var_one) +``` + +Instead the correct style is: +```py +def long_function_name_that_is_taking_up_too_much_space( + var_one, + var_two, + var_three, + var_four, + var_five, + var_six, + var_seven, + var_eight +): + print(var_one) +``` + +## Imports +Our projects require correctly ordering imports based on the pycharm import order rules. +If you use Pycharm as your main IDE, you can also use the `CTRL+ALT+O` shortcut to automatically reorder your imports to the correct style. + +There's three groups of imports which are defined in the following order: + +- Standard library +- 3rd party +- Local + +Each group must be ordered alphabetically, with uppercase modules coming before lowercase. +```py +from packagename import A, Z, c, e +``` + +Direct imports must be distinct, so you cannot do: +```py +import os, sys +``` +Instead do: +```py +import os +import sys +``` + +Absolute referencing for local project modules are preferenced over relative imports. + +Wildcard imports should be avoided. + +# Strings +## Quote Marks +Preference is to use double-quotes (`"`) wherever possible. +Single quotes should only be used for cases where it is logical. +Exceptions might include: + +- using a key string within an f-string: `f"Today is {data['day']}"`. +- using double quotes within a string: `'She said "oh dear" in response'` + +Docstrings must use triple double quotes (`"""`). + +## Docstrings +All public methods and functions should have docstrings defined. + +### Line Structure +Single-line docstrings can have the quotes on the same line: +```py +def add(a, b): + """Add two arguments together.""" + return a + b +``` + +Docstrings that require multiple lines instead keep both sets of triple quotes on their own lines: +```py +def exponent(base, exponent=2): + """ + Calculate the base raised to the exponents power. + + Default is 2 due to a squared base being the most common usage at this time. + """ + return a ** b +``` + +### Spacing +Functions and methods should not have an extra empty newline after the docstring. +```py +def greeting(name): + """Build a greeting string using the given name.""" + return f"Welcome, {name}" +``` + +Class docstrings do require an extra newline. +```py +class SecretStuffCog(commands.Cog): + """Handle the secret commands that must never been known.""" + + def __init__(self, bot): + ... +``` + +### Mood +Imperative mood and present tense usage is preferenced when writing docstrings. + +Imperative mood is a certain grammatical form of writing that expresses a clear command to do something. + +**Use:** "Build an information embed."<br> +**Don't use:** "Returns an embed containing information." + +Present tense defines that the work being done is now, in the present, rather than in the past or future. + +**Use:** "Build an information embed."<br> +**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/). + +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 +``` + +In previous examples, we have purposely omitted annotations to keep focus on the specific points they represent. 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 new file mode 100644 index 00000000..26c89b56 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/working-with-git.md @@ -0,0 +1,23 @@ +--- +title: Working with Git +description: Basic workflows when using git. +icon: fab fa-git-alt +--- + +Working with git can be daunting, but it is a powerful tool for collaboration and version control. +Below are links to regular workflows for working with Git using PyCharm or the CLI. + +> **What's the difference?**<br> +> The integrated Git tool built into PyCharm offers a more visual and abstract way to use Git to manage your files.<br> +> However, the CLI offers more minute control and functionality compared to the GUI, which may not always do exactly what you want. + +* [**Working with Git in PyCharm**](./pycharm) +* [**Working with the Git CLI**](./cli) + +--- + +**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/) diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/working-with-git/_info.yml b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/working-with-git/_info.yml new file mode 100644 index 00000000..68ef3fd6 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/working-with-git/_info.yml @@ -0,0 +1,3 @@ +title: Working with Git +description: Basic workflows when using git. +icon: fab fa-git-alt diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/working-with-git/cli.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/working-with-git/cli.md new file mode 100644 index 00000000..5f196837 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/working-with-git/cli.md @@ -0,0 +1,121 @@ +--- +title: Working with the Git CLI +description: Basic workflow when using the git CLI. +toc: 2 +--- + +This is the basic workflow when working with Git with CLI. For the PyCharm version of the guide, [**click here**](../pycharm). +The following will use the [Sir-Lancebot](https://github.com/python-discord/sir-lancebot/) repository as an example, but the steps are the same for all other repositories. + +> **Note:** This is a guide only meant to get you started with git. For in-depth resources, check the [**Working with Git**](..) page. + +--- + +## Adding the Upstream Remote +Adding a *remote* to the main GitHub repository you forked off will allow you to later update your fork with changes from the main repository. + +Generally, a *remote* designates a repository that is on GitHub or another external location rather than on your computer. +The `origin` remote will refer to your fork on GitHub. The `upstream` remote will refer to the main repository on GitHub. +```sh +$ git remote add upstream https://github.com/python-discord/sir-lancebot.git +``` +If you use SSH, use `[email protected]:python-discord/sir-lancebot.git` for the upstream URL instead. + +--- + +## Creating a New Branch +You will be committing your changes to a new branch rather than to `main`. +Using branches allows you to work on muiltiple pull requests without conflicts. + +You can name your branch whatever you want, but it's recommended to name it something succint and relevant to the changes you will be making. + +Run the following commands to create a new branch. Replace `branch_name` with the name you wish to give your branch. +```sh +$ git fetch --all +... +$ git checkout --no-track -b branch_name upstream/main +``` + +--- + +## Staging Changes +Files in git can be in one of four different states: + +- *Staged*: These files have been modified and will be committed. +- *Unstaged*: These files were already present but have been modified. +- *Untracked*: These files are new to the repository. +- *Ignored*: Specified in a `.gitignore` file in the project root, these files will never be committed, remaining only on your computer. + +As you can see, only staged files will end up being committed. +You can get an overview of this using `git status`. +If you wish to commit unstaged or untracked files, you will need to add them with `git add` first. +```sh +# Add files individually +$ git add path/to/file.py path/to/other/file.py + +# Add all unstaged and untracked files in a directory +$ git add path/to/directory + +# Add all unstaged and untracked files in the project +$ git add . + +# Add all tracked and modified files in the project +$ git add -u + +# Unstage a file +$ git reset -- path/to/file.py +``` + +--- + +## Discarding Changes +Be careful, these operations are **irreversible**! +```sh +# Discard changes to an unstaged file +$ git checkout -- path/to/file.py + +# Discard ALL uncommitted changes +$ git reset --hard HEAD +``` + +--- + +## Committing Changes +The basic command for committing staged changes is `git commit`. All commits must have a message attached to them. +```sh +# Commit staged changes and open your default editor to write the commit message +$ git commit + +# Specify the message directly +$ git commit -m "Turn pride avatar into an embed" + +# Commit all staged and unstaged changes. This will NOT commit untracked files +$ git commit -a -m "Update d.py documentation link" +``` + +--- + +## Pushing Commits +Commits remain local (ie. only on your computer) until they are pushed to the remote repository (ie. GitHub). + +The first time you push on your new branch, you'll need to set the upstream when you push: +```sh +$ git push -u origin branch_name +``` +Any subsequent pushes can be done with just `git push`. + +--- + +## Pulling Changes +Sometimes you want to update your repository with changes from GitHub. +This could be the case if you were working on the pull request on two different computers and one of them has an outdated local repository. + +You can pull the changes from GitHub with: +```sh +$ git pull +``` +You can also pull changes from other branches such as from branch `main` in `upstream`: +```sh +$ git pull upstream main +``` +This should generally only be needed if there are [merge conflicts](https://help.github.com/en/articles/about-merge-conflicts) that you need to resolve manually. Conflicts arise when you change the same code that someone else has changed and pushed since you last updated your local repository. diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/working-with-git/pycharm.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/working-with-git/pycharm.md new file mode 100644 index 00000000..3f7fefa0 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/working-with-git/pycharm.md @@ -0,0 +1,67 @@ +--- +title: Working with Git in PyCharm +description: Basic workflow when using git in PyCharm. +toc: 2 +--- + +This is the basic workflow when working with Git with PyCharm. For the CLI version of the guide, [**click here**](../cli). +The following will use the [Sir-Lancebot](https://github.com/python-discord/sir-lancebot/) repository as an example, but the steps are the same for all other repositories. + +> **Note:** This is a guide only meant to get you started with git. For in-depth resources, check the [**Working with Git**](wiki:/contributing/working-with-git/) page. + +--- + +## Adding the Upstream Remote +> Adding a *remote* to the main GitHub repository you forked off will allow you to later update your fork with changes from the main repository. + +> Generally, a *remote* designates a repository that is on GitHub or another external location rather than on your computer. The `origin` remote will refer to your fork on GitHub. The `upstream` remote will refer to the main repository on GitHub. + +1. In the menu bar, navigate to `Git` -> `Remotes...`.<br> + +2. In the popup menu, click the `+` icon, set `upstream` as the name, set the URL as the URL for the main repository on GitHub.<br> + +3. Click `OK`. + +--- + +## Creating a New Branch +> You will be committing your changes to a new branch rather than to `main`. Using branches allows you to work on multiple pull requests at the same time without conflicts. + +> You can name your branch whatever you want, but it's recommended to name it something succint and relevant to the changes you will be making. + +> Before making new branches, be sure to checkout the `main` branch and ensure it's up to date. + +1. In the bottom right corner, click on `main` and then click `New Branch`.<br> + + +--- + +## Committing Changes +After making changes to the project files, you can commit by clicking the commit button that's part of the Git actions available in the top right corner of your workspace: + + + +The flow of making a commit is as follows: + +1. Select the files you wish to commit. +2. Write a brief description of what your commit is. This is your *commit message*. +3. See the actual changes your commit will be making, and optionally tick/untick specific changes to only commit the changes you want. +4. Click `Commit`.<br> + + +--- + +## Pushing Changes +When you are ready to have your commits be available in your remote fork, navigate to `Git` -> `Push...`. +Select the commits you want to push, make sure the remote branch is your intended branch to push to, and click `Push`. + + + +--- + +## Pulling Changes +> Sometimes you want to update your repository with changes from GitHub. This could be the case if you were working on the pull request on two different computers and one of them has an outdated local repository. + +To do that, navigate to `Git` -> `Pull...`. From there, select the *remote* and the branches to pull from, then click `Pull`. + + diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/help-channel-guide.md b/pydis_site/apps/content/resources/guides/pydis-guides/help-channel-guide.md new file mode 100644 index 00000000..2a6e7781 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/help-channel-guide.md @@ -0,0 +1,78 @@ +--- +title: Help Channels +description: How do help channels work in the Python Discord community? +icon: fab fa-discord +relevant_links: + Asking Good Questions: ../asking-good-questions + Role Guide: /pages/server-info/roles + Helping Others: ../helping-others +--- + +On the 5th of April 2020, we introduced a new help channel system at Python Discord. This article is a supplementary guide to explain precisely where to go to find help. + +We have two different kinds of help channels in our community - **Topical help channels**, and **general help channels**. +Where you should go depends on what you need help with. +These channels also attract different helpers, and move at different speeds, which affects the kind of help you're likely to receive, and how fast you get that help. + +# Topical Help Channels + +The topical help channels move at a slower pace than the general help channels. +They also sometimes attract domain experts - for example, `#async-and-concurrency` has CPython contributors who helped write asyncio, and in `#game-development` you can find the creators and maintainers of several game frameworks. +If your question fits into the domain of one of our topical help channels, and if you're not in a big hurry, then this is probably the best place to ask for help. + + + +Some of the topical help channels have a broad scope, so they can cover many (somewhat) related topics. +For example, `#data-science-and-ai` covers scientific Python, statistics, and machine learning, while `#algos-and-data-structs` covers everything from data structures and algorithms to maths. + +To help you navigate this, we've added a list of suggested topics in the topic of every channel. +If you're not sure where to post, feel free to ask us which channel is relevant for a topic in `#community-meta`. + +# General Help Channels + +Our general help channels move at a fast pace, and attract a far more diverse spectrum of helpers. +This is a great choice for a generic Python question, and a good choice if you need an answer as soon as possible. +It's particularly important to [ask good questions](..guides/asking-good-questions) when asking in these channels, or you risk not getting an answer and having your help channel be claimed by someone else. + +## How To Claim a Channel + +There are always 3 available help channels waiting to be claimed in the **Python Help: Available** category. + + + +In order to claim one, simply start typing your question into one of these channels. Once your question has been posted, you have claimed this channel, and the channel will be moved down to the **Python Help: Occupied** category. + +If you're unable to type into these channels, this means you're currently **on cooldown**. In order to prevent someone from claiming all the channels for themselves, **we only allow someone to claim a new help channel every 15 minutes**. However, if you close your help channel using the `!dormant` command, this cooldown is reset early. + + +*This message is always posted when a channel becomes available for use.* + +## Q: For how long is the channel mine? + +The channel is yours until it has been inactive for **30 minutes**. When this happens, we move the channel down to the **Python Help: Dormant** category, and make the channel read-only. After a while, the channel will be rotated back into **Python Help: Available** for the next question. Please try to resist the urge to continue bumping the channel so that it never gets marked as inactive. If nobody is answering your question, you should try to reformulate the question to increase your chances of getting help. + + +*You'll see this message in your channel when the channel is marked as inactive.* + +## Q: I don't need my help channel anymore, my question was answered. What do I do? + +Once you have finished with your help channel you or a staff member can run `!dormant`. This will move the channel to the **Python Help: Dormant** category where it will sit until it is returned to circulation. You will only be able to run the command if you claimed the channel from the available category, you cannot close channels belonging to others. + +## Q: Are only Helpers supposed to answer questions? + +Absolutely not. We strongly encourage all members of the community to help answer questions. If you'd like to help answer some questions, simply head over to one of the help channels that are currently in use. These can be found in the **Python Help: Occupied** category. + + + +Anyone can type in these channels, and users who are particularly helpful [may be offered a chance to join the staff on Python Discord](/pages/server-info/roles/#note-regarding-staff-roles). + +## Q: I lost my help channel! + +No need to panic. +Your channel was probably just marked as dormant. +All the dormant help channels are still available at the bottom of the channel list, in the **Python Help: Dormant** category, and also through search. +If you're not sure what the name of your help channel was, you can easily find it by using the Discord Search feature. +Try searching for `from:<your nickname>` to find the last messages sent by yourself, and from there you will be able to jump directly into the channel by pressing the Jump button on your message. + + +*The dormant help channels can be found at the bottom of the channel list.* diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/helping-others.md b/pydis_site/apps/content/resources/guides/pydis-guides/helping-others.md new file mode 100644 index 00000000..d126707d --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/helping-others.md @@ -0,0 +1,140 @@ +--- +title: Helping Others +description: The staff's take on how to help others in our community. +icon: fab fa-discord +relevant_links: + Asking Good Questions: ../asking-good-questions + Help Channel Guide: ../help-channel-guide + Code of Conduct: /pages/code-of-conduct/ +toc: 2 +--- + +Python Discord has a lot of people asking questions, be it in the help channels, topical channels, or any other part of the server. +Therefore, you might sometimes want to give people the answers you have in mind. +But you might not be sure how best to approach the issue, or maybe you'd like to see how others handle it. +This article aims to present a few of the general principles which guide the staff on a day-to-day basis on the server. + +## Understanding the Problem + +Some people are good at asking for help. +They might be able to present their problem accurately and concisely, in which case discussing the problem and giving tips is simple and straight-forward. +But not everyone might be able to do that for their current issue. +Maybe they just don't know what they don't know. + +If you feel like there's a gap in your understanding of the problem, it's often a good first step to query the asker for more information. Some of this information might be: + +* More code +* The way in which the code doesn't work (if that is the issue), be it an exception message with traceback, undesired output, etc. +* You can sometimes infer what the problem is yourself by requesting short examples of the desired output for specific input. + +At this point, it's probably better being safe than sorry. +You don't want to accidentally pursue a direction that isn't even related to the real issue, as it could lead to frustration on both sides. +Beginners especially can be prone to asking a question which presents their attempt at solving the problem, instead of presenting the problem itself. +This is often called an [XY problem](https://xyproblem.info/). + +Even if eventually you can't help, simply clarifying what the problem is can help others join in, and give their input. + +> #### Example 1: +> A person might ask: *"How do I look at the values inside my function from outside?"* +> +> What they might be asking is: *"How do I return a value from a function?"* + + +## Understanding the Helpee + +Assuming you know what the problem is, it's vital to gauge the level of knowledge of the person asking the question. +There's a stark difference between explaining how to do something to someone experienced, who only lacks knowledge on the specific topic; and someone who is still learning the basics of the language. + +Try adjusting the solutions you present and their complexity accordingly. +Teaching new concepts allows the helpee to learn, but presenting too complex of a solution might overwhelm them, and the help session might not achieve its purpose. + +> #### Example 2: +> A user might ask how to count how often each word appears in a given text. +> You might lean towards solving it using `collections.Counter`, but is it really the right approach? +> If the user doesn't know yet how to update and access a dictionary, it might be better to start there. + +Generally, you should consider what approach will bring the most value to the person seeking help, instead of what is the most optimal, or "right" solution. + +Usually, understanding a person's level can be achieved after a short conversation (such as trying to understand the problem), or simply by seeing the person's code and what they need help with. +At other times, it might not be as obvious, and it might be a good idea to kindly inquire about the person's experience with the language and programming in general. + + +## Teach a Man to Fish... + +The path is often more important than the answer. +Your goal should primarily be to allow the helpee to apply, at least to a degree, the concepts you introduce in your answer. +Otherwise, they might keep struggling with the same problem over and over again. +That means that simply showing your answer might close the help channel for the moment, but won't be very helpful in the long-term. + +A common approach is to walk the helpee through to an answer: + +* Break the task into smaller parts that will be easier to handle, and present them step by step. + Try to think of the order of the steps you yourself would take to reach the solution, and the concepts they need to understand for each of those steps. + If one step requires the helpee to understand several new concepts, break it down further. +* Ask instructive questions that might help the person think in the right direction. + +> #### Example 3: +> +> **user**: "Hey, how can I create a sudoku solver?"<br> +> *helper1 proceeds to paste 40 lines of sudoku solving code*<br> +> **helper2**: "Are you familiar with lists / recursion / backtracking?"<br> +> *helper2 proceeds to give the information the user lacks* +> +> With the first replier, there's a much smaller chance of the helpee understanding how the problem was solved, and gaining new tools for future projects. +> It's much more helpful in the long run to explain the new concepts or guide them to resources where they can learn. +> +> This is also an example of gauging the level of the person you're talking to. +> You can't properly help if you don't know what they already learned. +> If they don't know recursion, it's going to take a slower, more detailed approach if you try to explain backtracking to them. +> Likewise if they're not familiar with lists. +> +> The same applies to presenting external resources. +> If they only just started programming, pasting a link to the Python documentation is going to be of little help. +> They are unlikely to be able to get around that website and understand what you expect them to read. In contrast, for a more seasoned programmer, the docs might be just what they need. + + +## Add a Grain of Salt + +Giving people more information is generally a good thing, but it's important to remember that the person helped is trying to soak in as much as they can. +Too much irrelevant information can confuse them, and make them lose sight of the actual solution. +Presenting a solution that is considered a bad practice might be useful in certain situations, but it's important to make sure they are aware it's not a good solution, so they don't start using it themselves. + +> #### Example 4: +> +> **user**: "How can I print all elements in a list?"<br> +> **helper1**: "You can do it like so:"<br> +> +> for element in your_list: +> print(element) +> +> **helper2**: "You can also do it like this:"<br> +> +> for i in range(len(your_list)): +> print(your_list[i]) +> +> The second replier gave a valid solution, but it's important that he clarifies that it is concidered a bad practice in Python, and that the first solution should usually be used in this case. + + +## It's OK to Step Away + +Sometimes you might discover you don't have the best chemistry with the person you're talking to. +Maybe there's a language barrier you don't manage to overcome. +In other cases, you might find yourself getting impatient or sarcastic, maybe because you already answered the question being asked three times in the past hour. + +That's OK- remember you can step away at any time and let others take over. +You're here helping others on your own free time (and we really appreciate it!), and have no quotas to fill. + +At other times, you might start talking with someone and realize you're not experienced in the topic they need help with. +There's nothing wrong with admitting you lack the specific knowledge required in this case, and wishing them good luck. +We can't know everything. + +Remember that helping means thinking of what's best for them, and we also wouldn't want to see you become agitated. +We're all here because we enjoy doing this. + + +## Respect Others Giving Help + +You might sometimes see others giving help and guiding others to an answer. +Throwing in additional ideas is great, but please remember both teaching and learning takes concentration, and you stepping in might break it. +You might have another idea to suggest, but you see that there's already a person helping, and that they're handling the situation. +In that case, it might be a good idea to patiently observe, and wait for a good opportunity to join in so as to not be disruptive. diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/how-to-contribute-a-page.md b/pydis_site/apps/content/resources/guides/pydis-guides/how-to-contribute-a-page.md index 726cb7b2..716250b1 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/how-to-contribute-a-page.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/how-to-contribute-a-page.md @@ -169,7 +169,7 @@ path = os.path.join("foo", "bar") ### HTML Attributes To add HTML attributes to certain lines/paragraphs, [see this page](https://python-markdown.github.io/extensions/attr_list/#the-list) for the format and where to put it. -This can be useful for setting the image size when adding an image using markdown (see the [Image Captions](#image-captions) section for an example), or for adding bulma styles to certain elements (like the warning notification [here](/pages/guides/pydis-guides/contributing/sir-lancebot#setup-instructions)). +This can be useful for setting the image size when adding an image using markdown (see the [Image Captions](#image-captions) section for an example), or for adding bulma styles to certain elements (like the warning notification [here](/pages/guides/pydis-guides/contributing/sir-lancebot#setup-instructions)).<br> **This should be used sparingly, as it reduces readability and simplicity of the article.** --- diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/off-topic-etiquette.md b/pydis_site/apps/content/resources/guides/pydis-guides/off-topic-etiquette.md new file mode 100644 index 00000000..f8031834 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/off-topic-etiquette.md @@ -0,0 +1,32 @@ +--- +title: Conversation Etiquette in Our Off-Topic Channels +description: Guidelines on conversation etiquette. +icon: fab fa-discord +--- + +## Why do we need off-topic etiquette? +Everyone wants to have good conversations in our off-topic channels, but with tens of thousands of members, this might mean different things to different people. +To facilitate the best experience for everyone, here are some guidelines on conversation etiquette. + +## Three things you shouldn't do +1. Don't interrupt active conversations + * There's three off-topic channels which can support three simultaneous conversations. + If one is active and you have something you'd like to discuss, try a different channel. +2. Don't post memes unless they're relevant to a conversation + * There are better places to share memes; if you have a meme you think is worth sharing, try to find a relevant subreddit, like [/r/ProgrammerHumor](https://www.reddit.com/r/ProgrammerHumor/). +3. Don't snap at people + * We are a large, diverse community. Different native languages, experiences, and ages mean miscommunications happen. Always try to assume the best in other community members. + +## Three things you should do +1. Ask away + * If you have a question that isn't about Python, just ask it in an inactive off-topic channel. + If someone sees your question who knows the answer, they will answer you. + "Why is my wifi not working?", "how do I tune a guitar?", "is there a server for C#?", are all fair game for questions to ask. + If your question relates to Python, try to find the most suitable channel to ask your question, or open a help session. +2. When in doubt, ask someone to clarify what they mean + * If you're not sure you properly understand someone, ask them to clarify. + Text isn't necessarily the easiest way for everyone to communicate, so it makes life easier if we're all on the same page. +3. Join in! + * The off-topic channels have lots of fun or interesting conversations; if someone is talking about something you're interested in, don't be scared to hop into the conversation. + +While you can discuss other topics than Python in the off-topic channels, the [ordinary rules](/pages/rules/) still apply. diff --git a/pydis_site/apps/content/resources/guides/python-guides/_info.yml b/pydis_site/apps/content/resources/guides/python-guides/_info.yml new file mode 100644 index 00000000..67730962 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/python-guides/_info.yml @@ -0,0 +1,3 @@ +title: Python Guides +description: Guides related to the Python Programming Language. +icon: fab fa-python diff --git a/pydis_site/apps/content/resources/guides/python-guides/creating-python-environment-windows.md b/pydis_site/apps/content/resources/guides/python-guides/creating-python-environment-windows.md new file mode 100644 index 00000000..356d63bd --- /dev/null +++ b/pydis_site/apps/content/resources/guides/python-guides/creating-python-environment-windows.md @@ -0,0 +1,72 @@ +--- +title: Creating a Unix-style Python Environment on Windows +description: How to setup Python for Windows. +--- + +Many programmers use Linux or macOS operating systems for their work, though newcomers to programming will likely want to get started on the computer they already own, which will often be running Windows. +This guide will help you install Python on Windows. + +Programmers also need to become comfortable using a command prompt (also known as a terminal), and many guides for both beginning and advanced programming will often tell you certain commands to run. +The Windows command prompt has different names for similar commands that are available on Linux and macOS. +This guide will also help you set up a command prompt called Git Bash, which will support many of the commands available on Linux and macOS. + +## Installing Python +Python can be downloaded from the Python website on the [downloads page](https://www.python.org/downloads/). +The website will automatically present you with a download button for the latest release of the Windows version when you access the site from a Windows machine. + +Once the download is complete, you can begin the installation. +Select "Customize Installation". +The default settings for "Optional Features" are sufficient and you can click "Next". + +The next step is to decide on a location where the Python executable can be stored on your computer. +This should be a location that's easy for you to remember. +One possibility is to create a folder called "Python" at the root of your hard drive. +Once you have selected a location, you can click "Install", as no other settings on this screen need to be adjusted. +This will complete the installation. + +## Installing a text editor +You will also need a text editor for writing Python programs, and for subsequent steps of this guide. +Powerful programs called integrated development environments (IDEs) like PyCharm and Visual Studio Code contain text editors, but they also contain many other features with uses that aren't immediately obvious to new programmers. + +[Notepad++](https://notepad-plus-plus.org/) is a popular text editor for both beginners and advanced users who prefer a simpler interface. +Other editors we recommend can be found (https://pythondiscord.com/resources/tools/#editors)[here]. + +## Installing Git Bash +Git is a command line program that helps you keep track of changes to your code, among other things. +Many developers use it, and while you may not need it right away, it is useful to install it because it comes with Git Bash. +On the "Select Components" screen, no settings need to be changed. +The next screen will ask what text editor you want to use with Git. Vim is the default choice, though Vim is widely considered difficult to learn, so you may choose to select Notepad++ or whichever text editor you may have installed previously. + +For all remaining screens in the installation, the default selections are fine. + +## Configuring .bashrc +`.bashrc` is a file where we tell Git Bash where the Python executable is. +First, open Git Bash, and as your first command, type `echo ~` and hit enter. +This will most likely print `c/Users/YourUsername` to the terminal. +Navigate to this location in your file explorer, though keep in mind that Windows will display `c/Users/YourUsername` as `C:\Users\YourUsername`. +In this folder, there will be a file called `.bashrc`; open it with your text editor of choice. + +For this step, you will need to remember where you installed Python earlier. +In whichever folder that was, there is a file called `python.exe`; this is the executable that will run your Python programs. +Copy the full path of this file, starting from `C:`. +If you used the example location given earlier, it will be located at `C:\Python\python.exe`. + +In the `.bashrc` file, add a line to the end of the file saying `alias python='C:\\Python\\python.exe`, where `C:\\Python\\python.exe` is the location of your `python.exe` file, but each folder is separated by two backslashes instead of one. +The two backslashes are because a single backslash is used as an [escape character](https://en.wikipedia.org/wiki/Escape_character). +Save the file, and then type `source ~/.bashrc` to activate the change you have made. + +Finally, enter `python -c 'import sys; print(sys.executable)'` into Git Bash. +(If you attempt to copy and paste this into the terminal using Ctrl+V, it might not work, though Shift+Insert will.) +If all the steps have been followed correctly, this will print the location of your `python.exe` file and demonstrate that your environment is set up correctly. +You can hereafter use the `python` command in Git Bash to run any Python program that you write. + +## Running a test program +At any location on your computer, create a file named `hello.py` and open it with your text editor. +The program need only be one line: `print('Hello world!')`. +Save this file. + +To run this program in Git Bash, navigate to where it is saved on your hard drive. +If you know the path to this location, you can use the `cd` command ("cd" stands for "change directory") to navigate to it. +If it's saved to your desktop, `cd /c/Users/YourUsername/Desktop` will take you there. +Otherwise if you have the directory open in your file explorer, you can right click anywhere in the white space of the file explorer window (not on top of a file) and select "Git Bash Here". +Once you're there, type `python hello.py`, and the program will run. diff --git a/pydis_site/apps/content/resources/guides/python-guides/discordpy.md b/pydis_site/apps/content/resources/guides/python-guides/discordpy.md new file mode 100644 index 00000000..b0b2fad1 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/python-guides/discordpy.md @@ -0,0 +1,230 @@ +--- +title: Discord.py Learning Guide +description: A learning guide for the discord.py bot framework written by members of our community. +icon: fab fa-python +toc: 2 +--- + +<!-- discord.py Badge --> +<a href="https://github.com/Rapptz/discord.py/"> + <div class="tags has-addons"> + <span class="tag is-dark">discord.py</span><span class="tag is-info">≥1.0</span> + </div> +</a> + +Interest in creating a Discord bot is a common introduction to the world of programming in our community. + +Using it as your first project in programming while trying to learn is a double-edged sword. +A large number of concepts need to be understood before becoming proficient at creating a bot, making the journey of learning and completing the project more arduous than more simple projects designed specifically for beginners. +However in return, you get the opportunity to expose yourself to many more aspects of Python than you normally would and so it can be an amazingly rewarding experience when you finally reach your goal. + +Another excellent aspect of building bots is that it has a huge scope as to what you can do with it, almost only limited by your own imagination. +This means you can continue to learn and apply more advanced concepts as you grow as a programmer while still building bots, so learning it can be a useful and enjoyable skillset. + +This page provides resources to make the path to learning as clear and easy as possible, and collates useful examples provided by the community that may address common ideas and concerns that are seen when working on Discord bots. + +## Essential References + +Official Documentation: [https://discord.py.readthedocs.io](https://discordpy.readthedocs.io/) + +Source Repository: [https://github.com/Rapptz/discord.py](https://github.com/Rapptz/discord.py) + +## Creating a Discord Bot Account + +1. Navigate to [https://discord.com/developers/applications](https://discord.com/developers/applications) and log in. +2. Click on `New Application`. +3. Enter the application's name. +4. Click on `Bot` on the left side settings menu. +5. Click `Add Bot` and confirm with `Yes, do it!`. + +### Client ID +Your Client ID is the same as the User ID of your Bot. +You will need this when creating an invite URL. + +You can find your Client ID located on the `General Information` settings page of your Application, under the `Name` field. + +Your Client ID is not a secret, and does not need to be kept private. + +### Bot Token + +Your Bot Token is the token that authorises your Bot account with the API. +Think of it like your Bot's API access key. +With your token, you can interact with any part of the API that's available to bots. + +You can find your Bot Token located on the Bot settings page of your Application, under the Username field. +You can click the Copy button to copy it without revealing it manually. + +**Your Bot Token is a secret, and must be kept private.** +If you leak your token anywhere other people has access to see it, no matter the duration, you should reset your Bot Token. + +To reset your token, go to the Bot settings page of your Application, and click the Regenerate button. +Be sure to update the token you're using for your bot script to this new one, as the old one will not work anymore. + +### Permissions Integer + +Discord Permissions are typically represented by a Permissions Integer which represents all the Permissions that have been allowed. + +You can find a reference to all the available Discord Permissions, their bitwise values and their descriptions here:<br> +[https://discordapp.com/developers/docs/topics/permissions#permissions-bitwise-permission-flags](https://discordapp.com/developers/docs/topics/permissions#permissions-bitwise-permission-flags) + +If you want to create your own Permissions Integer, you can generate it in the `Bot` settings page of your Application, located at the bottom of the page. + +Tick the permissions you want to be allowing, and it'll update the `Permissions Integer` field, which you can use in your Bot Invite URL to set your bot's default permissions when users go to invite it. + +### Bot Invite URL + +Bot's cannot use a server invite link. Instead, they have to be invited by a member with the Manage Server permission. + +The Bot Invite URL is formatted like: +`https://discordapp.com/oauth2/authorize?client_id={CLIENT_ID}&scope=bot&permissions={PERMISSIONS_INTEGER}` + +You can create the Invite URL for your bot by replacing: + +* `{CLIENT_ID}` with your [Client ID](#client-id) +* `{PERMISSIONS_INTEGER}` with the [Permissions Integer](#permissions-integer) + +You can also generate it with the [Permissions Calculator](https://discordapi.com/permissions.html tool) tool. + +## Using the Basic Client (`discord.Client`) { data-toc-label="Using the Basic Client" } + +Below are the essential resources to read over to get familiar with the basic functionality of `discord.py`. + +* [Basic event usage](https://discordpy.readthedocs.io/en/latest/intro.html#basic*concepts) +* [Simple bot walkthrough](https://discordpy.readthedocs.io/en/latest/quickstart.html#a*minimal*bot) +* [Available events reference](https://discordpy.readthedocs.io/en/latest/api.html#event*reference) +* [General API reference](https://discordpy.readthedocs.io/en/latest/api.html) + +## Using the Commands Extension (`commands.Bot`) { data-toc-label="Using the Commands Extension" } + +The Commands Extension has a explanatory documentation walking you through not only what it is and it's basic usage, but also more advanced concepts. +Be sure to read the prose documentation in full at:<br> +[https://discordpy.readthedocs.io/en/latest/ext/commands/commands.html](https://discordpy.readthedocs.io/en/latest/ext/commands/commands.html) + +It fully covers: +* How to create bot using the Commands Extension +* How to define commands and their arguments +* What the Context object is +* Argument Converters +* Error Handling basics +* Command checks + +You will also need to reference the following resources: +* [Commands Extension exclusive events](https://discordpy.readthedocs.io/en/latest/ext/commands/api.html#event-reference) +* [Commands Extension API reference](https://discordpy.readthedocs.io/en/latest/ext/commands/api.html) + +## FAQ + +The documentation covers some basic FAQ's, and they are recommended to be read beforehand, and referenced before asking for help in case it covers your issue: +[https://discordpy.readthedocs.io/en/latest/faq.html](https://discordpy.readthedocs.io/en/latest/faq.html) + +## Usage Examples + +### Official Examples and Resources + +The official examples can be found on the [source repository](https://github.com/Rapptz/discord.py/tree/master/examples). + +The most commonly referenced examples are: + +* [Basic Commands Extension Bot](https://github.com/Rapptz/discord.py/blob/master/examples/basic_bot.py) +* [Background Task Example](https://github.com/Rapptz/discord.py/blob/master/examples/background_task.py) + +### Permissions Documentation + +* [Role Management 101](https://support.discordapp.com/hc/en-us/articles/214836687-Role-Management-101) +* [Full Permissions Documentation](https://discordapp.com/developers/docs/topics/permissions) + +### Community Examples and Resources + +The `discord.py` developer community over time have shared examples and references with each other.<br> +The following are a collated list of the most referenced community examples. + +#### Extensions / Cogs +* [Extension/Cog Example](https://gist.github.com/EvieePy/d78c061a4798ae81be9825468fe146be) - *Credit to EvieePy* +* [Available Cog Methods](https://gist.github.com/Ikusaba-san/69115b79d33e05ed07ec4a4f14db83b1) - *Credit to MIkusaba* + +#### Error Handling +* [Decent Error Handling Example](https://gist.github.com/EvieePy/7822af90858ef65012ea500bcecf1612) - *Credit to EvieePy* + +#### Embeds +* [Embed Live Designer and Visualiser](https://leovoel.github.io/embed-visualizer/) - *Credit to leovoel* +* [Embed Element Reference](https://cdn.discordapp.com/attachments/84319995256905728/252292324967710721/embed.png)<br> +{: width="200" } + +##### Using Local Images in Embeds +```py +filename = "image.png" + +f = discord.File("some_file_path", filename=filename) +embed = discord.Embed() + +embed.set_image(url=f"attachment://{filename}") +await messagable.send(file=f, embed=embed) +``` + +##### Embed Limits + +| **Element** | **Characters** | +| -------------- | ---------------------- | +| Title | 256 | +| Field Name | 256 | +| Field Value | 1024 | +| Description | 2048 | +| Footer | 2048 | +| **Entire Embed** | **6000** + +| **Element** | **Count** | +| -------------- | ---------------------- | +| Fields | 25 | + +#### Emoji + +- [Bot's Using Emoji](https://gist.github.com/scragly/b8d20aece2d058c8c601b44a689a47a0) + +#### Activity Presence + +- [Setting Bot's Discord Activity](https://gist.github.com/scragly/2579b4d335f87e83fbacb7dfd3d32828) + +#### Image Processing + +- [PIL Image Processing Example Cog](https://gist.github.com/Gorialis/e89482310d74a90a946b44cf34009e88) - *Credit to Gorialis* + +### Systemd Service +**botname.service**<br> +```ini +[Unit] +Description=My Bot Name +After=network-online.target + +[Service] +Type=simple +WorkingDirectory=/your/bots/directory +ExecStart=/usr/bin/python3 /your/bots/directory/file.py +User=username +Restart=on-failure + +[Install] +WantedBy=network-online.target +``` + +**Directory**<br> +`/usr/local/lib/systemd/system` + +**Service Commands**<br> +Refresh systemd after unit file changes:<br> +`systemctl daemon-reload` + +Set service to start on boot:<br> +`systemctl enable botname` + +Start service now:<br> +`systemctl start botname` + +Stop service:<br> +`systemctl stop botname` + +**Viewing Logs**<br> +All logs:<br> +`journalctl -u botname` + +Recent logs and continue printing new logs live:<br> +`journalctl -fu mybot` diff --git a/pydis_site/apps/content/resources/guides/python-guides/mutability.md b/pydis_site/apps/content/resources/guides/python-guides/mutability.md new file mode 100644 index 00000000..185dc87c --- /dev/null +++ b/pydis_site/apps/content/resources/guides/python-guides/mutability.md @@ -0,0 +1,55 @@ +--- +title: Mutability and Immutability in Python +description: "Mutable and immutable data types: what they are and how they work." +--- + +Consider this example: +```python +>>> s = "hello" +>>> s.upper() +'HELLO' +>>> s +'hello' +``` +This might break your expectations. +After all, you've called the `upper()` method on `s`, so why didn't it change? That's because strings are _immutable_: you can't change them in-place, only create new ones. +In this example, `.upper()` just cannot change the string stored in `s`. + +How do you make `s` store `'HELLO'` instead of `'hello'` then? That's possible. +Even though you can't change the original string, you can create a new one, which is like the old one, but with all letters in upper case. + +In other words, `s.upper()` doesn't change an existing string. +It just returns a new one. +```python +>>> s = 'hello' +>>> s = s.upper() +>>> s +'HELLO' +``` + +Let's examine what's going on here. +At first, the variable `s` refers to some object, the string `'hello'`. + + + +When you call `s.upper()`, a new string, which contains the characters `'HELLO'`, gets created. + + + +This happens even if you just call `s.upper()` without any assignment, on its own line: +```python +"hello".upper() +``` +In this case, a new object will be created and discarded right away. + +Then the assignment part comes in: the name `s` gets disconnected from `'hello'`, and gets connected to `'HELLO'`. + + + +Now we can say that `'HELLO'` is stored in the `s` variable. + +Then, because no variables refer to the _object_ `'hello'`, it gets eaten by the garbage collector. + + + +It means that the memory reserved for that object will be freed. If that didn't happen, the 'garbage' would accumulate over time and fill up all the RAM. diff --git a/pydis_site/apps/content/resources/guides/python-guides/parameters-and-arguments.md b/pydis_site/apps/content/resources/guides/python-guides/parameters-and-arguments.md new file mode 100644 index 00000000..45ad60b1 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/python-guides/parameters-and-arguments.md @@ -0,0 +1,290 @@ +--- +title: Function Parameters and Arguments in Python +description: An in-depth look at function parameters and arguments, and how to use them. +toc: 1 +--- + +A Python function is utilised in two steps: + +1. The function definition/signature (used just once). +2. The function invocation/call (used many times). + +The function definition uses parameters, whereas the function call uses arguments: + +```python +def foo(this_is_a_parameter): + print(this_is_a_parameter) + +foo(this_is_an_argument) +``` + +An important detail to be aware of is that by default any argument used to call a function in Python can be used as both a positional and a keyword argument—just not at the same time. +A function call may contain a mixture of positional and keyword arguments, and—unless otherwise specified—an argument can reference the parameters in the function definition positionally, or by name (keyword). + +# Positional Arguments + +```python +def foo(a, b, c): + print(a, b, c) + +>>> foo(1, 2, 3) +1 2 3 +``` + +In the above function definition we have three parameters `a`, `b`, and `c`. + +When we invoke the function with the arguments `1`, `2`, and `3`, the function will map these values in the exact order given to the parameters in the function definition. +With no keyword reference given they become positional arguments. + +# Keyword Arguments + +```python +def foo(a, b, c): + print(a, b, c) + +>>> foo(1, 2, 3) +1 2 3 + +>>> foo(c=3, b=2, a=1) +1 2 3 +``` + +As you can see, `foo(1, 2, 3)` and `foo(c=3, b=2, a=1)` are identical. +Referencing a function parameter by its name means that we are using a keyword argument. +The order in which keyword arguments are given does not matter. + +# Mixing Positional and Keyword Arguments + +So what happens if we want to mix the positional argument mapping with keyword arguments? + +Python prioritises the mapping of positional arguments to their parameter names before the mapping of keywords. + +```python +def foo(a, b, c): + print(a, b, c) + +>>> foo(1, c=3, b=2) +1 2 3 +``` + +Passing a keyword argument using the name of a parameter that has already been given will not work: + +```python +>>> foo(1, 2, a=3) +TypeError: foo() got multiple values for argument 'a' + +>>> foo(1, b=2, b=3) +SyntaxError: keyword argument repeated +``` + +Attempting to pass positional arguments after a keyword argument will also not work: + +```python +>>> foo(a=1, 2, 3) +SyntaxError: positional argument follows keyword argument +``` + +# Default Parameter Values + +Although the syntax is similar, these are not to be confused with keyword arguments.<br> +Default parameter values appear within the function definition and allow us to conveniently set a default value. This means that if any argument is omitted, its default value will be used as the argument. + +```python +def foo(a=0, b=0, c=0): + print(a, b, c) + +>>> foo() +0 0 0 + +>>> foo(1, 2, 3) +1 2 3 + +>>> foo(c=3, b=2) +0 2 3 + +>>> foo(1, c=3) +1 0 3 +``` + +Using default parameter values does not change how a function can be invoked with arguments: + +```python +>>> foo(1, 2, a=3) +TypeError: foo() got multiple values for argument 'a' + +>>> foo(1, b=2, b=3) +SyntaxError: keyword argument repeated + +>>> foo(a=1, 2, 3) +SyntaxError: positional argument follows keyword argument +``` + +You must specify any parameters without a default value before those with default values: + +```python +def foo(a=0, b): + ^ +SyntaxError: non-default argument follows default argument +``` + +# Positional-only Parameters +[Python 3.8](https://docs.python.org/3/whatsnew/3.8.html#positional-only-parameters) / [PEP 570](https://www.python.org/dev/peps/pep-0570/) introduces the possibility to specify which parameters are required to be positional-only via a bare `/` parameter within a function definition. + +```python +def foo(a=0, b=0, /, c=0, d=0): + print(a, b, c, d) +``` + +The parameters defined before the bare `/` are now considered to be positional-only and keyword mapping will no longer work on them.<br> +In the above function definition `a` and `b` are now positional-only parameters. + +These function calls will still work: + +```python +>>> foo() +0 0 0 0 + +>>> foo(1) +1 0 0 0 + +>>> foo(1, 2, 3, 4) +1 2 3 4 + +>>> foo(1, 2, d=4, c=3) +1 2 3 4 + +>>> foo(1, d=4, c=3) +1 0 3 4 + +>>> foo(c=3, d=4) +0 0 3 4 +``` + +However, attempting to pass keyword arguments for `a` or `b` will fail: + +```python +>>> foo(1, b=2, c=3, d=4) +TypeError: foo() got some positional-only arguments passed as keyword arguments: 'b' +``` + +### Q: Why is this useful? + +#### Keyword Argument Freedom + +Passing a keyword argument using the name of a parameter that has already been given will not work. +This becomes an issue if we require keyword arguments that use the same parameter names as defined in the function signature, such as via callback functions. + +```python +def foo(a, **kwargs): + print(a, kwargs) + +>>> foo(a=1, a=2) +SyntaxError: keyword argument repeated + +>>> foo(1, a=2) +TypeError: foo() got multiple values for argument 'a' +``` + +#### Backwards Compatibility + +Because Python allows that an argument by default can be either positional or keyword, a user is free to choose either option. +Unfortunately, this forces the author to keep the given parameter names as they are if they wish to support backwards compatibility, as changing the parameter names can cause dependent code to break. +Enforcing positional-only parameters gives the author the freedom to separate the variable name used within the function from its usage outside of it. + +```python +def calculate(a, b): + # do something with a and b + +>>> calculate(1, 2) +``` + +A user could call this function using `a` or `b` as keywords, which the author may have not intended: + +```python +>>> calculate(a=1, b=2) +``` + +However, by using `/`, the user will no longer be able to invoke using `a` or `b` as keywords, and the author is also free to rename these parameters: + +```python +def calculate(x, y, /): + # do something with x and y + +>>> calculate(1, 2) +``` + +# Keyword-only Parameters + +Similarly to enforcing positional-only parameters, we can also enforce keyword-only parameters using a bare `*` parameter. +The parameters defined after the bare `*` are now considered to be keyword-only. + +```python +def foo(a=0, b=0, /, c=0, *, d=0): + print(a, b, c, d) + +>>> foo() +0 0 0 0 + +>>> foo(1, 2, 3) +1 2 3 0 + +>>> foo(1, 2, d=4, c=3) +1 2 3 4 + +>>> foo(1, d=4, c=3) +1 0 3 4 +``` + +Although `c` can be either a positional or keyword argument, if we attempt to pass `d` as a non-keyword argument, it will fail: + +```python +>>> foo(1, 2, 3, 4) +TypeError: foo() takes from 0 to 3 positional arguments but 4 were given +``` + +At least one named parameter must be provided after a bare `*` parameter. +Writing a function definition similar to what is shown below would not make sense, as without the context of a named parameter the bare `*` can simply be omitted. + +```python +def foo(a=0, *, **kwargs): + ^ +SyntaxError: named arguments must follow bare * +``` + +### Q: Why is this useful? + +The main benefit of using keyword-only parameters is when they are used together with positional-only parameters to remove ambiguity. + +However, it may sometimes also be desirable to use keyword-only arguments on their own.<br> +If we were to expose a function as part of an API, we may want the parameter names to carry explicit meaning. + +Without using keyword names when invoking the function it can be unclear as to what the provided arguments are for. +Additionally, a user could also choose to interchange positional arguments with keyword arguments, which can potentially add to the confusion. + +```python +def update(identity=None, name=None, description=None): + # handle the parameters + +>>> update("value 1", "value 2", "value 3") + +>>> update(1234, "value 1", description="value 2") +``` + +Enforcing the keyword names is clearer, as it carries context without needing to look at the function definition: + +```python +def update(*, identity=None, name=None, description=None): + # handle the parameters + +>>> update(identity=1234, name="value 1", description="value 2") +``` + +# Summary + +* Unless otherwise specified, an argument can be both positional and keyword. +* Positional arguments, when provided, must be in sequence. +* Positional arguments must be used before keyword arguments. +* Keyword arguments may be in any order. +* A default parameter value is used when the argument is omitted. +* A bare `/` used as a parameter in a function definition enforces positional-only parameters to its left. +* A bare `*` used as a parameter in a function definition enforces keyword-only parameters to its right. diff --git a/pydis_site/apps/content/resources/rules.md b/pydis_site/apps/content/resources/rules.md new file mode 100644 index 00000000..27f03f07 --- /dev/null +++ b/pydis_site/apps/content/resources/rules.md @@ -0,0 +1,44 @@ +--- +title: Python Discord Rules +description: The rules of our community. +icon: fab fa-discord +--- +We have a small but strict set of rules on our server. Please read over them and take them on board. If you don't understand a rule or need to report an incident, please send a direct message to <code>@ModMail</code>! + +> 1. Follow the [Discord Community Guidelines](https://discordapp.com/guidelines) and [Terms Of Service](https://discordapp.com/terms). +> 2. Follow the [Python Discord Code of Conduct](/pages/code-of-conduct/). +> 3. Listen to and respect staff members and their instructions. +> 4. This is an English-speaking server, so please speak English to the best of your ability. +> 5. Do not provide or request help on projects that may break laws, breach terms of services, be considered malicious or inappropriate. Do not help with ongoing exams. Do not provide or request solutions for graded assignments, although general guidance is okay. +> 6. No spamming or unapproved advertising, including requests for paid work. Open-source projects can be shared with others in #python-general and code reviews can be asked for in a help channel. +> 7. Keep discussions relevant to channel topics and guidelines. + +# Nickname Policy + +In order to keep things pleasant and workable for both users and staff members, we enforce the following requirements regarding your nickname. + +1. No blank or "invisible" names +2. No slurs or other offensive sentiments +3. No noisy unicode characters - for example, z̯̯͡a̧͎̺̻̝͕̠l̡͓̫̣g̹̲o̡̼̘ or byte order marks +4. No nicknames designed to annoy other users + +Staff reserves the right to change the nickname of any user for any reason. Failure to comply with these requirements may result in you losing the right to change your nickname. We also reserve the right to discipline users with offensive usernames, regardless of the nickname they're using. + + +# Infractions + +We have a generally no-nonsense policy when it comes to our rules. If you notice someone breaking them, feel free to mention or DM a staff member and we'll try to deal with it as soon as possible. + +The possible actions we take based on infractions can include the following: + +* A public verbal or textual warning +* Forced nick changes, where appropriate +* A short temporary mute +* A long temporary mute +* A kick from the server +* A temporary ban from the server +* A permanent ban from the server + +While we do discuss more serious matters internally before handing out a punishment, simpler infractions are dealt with directly by individual staffers and the punishment they hand out is left to their own discretion. + +If you receive an infraction and would like to appeal it, send an e-mail to [[email protected]](mailto:[email protected]). diff --git a/pydis_site/apps/content/resources/security-notice.md b/pydis_site/apps/content/resources/security-notice.md new file mode 100644 index 00000000..e3630ae1 --- /dev/null +++ b/pydis_site/apps/content/resources/security-notice.md @@ -0,0 +1,37 @@ +--- +title: Security Notice +description: How vulnerabilities in our projects should be reported. +icon: fas fa-shield-alt +--- + +This is the security notice for all Python Discord repositories. +The notice explains how vulnerabilities should be reported. + +# Reporting a Vulnerability + +If you've found a vulnerability, we would like to know so we can fix it before it is released publicly. +**Do not open a GitHub issue for a found vulnerability**. + +Send details to [[email protected]](mailto:[email protected]) or through a Discord direct message to an Admin of Python Discord, including: + +* the website, page or repository where the vulnerability can be observed +* a brief description of the vulnerability +* optionally the type of vulnerability and any related [OWASP category](https://www.owasp.org/index.php/Category:OWASP_Top_Ten_2017_Project) +* non-destructive exploitation details + +We will do our best to reply as fast as possible. + +# Scope + +The following vulnerabilities **are not** in scope: + +* volumetric vulnerabilities, for example overwhelming a service with a high volume of requests +* reports indicating that our services do not fully align with “best practice”, for example missing security headers + +If you aren't sure, you can still reach out via email or direct message. + +--- + +This notice is inspired by the [GDS Security Notice](https://github.com/alphagov/.github/blob/master/SECURITY.md). + +*Version 2021-03* diff --git a/pydis_site/apps/content/resources/server-info/_info.yml b/pydis_site/apps/content/resources/server-info/_info.yml new file mode 100644 index 00000000..52df0f8d --- /dev/null +++ b/pydis_site/apps/content/resources/server-info/_info.yml @@ -0,0 +1,3 @@ +title: Server Information +description: Information on roles, tooling, and infrastructure at Python Discord. +icon: fab fa-discord diff --git a/pydis_site/apps/content/resources/server-info/roles.md b/pydis_site/apps/content/resources/server-info/roles.md new file mode 100644 index 00000000..716f5b1e --- /dev/null +++ b/pydis_site/apps/content/resources/server-info/roles.md @@ -0,0 +1,131 @@ +--- +title: Python Discord Server Roles +description: Information on the various roles at Python Discord. +icon: fab fa-discord +--- + +# Basic Roles + +### <span class="fas fa-circle" style="color:#6e6e6e"></span> Announcements +**Description:** A role pinged by Admins when an announcement is made in the `#announcements` channel. + +**How to get it:** Run the command `!subscribe` in the `#bot-commands` channel. +To unsubscribe, run `!unsubscribe` in the `#bot-commands` channel. + + +### <span class="fas fa-circle" style="color:#6e6e6e"></span> Voice Verified +**Description:** A role that lets people speak in voice channels. + +**How to get it:** Send `!voiceverify` in the `#voice-verification` channel. +There are multiple requirements listed there for getting the role. + +--- + +# Server Support Roles + +### <span class="fas fa-circle" style="color:#55cc6c"></span> Contributors +**Description:** A role given by staff to people who make substantial contributions to any of the server's [open source repositories](https://github.com/python-discord/) (Sir Lancebot, Python, the site, the branding repo, etc..).<br> +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. + +--- + +# Financial Support Roles + +### <span class="fas fa-circle" style="color:#46e6e8"></span> Nitro Boosters +**Description:** A vanity role for people who boost the server with their nitro subscription. + +**How to get it:** Boost the server with a nitro subscription. + + +### <span class="fas fa-circle" style="color:#46e6e8"></span> <span class="fas fa-circle" style="color:#3e7be9"></span> <span class="fas fa-circle" style="color:#2a82bd"></span> Patrons +**Description:** A vanity role for Patreon patrons of the server. + +**How to get it:** [Become a patron here!](https://www.patreon.com/python_discord) + +--- + +# Staff Roles +#### Note regarding staff roles: +##### Q: How do I apply for Helper/Moderator/Admin? +There is no application, and there are no public nominations. Staff keep an eye out for potential candidates, and people nominated (by staff) are put in a pool for evaluation. After a period of time the candidate for a certain role is voted on by staff higher up the hierarchy. + +##### Q: How do I become Helper? +See the description of a Helper. Being active in helping others, providing good help, contributing to our projects, and abiding by our rules go a long way towards catching staff attention, and make the server a better place for both beginners and advanced Python devs. + +##### Role Expectations +In addition to the informal descriptions below, we've also written down a more formal list of expectations that come with each staff role. While this list is mostly for internal use, you can read it [here](/pages/server-info/staff-role-expectations/). + +### <span class="fas fa-circle" style="color:#f85950"></span> Owners +**Description:** Owners of the server. + +### <span class="fas fa-circle" style="color:#ff784d"></span> Admins +**Description:** Staff who administrate the server, its function, its staff, and are involved in deciding the direction of the server. + +### <span class="fas fa-circle" style="color:#1abc9c"></span> Domain Leads +**Description:** Staff in charge of a certain domain such as moderation, events, and outreach. A lead will have a second role specifying their domain. + +### <span class="fas fa-circle" style="color:#8dc2ba"></span> Project Leads +**Description:** Staff in charge of a certain project that require special attention, such as a YouTube video series or our new forms page. + +### <span class="fas fa-circle" style="color:#ff9f1b"></span> Moderators +**Description:** Staff who moderate the server, enforce the rules, and coordinate with staff to support the server. + +### <span class="fas fa-circle" style="color:#a1d1ff"></span> PyDis Core Developers +**Description:** A role for staff who are critical contributors to the server's core projects, like the [bot](https://github.com/python-discord/bot) and the [site](https://github.com/python-discord/site), and are in charge of managing the repositories. + +### <span class="fas fa-circle" style="color:#a1d1ff"></span> DevOps +**Description:** A role for staff involved with the DevOps toolchain of our core projects. + +### <span class="fas fa-circle" style="color:#f8d188"></span> Project Teams +**Description:** Staff can join teams which work on specific projects in the organisation, such as our code jams, media projects, and more. + +### <span class="fas fa-circle" style="color:#eecd36"></span> Helpers +**Description:** This is the core staff role in our organization: All staff members have the Helpers role. + +In general, being a helper means that you provide substantial help for the server's function, and have a good understanding of the culture and rules of the server. + +Helpers assist in the help channels, demonstrate proficiency in the language, and have strong teaching and explanation skills. +Otherwise they might assist in other areas of the organization, such as being a core developer, events team member, or moderator. + +Being a helper is also more than just quantity of messages, it's about quality. We watch and we pick these people out of the crowd, because we believe that they're a valuable asset to the community, and want our users to know that they're someone that can be relied on for answers and help. + +--- + +# Code Jam Roles +### <span class="fas fa-circle" style="color:#f87dc8"></span> Code Jam Champions +**Description:** A vanity role for winners of past code jams. + +**How to get it:** Win a code jam! + + +### <span class="fas fa-circle" style="color:#28866c"></span> Code Jam Leaders +**Description:** A temporary role for the duration of a code jam given to team leaders. + +**How to get it:** Team leaders are picked from the participants by the Events Team, and assigned for the duration of a jam. + + +### <span class="fas fa-circle" style="color:#229939"></span> Code Jam Participants +**Description:** A temporary role for the duration of a code jam given to participants. + +**How to get it:** Qualify for and participate in a code jam. + +*Note: Similar roles may exist for a game jam.* + + +--- + +# Miscellaneous Roles + +### <span class="fas fa-circle" style="color:#9f3fee"></span> Partners +**Description:** Representatives of communities we are partnered with. For a list of partnered communities, see the `#partners` channel. + +*Note: Not related to [Discord Partners](https://discordapp.com/partners), which our server is currently a part of.* + +### <span class="fas fa-circle" style="color:#c77cfa"></span> Python Community +**Description:** Prominent people in the Python ecosystem. +Typically this will be people who have written books, people who speak at PyCon, YouTube content creators, podcasters, or notable contributors to a Python runtime or a major Python module. +These members will have a meta role attached to further explain why they have this role, for example `CPython: Core Developer`. diff --git a/pydis_site/apps/content/resources/server-info/staff-role-expectations.md b/pydis_site/apps/content/resources/server-info/staff-role-expectations.md new file mode 100644 index 00000000..286386d7 --- /dev/null +++ b/pydis_site/apps/content/resources/server-info/staff-role-expectations.md @@ -0,0 +1,67 @@ +--- +title: Staff Role Expectations +description: List of expectations that come with being on the staff team at Python Discord. +icon: fab fa-discord +--- + +This page has a list of expectations that come with having a certain staff role in our community. +While the term "expectations" may sound a bit formal, it's important to keep in mind that everyone with a staff role is just a volunteer and that this list is a way of having a clear overview of what each role entails. + +This document is mostly meant for internal reference. +If you want a more informal description of each staff role, take a look at our [roles page](/pages/server-info/roles/#staff-roles). + +## Expectations + +### <span class="fas fa-circle" style="color:#eecd36"></span> Helpers + +* In general, helpers participate in Python-related channels (e.g. Help Channels, Topical Channels) and help other members of our community. +* Helpers may also help the community by taking up organizational tasks. +* There are no real requirements for the level of activity a helper has to have, although we do expect their activity level to be more than "nothing". + +### <span class="fas fa-circle" style="color:#ff9f1b"></span> Moderators + +* Moderators moderate our community and participate in moderation discussions in our moderators channel. +* While moderators don't need to have high levels of activity, we do expect some form of consistent activity. +This means that consistently being active a few times a month is better than having one day with a lot of activity per year. +Having some kind of consistent activity helps moderators bond with the rest of the moderation team and helps them to stay up to date with the moderation policy. +* **Moderators are not required to fulfill the helper criteria in addition to this,** although it's is obviously appreciated if they do. + +### <span class="fas fa-circle" style="color:#ff784d"></span> Admins + +* Admins are expected to work on tasks that directly improve the community on a regular basis. +* Examples of these tasks include: + * Doing pull request reviews; + * Being involved in events; + * Overseeing road map items; + * Solving critical issues; + * Handling raids; + * Joining our meetings (if in a compatible timezone); + * Actioning issues on the organisation repo; + * Improving our infrastructure; + * Writing documentation or guides; + * Recruiting and on-boarding new staff members; + * Calling staff votes for nominees; + * Having one-on-ones with moderators. +* Admins are also expected to keep each other updated on the status of the tasks they are working on. + +### <span class="fas fa-circle" style="color:#f85950"></span> Owners + +**In addition to** the regular Admin criteria, Owners also have to: + +* Join staff/admin meetings as often as possible and lead those meetings. +* Help identify the most critical tasks and try to distribute them among the Admins during the weekly Admin meeting. +* Make sure that no one is "blocked" in performing their tasks. +* Ensure that the community isn’t neglecting important responsibilities. +* Manage partnerships, sponsorships and speak on behalf of the community in public settings. + +--- + +## Staff Management +First of all, it's important to appreciate that everything staff members do in this community is voluntary and the expectations listed above are not meant to change that. +**This means it's absolutely fine for all staff members to take breaks or vacations from their activities in the community when they need to.** +We will never hold it against someone if they are temporarily away from their responsibilities. + +At the same time, it's only natural for a community like ours that there's some amount of staff turnover as personal interests and circumstances change. +Going forward, we will periodically review the activity of individual staff members and open a dialogue with staff members who are currently not meeting the expectations to see what can be done. +It might happen that we come to conclusion that it's better for a staff member to step down from their current position. +Do note that there are no hard feelings involved if that happens; we just want to make sure that the current staffing reflects the people who are still interested in volunteering in this community. diff --git a/pydis_site/apps/content/views/page_category.py b/pydis_site/apps/content/views/page_category.py index 4031fde2..7427ec58 100644 --- a/pydis_site/apps/content/views/page_category.py +++ b/pydis_site/apps/content/views/page_category.py @@ -53,7 +53,7 @@ class PageOrCategoryView(TemplateView): context["subarticles"] = [] for entry in self.category_path.iterdir(): entry_info = {"path": entry.stem} - if entry.suffix == ".md": + if entry.suffix == ".md" and not entry.with_suffix("").is_dir(): entry_info["name"] = frontmatter.load(entry).metadata["title"] elif entry.is_dir(): entry_info["name"] = utils.get_category(entry)["title"] diff --git a/pydis_site/apps/events/views/page.py b/pydis_site/apps/events/views/page.py index eab2f462..1622ad70 100644 --- a/pydis_site/apps/events/views/page.py +++ b/pydis_site/apps/events/views/page.py @@ -21,6 +21,5 @@ class PageView(TemplateView): if not page_path.exists(): raise Http404 - print(f"events/{settings.EVENTS_PAGES_PATH.name}/{path}") return [f"events/{settings.EVENTS_PAGES_PATH.name}/{path}"] |