diff options
| author |  kosayoda <[email protected]> | 2021-04-14 23:30:52 +0800 |
|---|---|---|
| committer | kosayoda <[email protected]> | 2021-04-14 23:30:52 +0800 |
| commit | 85f60399a9e87236ed5be068522d6fab8c91cc22 (patch) | |
| tree | a5d7484aba3e5828bbdcff211e7925914d1fc7e1 /pydis_site/apps | |
| parent | Use the more consistent highlight. (diff) | |
Migrate contributing pages.
Some guides were updated to fit current PyCharm UI and to keep up with
Seasonalbot -> Sir-Lancebot changes.
Diffstat (limited to 'pydis_site/apps')
24 files changed, 1733 insertions, 0 deletions
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..321e9b5d --- /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. +[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..06bbddf0 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/bot.md @@ -0,0 +1,210 @@ +--- +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. + +<!-- 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. + +### 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. + +--- +# 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..d13a838f --- /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`. + +2. Enter the URL of your forked repository. +3. Change the directory if you desire and click `Clone`. + + +--- + +## 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..b29097fd --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/docker.md @@ -0,0 +1,119 @@ +--- +title: Working with Docker & Docker Compose +description: Guide to running our projects with Docker and Docker CE. +icon: fab fa-docker +--- + +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** +Your Docker service is either not started, or you haven't yet installed Docker. + +**Solution** +[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** +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** +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** +Windows has not been configured to share drives with Docker. + +**Solution** +> 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. + + +2. Click the "Shared Drives" label at the left, and check the box next to the drive letter where your project is stored. + + +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..c029760c --- /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. + +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..f1d53c5a --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/hosts-file.md @@ -0,0 +1,45 @@ +--- +title: Preparing Your Hosts file +description: How to setup your hosts file for project usage. +icon: fas fa-cog +--- + +# 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..ff981110 --- /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..b29391e5 --- /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: + +Click the `Issues` tab in a repository: + + +Click `New Issue`: + + +Enter the title and description for your issue, then click `Submit new issue`: +{: 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..b2324e9e --- /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.**](./sir-lancebot-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..543b0cb6 --- /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." +**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." +**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..c0f55053 --- /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?** +> The integrated Git tool built into PyCharm offers a more visual and abstract way to use Git to manage your files. +> 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..e25a783b --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/working-with-git/cli.md @@ -0,0 +1,131 @@ +--- +title: Working with the Git CLI +description: Basic workflow when using the git CLI. +--- + +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. + +#### Only done once per project +* [Adding the Upstream Remote](#adding-the-upstream-remote) + +#### Commonly done +* [Creating a New Branch](#creating-a-new-branch) +* [Staging Changes](#staging-changes) +* [Discarding Changes](#discarding-changes) +* [Committing Changes](#committing-changes) +* [Pushing Commits](#pushing-changes) +* [Pulling Changes](#pulling-changes) + +--- + +## 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..c38e5f62 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/working-with-git/pycharm.md @@ -0,0 +1,75 @@ +--- +title: Working with Git in PyCharm +description: Basic workflow when using git in PyCharm. +--- + +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. + +#### Only done once per project +* [Adding the Upstream Remote](adding-the-upstream-remote) + +#### Done for each feature +* [Creating a New Branch](creating-a-new-branch) +* [Committing Changes](committing-changes) +* [Pushing Changes](pushing-changes) + +#### Done whenever needed +* [Pulling Changes](pulling-changes) + +--- + +## 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...`. + +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. + +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`. + + +--- + +## 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`. + + +--- + +## 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/security-notice.md b/pydis_site/apps/content/resources/security-notice.md new file mode 100644 index 00000000..15b88cb0 --- /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-lock +--- + +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* |