Skip to content

Latest commit

 

History

History
executable file
·
300 lines (189 loc) · 11.6 KB

README.md

File metadata and controls

executable file
·
300 lines (189 loc) · 11.6 KB
Raw

SeasonalBot

Build Status Discord

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 started the HacktoberBot community project during Hacktoberfest 2018 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

Please ensure you read the contributing guidelines in full.

If you are new to this you may find it easier to use PyCharm. What is PyCharm?

  1. Fork the Project
  2. Clone & Install Packages
  3. Test Server
  4. Bot Account
  5. Configuration
  6. Working with Git
  7. Pull Requests (PRs)
  8. 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.

Requirements

Fork the Project

To fork this project, press the Fork button at the top of the repository page:

In your new forked repository, copy the git url by clicking the green clone or download button and then the copy link 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:

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.

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 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.
  3. 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:

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.

Precommit Hook

Projects need to pass linting checks to be able to successfully build and pass as in push requests.
Read CONTRIBUTING.md for more details.

To install the precommit hook, which checks your code before commits are submitted, do the following:

pipenv run precommit

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 the current git branch, which you can click to show a menu of actions. You can click New Branch to create a new one, and name it something short that references what the PR is to accomplish. Before making new branches, be sure you change to master and ensure it's up to date before creating a new branch.

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:

# 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:

git commit -a -m "commit message here"

Pull Requests (PRs)

Go to the Pull requests and click the green New Pull Request button:

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.

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.

Further Reading