Skip to content

Commit 2ea9ba2

Browse files
authored
Expand docs to clarify unknown details (#22)
* Add missing dev guide reference * Add a brief user guide * Add and improve on dev guide docs * Move contributing into `.github` * Update content of README.md and docs/index.rst
1 parent 12b7715 commit 2ea9ba2

File tree

11 files changed

+886
-18
lines changed

11 files changed

+886
-18
lines changed

.github/CONTRIBUTING.md

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Contributing
2+
3+
Thank you for your interest in contributing to this project!
4+
The rest of the document can be found [here](https://rodhaj.readthedocs.io/en/latest/dev-guide/contributing.html).

CONTRIBUTING.md

-3
This file was deleted.

README.md

+4-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Rodhaj
22

3+
[![CodeQL](https://github.com/transprogrammer/rodhaj/actions/workflows/codeql.yml/badge.svg)](https://github.com/transprogrammer/rodhaj/actions/workflows/codeql.yml) [![Lint](https://github.com/transprogrammer/rodhaj/actions/workflows/lint.yml/badge.svg)](https://github.com/transprogrammer/rodhaj/actions/workflows/lint.yml) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=transprogrammer_rodhaj&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=transprogrammer_rodhaj) [![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=transprogrammer_rodhaj&metric=ncloc)](https://sonarcloud.io/summary/new_code?id=transprogrammer_rodhaj)
4+
35
A improved, modern version of ModMail for Transprogrammer
46

57
> [!IMPORTANT]
@@ -18,11 +20,11 @@ sends a direct message to the bot, Rodhaj will create a new ticket (which is a f
1820
internally for staff to view. From there, each ticket is tied with a member and DMs from Rodhaj will be processed and sent to their respective tickets.
1921

2022
To ensure that staff will be able to respond, each active staff is randomly assigned
21-
to a particular ticket. This ensures that tickets are evenly distributed among staff. Staff are free to swap and work on multiple tickets as needed. Once a ticket is closed, the staff will be automatically unassigned from the ticket, and a new DM to Rodhaj will prompt the user to create a new ticket.
23+
to a particular ticket. This ensures that tickets are evenly distributed among staff. Staff are free to swap and work on multiple tickets as needed. Once a ticket is closed, the staff will be automatically unassigned from the ticket, and a new DM to Rodhaj will prompt the user to create a new ticket. It's designed to be a replacement to ModMail.
2224

2325
## Contributing
2426

2527
Contributions to Rodhaj are always welcomed. These could be as small as
2628
changing documentation to adding new features. If you are interested to start
27-
the process, please consult the [developer guide](CONTRIBUTING.md) before
29+
the process, please consult the [contributing guidelines](.github/CONTRIBUTING.md) before
2830
you get started.

docs/_static/assets/trunk-workflow.svg

+657
Loading

docs/dev-guide/contributing.rst

+113
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
============
2+
Contributing
3+
============
4+
5+
Thank you for your interest in contributing to this project!
6+
7+
The following is a set of guidelines for contributing to this project.
8+
These are just guidelines, not rules.
9+
10+
Ways You Can Contribute
11+
=======================
12+
13+
The ways you can contribute are not only limited to code changes, but so much more.
14+
Some of the ways you can contribute are:
15+
16+
- Reporting a bug
17+
- Discussing the current state and future of the project
18+
- Submitting a fix
19+
- Proposing new features
20+
- Improving or editing documentation
21+
22+
Note that if you plan on proposing new features, please first discuss them with the project owners on the issues page.
23+
24+
Writing Good Bug Reports
25+
========================
26+
27+
Please be aware of the following when you submit a bug report:
28+
29+
1. Ask on the server first (this is preferred). If you are unsure about an issue, please contact the dev lead (Noelle) for clarification.
30+
2. Don't open duplicate issues. Please search your issue to see if it has been asked already. Duplicate issues will be closed.
31+
3. When filing a bug about exceptions or tracebacks, please include the complete traceback. Without the complete traceback the issue might be unsolvable and you will be asked to provide more information.
32+
33+
If a bug report is not clear enough, or missing these information, then more than likely
34+
it'll take longer to fix the bug, or it'll be closed. More than likely clarification will
35+
be asked in order to aid in this process.
36+
37+
Submitting Code
38+
===============
39+
40+
Submitting code is done through pull requests. Please ensure that the pull request
41+
focuses on a single aspect and doesn't leave the scope of that aspect. You'll have to
42+
keep in mind about the following guidelines when submitting code.
43+
44+
Programming Style
45+
-----------------
46+
47+
In order to keep the code unified, `Black <https://github.com/psf/black>`_, `AutoFlake <https://github.com/PyCQA/autoflake>`_, and
48+
`Isort <https://github.com/PyCQA/isort>`_ are used to format code to a consistent style.
49+
In addition, linters such as `Pyright <https://github.com/microsoft/pyright>`_ and `Ruff <https://github.com/astral-sh/ruff>`_ are
50+
used to ensure that code quality is kept to its standards and properly type hinted. The formatters are ran automatically within a pre-commit
51+
hook, which is ran before every commit. If you wish to run the pre-commit hook manually, you can run the following command:
52+
53+
.. code-block:: bash
54+
55+
pre-commit run --all-files
56+
57+
.. note::
58+
59+
This project does follow the guidelines of `PEP-8 <https://peps.python.org/pep-0008/>`_ strictly. Please ensure that
60+
your code is in accordance with PEP-8.
61+
62+
Static Code Analyzers
63+
---------------------
64+
65+
In addition to the tools mentioned, `SonarCloud <https://sonarcloud.io/>`_ is also used to analyze the codebase.
66+
If there is a issue raised by SonarCloud, please fix it. If you are unsure about the issue,
67+
please contact the dev lead (Noelle) for clarification.
68+
69+
Pull Request Details
70+
--------------------
71+
72+
Source Control Branching Model
73+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
74+
75+
.. figure:: /_static/assets/trunk-workflow.svg
76+
:alt: Trunk Based Development Workflow
77+
:align: center
78+
79+
The model used for source control branching is `trunk-based <https://www.atlassian.com/continuous-delivery/continuous-integration/trunk-based-development>`_.
80+
The ``main`` branch is known to contain working code, and thus cannot be touched directly.
81+
82+
.. _Branch Naming Convention:
83+
84+
Branch Naming Convention
85+
^^^^^^^^^^^^^^^^^^^^^^^^
86+
87+
When you create a branch, please use the following naming convention:
88+
89+
.. code-block::
90+
91+
<name>/<type>
92+
93+
94+
``<name>`` is your name (you can use your GitHub name) and ``<type>`` is a concise one to three word description of the branch.
95+
For example, if a pull request has the name ``noelle/docs``, this indicates that the branch is created and owned by Noelle,
96+
and the purpose of the branch is to update documentation.
97+
98+
Pull Request Checklist
99+
^^^^^^^^^^^^^^^^^^^^^^
100+
101+
When you create a pull request, please ensure that the following is done:
102+
103+
1. Ensure that you have forked the repository and created a branch from ``main`` with the correct naming conventions as mentioned :ref:`above <Branch Naming Convention>`.
104+
2. Make sure that you have noted the changes in the ``changelog.md`` file.
105+
3. Your code is properly formatted and linted (and all workflows are passing).
106+
107+
Git Commit Guidelines
108+
---------------------
109+
110+
1. Use present tense and imperative mood when writing commit messages. For example, ``Add new feature`` instead of ``Added new feature``.
111+
2. Reference issues or pull requests outside of the first line.
112+
a. Please use the shorthand ``#123`` and not the full URL.
113+
3. Commits that need to skip the CI workflows must be prefixed with ``[skip ci]``.

docs/dev-guide/faq.rst

+9-3
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
1+
===
12
FAQ
2-
---
3+
===
34

45
This is a list of frequently asked questions.
56
If you have a question that is not answered here,
@@ -10,8 +11,8 @@ Slash Commands
1011

1112
Questions regarding slash commands and how they operate in ``discord.py``.
1213

13-
Where are the slash commands?
14-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
14+
Where Are The Slash Commands?
15+
-----------------------------
1516

1617
Unlike other frameworks, discord.py **does not** automatically sync slash commands
1718
for you (as slash commands need to be synced to Discord and are handled by them).
@@ -28,3 +29,8 @@ such as the following:
2829
2930
To see details information on why the practice of automatically syncing commands is bad,
3031
see `this gist <https://gist.github.com/No767/e65fbfdedc387457b88723595186000f>`_ for more.
32+
33+
.. note::
34+
35+
If you do not understand what is syncing,
36+
please read the `syncing guide <https://gist.github.com/No767/e65fbfdedc387457b88723595186000f#a-primer-on-syncing>`_.

docs/dev-guide/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,5 @@ Rodhaj offers a developer guide so future developers can easily get started with
88
:maxdepth: 2
99

1010
intro
11+
contributing
1112
faq

docs/dev-guide/intro.rst

+13-9
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ Introduction
55
This is the documentation for Rodhaj, the modern ModMail bot for the transprogrammer server.
66

77
Software Requirements
8-
---------------------
8+
=====================
99

1010
Before you get started, please ensure you have the following installed:
1111

@@ -36,12 +36,13 @@ For a debian-based system, you can install them with the following command:
3636
Windows support should work but is not tested.
3737

3838
Setup
39-
-----
39+
=====
4040

4141
**Rodhaj only supports Python 3.9 or higher**
4242

4343
.. important::
4444
Ensure that you are in the root of the repo throughout this process
45+
and have the database running
4546

4647
1. Fork and clone the repo
4748

@@ -71,8 +72,8 @@ Setup
7172
poetry run python bot/launcher.py
7273
7374
Database
74-
^^^^^^^^
75-
75+
--------
76+
7677
The following SQL queries can be used to create the user and database:
7778

7879
.. code-block:: sql
@@ -86,9 +87,12 @@ The following SQL queries can be used to create the user and database:
8687
the PostgreSQL server. If you decide not to use Docker, you
8788
will need to manually create the database as shown below
8889

89-
Basic Concepts
90-
--------------
90+
Using Docker
91+
^^^^^^^^^^^^
92+
93+
If you decide to use Docker to run the local PostgreSQL server, then a
94+
pre-built Docker Compose file is provided. Simply run the following:
95+
96+
.. code-block:: bash
9197
92-
Rodhaj works by implementing commands, which
93-
are used staff. And Rodhaj takes care of assigning threads, creating tickets, etc.
94-
More will be provided in-depth in other parts of the documentation.
98+
docker compose -f docker-compose-dev.yml up -d

docs/index.rst

+18-1
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ Rodhaj
1111
:hidden:
1212
:caption: Guides
1313

14+
user-guide/index
1415
dev-guide/index
1516

1617
A improved, modern version of ModMail for the Transprogrammer community.
@@ -20,6 +21,15 @@ but with a completely new, improved codebase and features. It works just like Re
2021
where users can send messages to the bot and the bot will relay it to the server's staff team. This allows
2122
for a process of communicating from user to staff to be streamlined, and securely done.
2223

24+
Features
25+
--------
26+
27+
Rodhaj offers these features in addition to ones found on ModMail:
28+
29+
- Advanced tags system
30+
- Automatic ticket assignment (with manual override)
31+
- Modern touch using forum channels, webhooks, and best practices
32+
- Customizable settings
2333

2434
What's Different?
2535
-----------------
@@ -34,4 +44,11 @@ Thus, **this bot has no invite**.
3444
Contributing
3545
------------
3646

37-
If you would like to contribute to Rodhaj, please read the guides below.
47+
If you would like to contribute to Rodhaj, please read the guide below.
48+
49+
- :doc:`dev-guide/index`
50+
51+
Next Steps
52+
-----------
53+
54+
- Learn about Rodhaj's features in the :doc:`user-guide/features` guide.

docs/user-guide/features.rst

+57
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
============
2+
Features
3+
============
4+
5+
This document describes the features of Rodhaj and an general description on them.
6+
7+
User Features
8+
=============
9+
10+
These are the publicly available features that an user can use.
11+
12+
Closing
13+
-------
14+
15+
Naturally as communications come to an end, users cannot simply leave the ticket stale.
16+
In order to close a ticket, it is recommended to use the ``?close`` command.
17+
The ticket will be marked as closed to the user and subsequently closed on the ticket pool.
18+
Once closed, a ticket cannot be reopened. If a staff uses the ``?close`` command,
19+
the active ticket will be closed and the user will be notified of the closure.
20+
21+
Note that there is no plans to support timed closures, as it is a design feature fudmentally flawed for this type of command.
22+
23+
Administrative Features
24+
=======================
25+
26+
Replying
27+
--------
28+
29+
In order to reply to a thread, use the ``?reply`` command. This will send a message to the user within an active ticket.
30+
Without executing this command, all messages will be seen as internal in the ticket. Images attachments, emojis, and stickers
31+
are supported.
32+
33+
.. note::
34+
35+
Unlike ModMail, **none** of the messages sent with the ``?reply`` command, internally in the ticket, or by the user to staff
36+
will be logged. This is to ensure that the privacy of the user is respected. Staff can always look back at an closed ticket
37+
within the ticket channel if they need to refer to a particular message.
38+
39+
Tags
40+
----
41+
42+
To aid with frequent responses, tags can be used. Tags do not have an owner associated, thus they can be used and edited by any staff member.
43+
Tags can be used by using the ``?tag <tag name>`` command, where ``<tag name>`` represents the name of the tag that should be used.
44+
By default, they are sent directly to the user who is in the ticket, but can be sent internally by using the ``--ns`` flag.
45+
46+
47+
Ticket Assignee
48+
---------------
49+
50+
As tickets are created, they are assigned to a staff member. This is done to ensure that the ticket is not left unattended.
51+
The ticket assignee is randomly selected from the staff members who are online. If no staff members are online, then there will not be a ticket assignee.
52+
In order to manually assign a ticket, the ``?assign`` command can be used. This will assign the ticket to the staff member who executed the command.
53+
54+
When the ticket is created, the staff is notified in a channel that logs events related to tickets. This is done to ensure that the staff is aware of the ticket
55+
and can act accordingly.
56+
57+

docs/user-guide/index.rst

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
================
2+
User Guide
3+
================
4+
5+
This document represents the user guide for Rodhaj
6+
7+
.. toctree::
8+
:maxdepth: 2
9+
10+
features

0 commit comments

Comments
 (0)