aboutsummaryrefslogtreecommitdiffstats
path: root/pydis_site
diff options
context:
space:
mode:
authorGravatar kosayoda <[email protected]>2021-04-15 14:24:37 +0800
committerGravatar kosayoda <[email protected]>2021-04-15 14:24:37 +0800
commited4408e22a852f20a9994e8ee0c14b787b237c00 (patch)
treebb1f6f1674452b58fff6ebb96b009201d261f920 /pydis_site
parentAdd Python guide assets. (diff)
Migrate Python Discord guides.
Diffstat (limited to 'pydis_site')
-rw-r--r--pydis_site/apps/content/resources/guides/pydis-guides/code-reviews-primer.md164
-rw-r--r--pydis_site/apps/content/resources/guides/pydis-guides/contributing/bot.md1
-rw-r--r--pydis_site/apps/content/resources/guides/pydis-guides/help-channel-guide.md78
-rw-r--r--pydis_site/apps/content/resources/guides/pydis-guides/helping-others.md139
-rw-r--r--pydis_site/templates/events/pages/code-jams/6/rules.html3
5 files changed, 382 insertions, 3 deletions
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..55f167d0
--- /dev/null
+++ b/pydis_site/apps/content/resources/guides/pydis-guides/code-reviews-primer.md
@@ -0,0 +1,164 @@
+---
+title: "Code Reviews: A Primer"
+description: An introduction and guide to the world of code reviews!
+icon: fab fa-github
+---
+
+## 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/bot.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/bot.md
index 06bbddf0..98ee5e2f 100644
--- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/bot.md
+++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/bot.md
@@ -49,7 +49,6 @@ For any staff member, since you have write permissions already to the original r
# Test server and bot account
You will need your own test server and bot account on Discord to test your changes to the bot.
-<!-- TODO: Fix ALL Links -->
* [**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.
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..83322b3d
--- /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.
+
+![List of topical help channels](/static/images/content/help_channels/topical_channels.webp)
+
+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.
+
+![Available help channels](/static/images/content/help_channels/available_channels.webp)
+
+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.
+
+![Channel available message](/static/images/content/help_channels/available_message.webp)
+*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.
+
+![Channel dormant message](/static/images/content/help_channels/dormant_message.webp)
+*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.
+
+![Occupied help channels](/static/images/content/help_channels/occupied_channels.webp)
+
+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.
+
+![Dormant help channels](/static/images/content/help_channels/dormant_channels.webp)
+*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..28de3d67
--- /dev/null
+++ b/pydis_site/apps/content/resources/guides/pydis-guides/helping-others.md
@@ -0,0 +1,139 @@
+---
+title: Helping Others
+description: The staff 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/python-discord-code-of-conduct/
+---
+
+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?"
+> *helper1 proceeds to paste 40 lines of sudoku solving code*
+> **helper2**: "Are you familiar with lists / recursion / backtracking?"
+> *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?"
+> **helper1**: "You can do it like so:"
+>
+> for element in your_list:
+> print(element)
+>
+> **helper2**: "You can also do it like this:"
+>
+> 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/templates/events/pages/code-jams/6/rules.html b/pydis_site/templates/events/pages/code-jams/6/rules.html
index 727d98be..2f1d1e28 100644
--- a/pydis_site/templates/events/pages/code-jams/6/rules.html
+++ b/pydis_site/templates/events/pages/code-jams/6/rules.html
@@ -62,9 +62,8 @@
</li>
</ol>
- <!-- TODO: After code of conduct and rules page is migrated, change these URLs. -->
<blockquote>
- Please note that our regular <a href="/pages/rules/">community rules</a> and <a href="/pages/code-of-conduct/">code of conduct</a>
+ Please note that our regular <a href="/pages/rules/">community rules</a> and <a href="/pages/python-discord-code-of-conduct/">code of conduct</a>
also apply during the event and that we reserve the right to make changes to these rules at any time.
</blockquote>
{% endblock %}