Browse Source

Update README and CONTRIBUTING

main
parent
commit
c4d52f7006
Signed by: StDingenskirchen GPG Key ID: 14FE9712CC42FE8B
2 changed files with 55 additions and 40 deletions
  1. +51
    -26
      CONTRIBUTING.md
  2. +4
    -14
      README.md

+ 51
- 26
CONTRIBUTING.md View File

@ -10,45 +10,70 @@ use [Nix] wrapping [poetry]. Complex input beyond the capabilities of discordpy
[TOML], which is the least painful to write markup format i could come up with that has Python
bindings.
## Getting Started
## Getting Started: Coding
If you want to add a new feature, please start out by creating an issue and opening a discussion
about it. Pull Requests coming out of the blue won't be accepted. If you want to pick up an existing
issue for implementation, leave a note there that you're doing so so that no one else starts on the
same work as you do accidentally. Then, you can start actually working on it:
1. Install the dependencies: If you're on Linux or Mac, you'll want [Nix], if you're on Windows,
just [poetry] should do fine. You will need git in any case. You probably also want a visual git
interface, e.g. that of Visual Studio Code (which is a fine code editor).
2. Create a fork, that is, a copy of BLIMP's repository, for your own GitHub account. There's a
### 1. Prerequisites
If you're on Linux or Mac, you'll want [Nix], if you're on Windows, just [poetry] should do fine. If
you don't install Nix, you will need to check that you have [Python 3.9] or later available.
You will need [git] in any case. You probably also want a visual git interface, e.g. that of Visual
Studio Code (which is a fine code editor too).
You also need a Discord bot token, which you can get from the [Applications page] of your Discord
account. You might also need to create a server to test your bot in.
### 2. Forking & Cloning
1. Create a fork, that is, a copy of BLIMP's repository, for your own GitHub account. There's a
button somewhere on the top right on the repository main site.
2. Clone your fork of BLIMP into a directory on your PC: `git clone git@github.com:yourname/blimp`.
3. Switch over into that directory and spin up a development shell using either `nix-shell` or
`poetry shell`, depending on what you installed earlier. If you didn't install Nix, you'll also need
to make sure you have Python 3.9 installed aside from poetry.
4. Create a new branch for your feature: `git checkout -b anything_goes_here_it_doesnt_matter`. This
allows you to develop your feature concurrently to others working on other things.
5. Make your changes. To test them, you need a discord bot, which you can create on the
[Applications page] of your Discord account. You also need a server to test in. You can copy all the
necessary IDs and the bot token into `blimp.cfg.example` and save it as `blimp.cfg`. Then, in your
development shell, you'll be able to run your testing instance with `python39 -m blimp`. If you need
help with something while making the changes, don't hesitate to ask!
6. Once your changes are complete, run `isort blimp; black blimp` to format the codebase and
`pylint blimp` to see potential issues with your code. Once happy with the results, stage your
changes with git: `git add src/file1 src/file2 src/filen` and commit them: `git commit`. Please
don't alter the version number of BLIMP, we'll change it after the merge is done.
7. Push your work to your fork: `git push origin the-previously-picked-branch-name`. Then, go to the
2. Clone your fork of BLIMP into a directory on your PC by following the instructions listed under
"Code"→"Clone" on your fork's GitHub page.
### 3. Initial Setup
1. Switch over into the directory you cloned BLIMP into and spin up a development shell using either
`nix-shell` or `poetry shell`, depending on what you installed earlier. This might take a while, so
grab yourself a cup of tea.
2. Open the file `blimp.cfg.example` with your text editor and update at the very least the value of
`discord.token` with the bot token you got from Discord. Without this, your bot won't be able to log
in. You might also want to change other values. Save the file as `blimp.cfg` in the same folder.
3. In your development shell, run `python -m blimp` to start the bot for the first time. It will
automatically create the needed database.
### 4. Development Workflow
1. Create a new branch for your feature: `git checkout -b just-write-stuff-into-here`. This allows
you to develop your feature concurrently to others working on other things.
2. Make whatever changes you think appropriate. If you need help with something while making the
changes, don't hesitate to ask in the support server or the issue you're working on! When you save
your changes, use `Ctrl-C` in your development shell to stop the bot and repeat `python -m blimp` to
restart it with your changes applied.
3. Once your changes are complete, run `isort blimp` and `black blimp` in your development shell to
format the codebase, followed by `pylint blimp` to see potential issues with your code. Once happy
with the results, stage your changes with git: `git add src/file1 src/file2 src/file_n` and commit
them: `git commit`. Please don't alter the version number of BLIMP, we'll change it after the merge
is done.
4. Push your work to your fork: `git push origin the-previously-picked-branch-name`. Then, go to the
[pull requests] page and click the button that should appear to create a pull request based on your
recently pushed branch. Write "hi" or something. If you think something you've done warrants extra
explanations, do so.
8. Wait for a review. If you want to change more things in your branch, add more commits; don't edit
recently pushed branch. Write a short summary of your changes; if you think something you've done
warrants extra explanations, do so.
7. Wait for a review. If you want to change more things in your branch, add more commits; don't edit
your previous ones.
9. Wait for your request to be merged into the `main` branch.
10. Reset your working copy by checking out `main`: `git checkout main` and pulling from the main
8. Wait for your request to be merged into the `main` branch.
9. Reset your working copy by checking out `main`: `git checkout main` and pulling from the main
repository: `git pull upstream main`.
[discordpy]: https://github.com/Rapptz/discord.py/
[Python 3.9]: https://www.python.org/downloads/
[git]: https://git-scm.com/
[Nix]: https://nixos.org
[poetry]: https://python-poetry.org
[Applications page]: https://discord.com/developers/applications
[pull requests]: https://github.com/The-Valley-Discord/blimp/pulls
[TOML]: https://toml.io/

+ 4
- 14
README.md View File

@ -4,20 +4,10 @@
A Discord misc. tooling Bot, spiritual successor of Bampersand.
To run, you need [Nix](https://nixos.org/). BLIMP is written in Python.
Running in **development**:
```
$ cd blimp
$ nix-shell
[nix-shell:/blimp]$ python -m blimp
```
Building the package for **production**:
```
$ cd blimp
$ nix build
$ ./result/bin/blimp
```
For detailed instructions on how to contribute, please see [CONTRIBUTING.md](CONTRIBUTING.md).
For instructions on hosting your own instance, please see the
[official manual's section on it](https://dingenskirchen.systems/blimp/manual/#self-hosting).
---
@ -34,4 +24,4 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
along with this program. If not, see <https://www.gnu.org/licenses/>.

Loading…
Cancel
Save