diff options
Diffstat (limited to 'README.md')
| -rwxr-xr-x | README.md | 347 |
1 files changed, 263 insertions, 84 deletions
@@ -3,105 +3,284 @@ [)](https://dev.azure.com/python-discord/Python%20Discord/_build/latest?definitionId=3) [](https://discord.gg/2B963hn) -A community project initially started for [Hacktoberfest 2018](https://hacktoberfest.digitalocean.com). A Discord bot for the Python Discord community which changes with the seasons, and provides useful event features. +A Discord bot for the Python Discord community which changes with the seasons, and provides useful event features. You can find our community by going to https://discord.gg/python ## Motivations -We know it can be difficult to get into the whole open source thing at first. To help out, we've decided to start a little community project during hacktober that you can all choose to contribute to if you're finding the event a little overwhelming, or if you're new to this whole thing and just want someone to hold your hand at first. -This later evolved into a bot that will be running all through the year, providing season-appropriate functionality and issues that beginners can work on. +We know it can be difficult to get into the whole open source thing at first. To help out, we started the HacktoberBot community project during [Hacktoberfest 2018](https://hacktoberfest.digitalocean.com) to help introduce and encourage members to participate in contributing to open source, providing a calmer and helpful environment for those who want to be part of it. + +This later evolved into a bot that runs all year, providing season-appropriate functionality and issues that beginners can work on. ## Getting started -If you are new to this you will find it far easier using PyCharm: +If you are new to this you may find it easier to use PyCharm. [What is PyCharm?](#what-is-pycharm) + +1. [Fork the Project](#fork-the-project) +2. [Clone & Install Packages](#clone--install-packages) +3. [Test Server](#test-server) +4. [Bot Account](#bot-account) +5. [Configuration](#configuration) +6. [Working with Git](#working-with-git) +7. [Pull Requests (PRs)](#pull-requests-prs) +8. [Further Reading](#further-reading) + +### What is PyCharm? + +PyCharm is a Python IDE (integrated development environment) that is used to make python development quicker and easier. + +Our instruction include PyCharm specific steps for those who have it, so you're welcome to give it a go if you haven't tried it before. + +You can download PyCharm for free [here](https://www.jetbrains.com/pycharm/). -### With PyCharm +### Requirements -First things first, what is PyCharm? -PyCharm is a Python IDE(integrated development environment) that is used to make python development quicker and easier overall. -So now your going to need to download it [here](https://www.jetbrains.com/pycharm/). +- [Python 3.7](https://www.python.org/downloads/) +- [Pipenv](https://pipenv.readthedocs.io/en/latest/install/#installing-pipenv) +- Git + - [Windows Installer](https://git-scm.com/download/win) + - [MacOS Installer](https://sourceforge.net/projects/git-osx-installer/files/) or `brew install git` + +### Fork the Project + +To fork this project, press the Fork button at the top of the [repository page](https://github.com/python-discord/seasonalbot): + + + +In your new forked repository, copy the git url by clicking the green `clone or download` button and then the copy link button: -#### 1. Fork -Ok, now you have got PyCharm downloading you are going to want to fork this project and find its git URL. To fork scroll to the top of the page and press this button. - -Then when you new forked repository loads you are going to want to get the Git Url by clicking the green `clone or download` button and then the copy link button as seen below:  -#### 2. Clone -Now that you have done that you are going to want to load up Pycharm and you'll get something like this without the left sidebar: - -You going to want to click Check Out from Version `Control->Git` and you'll get a popup like the one below: - -Now paste your link in, test the connection and hit `clone`. You now have a copy of your repository to work with and it should setup your Pipenv automatically. -#### 3. Bot -Now we have setup our repository we need somewhere to test out bot. -You'll need to make a new discord server: - -We need to make the applicaiton for our bot... navigate over to [discordapp.com/developers](https://discordapp.com/developers) and hit new application - -Now we have our discord application you'll want to name your bot as below: - -To actually make the bot hit `Bot->Add Bot->Yes, do It!` as below: - -Copy that Token and put to somewhere for safe keeping. - -Now to add that robot to out new discord server we need to generate an OAuth2 Url to do so navigate to the OAuth2 tab, Scroll to the OAUTH2 URL GENERATOR section, click the `Bot` checkbox in the scope section and finally hit the `administrator` checkbox in the newly formed Bot Permissions section. - -Copy and paste the link into your browser and follow the instructions to add the bot to your server - ensure it is the server you have just created. -#### 4. Run Configurations -Go back to PyCharm and you should have something a bit like below, Your going to want to hit the `Add Configuration` button in the top right. - -We are going to want to choose a python config as below: - -The first setting we need to change is script path as below (the start script may have changed from bot.py so be sure to click the right one - -Now we need to add an enviroment variable - what this will do is allow us to set a value without it affact the main repository. -To do this click the folder icon to the right of the text, then on the new window the plus icon. Now name the var `SEASONALBOT_TOKEN` and give the value the token we kept for safe keeping earilier. - -Now hit apply on that window and your ready to get going! -#### 5. Git in PyCharm -As we work on our project we are going to want to make commits. Commits are effectively a list of changes you made to the pervious version. To make one first hit the green tick in the top right - -1. Select the files you wish to commit -2. Write a brief description of what your commit is -3. See the actual changes you commit does here (you can also turn some of them off or on if you wish) -4. Hit commit - - -Now once you have made a few commits and are happy with your changes you are going to want to push them back to your fork. -There are three ways of doing this. -1. Using the VSC Menu `VSC->Git->Push` -2. Using the VSC popup <code>alt-\`->Push</code> -3. A shortcut: `ctrl+shift+K` - -You should get a menu like below: -1. List of commits -2. List of changed files -3. Hit Push to send to fork! - - -#### 6. Pull Requests (PR or PRs) -Goto https://github.com/python-discord/seasonalbot/pulls and the green New Pull Request button! + +### Clone & Install Packages + +#### With PyCharm: + +Load up PyCharm and click `Check Out from Version Control` -> `Git`: + + + +Test the URL with `Test` first and then click `Clone`. + + + +Note: PyCharm automatically detects the Pipfile in the project and sets up your packages for you. + +#### With console: + +Open a console at the directory you want your project to be in and use the git clone command to copy the project files from your fork repository: + +```bash +git clone https://github.com/yourusername/seasonalbot.git +``` + +Change your console directory to be within the new project folder (should be named `seasonalbot` usually) and run the pipenv sync command to install and setup your environment. +```bash +cd seasonalbot +pipenv sync --dev +``` + +### Test Server + +Create a test discord server if you haven't got one already: + + + +In your test server, ensure you have the following: + - `#announcements` channel + - `#dev-logs` channel + - `admins` role + - A channel to test your commands in. + +### Bot Account + +Go to the [Discord Developers Portal](https://discordapp.com/developers/applications/) and click the `New Application` button, enter the new bot name and click `Create`: + + + +In your new application, go to the `Bot` tab, click `Add Bot` and confirm `Yes, do it!`: + + + +Change your bot's `Public Bot` setting off so only you can invite it, save, and then get your token with the `Copy` button: + + + +Save your token somewhere safe so we can put it in the project settings later. + +In the `General Information` tab, grab the Client ID: + + + +Add the Client ID to the following invite url and visit it in your browser to invite the bot to your new test server: +``` +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. + +### Configuration + +#### Environment Variables: + +Create a `.env` file in your project root and copy the following text into it: +``` +SEASONALBOT_DEBUG=True +SEASONALBOT_TOKEN=0 +SEASONALBOT_GUILD=0 +SEASONALBOT_ADMIN_ROLE_ID=0 +CHANNEL_ANNOUNCEMENTS=0 +CHANNEL_DEVLOG=0 +``` + +Edit the variable values to match your own bot token that you put aside earlier, the ID of your Guild, the Announcements and Dev-logs channel IDs and the admin role ID. To get the role ID, you can make it mentionable, and send an escaped mention like `\@admin`: + + + +Note: These are only the basic environment variables. Each season will likely have their own variables needing to set, so be sure to check out the respective seasonal setups that you're working on. + +#### PyCharm Project Config: + +Copy the contents of your `.env` file first. +Click the `Add Configuration` button in the top right of the window. + + + +In the Configuration Window do the following: +1. Click the plus on the top left and select `Python`. +2. Add `bot` to the `Script path` input box. +5. Add `-m` to the `Interpreter options` input box. + + + +Click the folder icon for the `Environment variables` input box. In the new window, click the paste icon on the right side and click `OK`: + + + +Note: This should have your actual bot token and IDs as the values. If you copied the blank template from above and didn't update it, go back to do so first. + +Click `OK` to save and close the Configuration window. + +From now on, to run the bot you only need to click the `Run` button in the top right of PyCharm: + + + +#### In console: + +Since we have the `.env` file in the project root, anytime we run Pipenv and it'll automatically load the environment variables present within. + +To run the the bot, use: +```bash +pipenv run start +``` + +### Working with Git + +Working with git can be intimidating at first, so feel free to ask for any help in the server. + +For each push request you work on, you'll want to push your commits to a branch just for it in your repository. This keeps your `master` branch clean, so you can pull changes from the original repository without pulling the same commits you've already added to your fork. + +Once you finish a push request, you can delete your branch, and pull the changes from the original repository into your master branch. With the master branch updated, you can now create a new branch to work on something else. + +Note: You should never commit directly to the original repository's `master` branch. All additions to the `master` branch of the original repository **must** be put through a PR first. + +#### In PyCharm + +The PyCharm interface has a set of Git actions on the top right section of your workspace: + + + +In order from left to right these are: +- Update +- Commit +- History +- Revert + +As we work on our project we are going to want to make commits. Commits are effectively a log of changes you made over time. + +Before making any commits, you should make the branch for the PR you're about to work on. At the bottom of the PyCharm workspace, you'll see + +After making changes to the project files, you can commit by clicking the `Commit` button that's part of the git actions available on the top right 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. +3. See the actual changes you commit does, and optionally tick/untick specific changes to only commit the changes you want. +4. Click `Commit`. + + + +To create a new branch, + +Once you have made a few commits and are ready to push them to your fork repository, you can do any of the following: +- Use the VSC Menu `VSC` -> `Git` -> `Push` +- Use the VSC popup `alt-\ ` -> `Push` +- Use the Push shortcut: `CTRL+SHIFT+K` + +You should see a window listing commits and changed files. +Click `Push` when you're ready and it'll submit the commits to your forked repository. + +#### With console: + +When you create a commit, you will either want to add certain files for that commit, or apply all changes to every file. + +It's recommended to add only the files that you want to apply changes to before committing, rather than committing everything tracked. This brings more caution, and allows you to check first each file is relevant to the PR you're working on. + +To only add certain files, you will need to do that first before committing: +```bash +# create/use feature branch +git checkout some_new_feature + +# stage a single file +git add my_file.py + +# stage multiple files in one command +git add file_one.py file_two.py file_three.py + +# stage all files in current directory +git add . + +# remove a file from staging +git rm --cached wrong_file.py + +# finally commit +git commit -m "commit message here" +``` + +If you're absolutely sure that the tracked changes are all within scope of your PR, you can try using the commit all command. +To commit all changes across all tracked files, just use the `-a` flag: +```bash +git commit -a -m "commit message here" +``` + +### Pull Requests (PRs) + +Go to the [Pull requests](https://github.com/python-discord/seasonalbot/pulls) and click the green New Pull Request button: +  -Now you should hit `Compare across forks` then on the third dropdown select your fork (it will be `your username/seasonalbot`) then hit Create Pull request. -1[](https://i.imgur.com/N2X9A9v.png) -Now to tell other people what your PR does -1. Title - be concise and informative -2. Description - write what the PR changes as well as what issues it relates to -3. Hit `Create pull request` - -#### 7. Wait & further reading -At this point your PR will either be accepted or a maintainer might request some changes. +Click `Compare across forks`. +Change the `head fork` dropdown box to your fork (`your_username/seasonalbot`). +Click `Create pull request`. + + + +In the PR details, put a concise and informative title. +Write a description for the PR regarding the changes and any related issues. +Ensure `Allow edits from maintainers.` has been ticked. +Click `Create pull request`. + + -You can now read up some more on [Git](https://try.github.io), [PyCharm](https://www.jetbrains.com/help/pycharm/quick-start-guide.html), -or learn more about Python and Discord: [discord.py rewrite](https://discordpy.readthedocs.io/en/rewrite) +A maintainer or other participants may comment or review your PR, and may suggest changes. Communicate in the PR ticket and try ensure you respond timely on any questions or feedback you might get to prevent a PR being marked stale. +After a successful review by a maintainer, the PR may be merged successfully, and the new feature will deploy to the live bot within 10 minutes usually. -### Without PyCharm -The process above can be completed without PyCharm however it will be necessary to learn how to use Git, Pipenv and Environment variables. +### Further Reading -You can find tutorials for the above below: -- Git: [try.github](http://try.github.io/) -- Pipenv [Pipenv.readthedocs](https://pipenv.readthedocs.io) -- Environment Variables: [youtube](https://youtu.be/bEroNNzqlF4?t=27) +- [Git](https://try.github.io) +- [PyCharm](https://www.jetbrains.com/help/pycharm/quick-start-guide.html) +- [Pipenv](https://pipenv.readthedocs.io) +- [discord.py rewrite](https://discordpy.readthedocs.io/en/rewrite) +- [Environment Variables (youtube)](https://youtu.be/bEroNNzqlF4?t=27) |