-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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
- Loading branch information
Showing
11 changed files
with
886 additions
and
18 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
# Contributing | ||
|
||
Thank you for your interest in contributing to this project! | ||
The rest of the document can be found [here](https://rodhaj.readthedocs.io/en/latest/dev-guide/contributing.html). |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,113 @@ | ||
============ | ||
Contributing | ||
============ | ||
|
||
Thank you for your interest in contributing to this project! | ||
|
||
The following is a set of guidelines for contributing to this project. | ||
These are just guidelines, not rules. | ||
|
||
Ways You Can Contribute | ||
======================= | ||
|
||
The ways you can contribute are not only limited to code changes, but so much more. | ||
Some of the ways you can contribute are: | ||
|
||
- Reporting a bug | ||
- Discussing the current state and future of the project | ||
- Submitting a fix | ||
- Proposing new features | ||
- Improving or editing documentation | ||
|
||
Note that if you plan on proposing new features, please first discuss them with the project owners on the issues page. | ||
|
||
Writing Good Bug Reports | ||
======================== | ||
|
||
Please be aware of the following when you submit a bug report: | ||
|
||
1. Ask on the server first (this is preferred). If you are unsure about an issue, please contact the dev lead (Noelle) for clarification. | ||
2. Don't open duplicate issues. Please search your issue to see if it has been asked already. Duplicate issues will be closed. | ||
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. | ||
|
||
If a bug report is not clear enough, or missing these information, then more than likely | ||
it'll take longer to fix the bug, or it'll be closed. More than likely clarification will | ||
be asked in order to aid in this process. | ||
|
||
Submitting Code | ||
=============== | ||
|
||
Submitting code is done through pull requests. Please ensure that the pull request | ||
focuses on a single aspect and doesn't leave the scope of that aspect. You'll have to | ||
keep in mind about the following guidelines when submitting code. | ||
|
||
Programming Style | ||
----------------- | ||
|
||
In order to keep the code unified, `Black <https://github.com/psf/black>`_, `AutoFlake <https://github.com/PyCQA/autoflake>`_, and | ||
`Isort <https://github.com/PyCQA/isort>`_ are used to format code to a consistent style. | ||
In addition, linters such as `Pyright <https://github.com/microsoft/pyright>`_ and `Ruff <https://github.com/astral-sh/ruff>`_ are | ||
used to ensure that code quality is kept to its standards and properly type hinted. The formatters are ran automatically within a pre-commit | ||
hook, which is ran before every commit. If you wish to run the pre-commit hook manually, you can run the following command: | ||
|
||
.. code-block:: bash | ||
pre-commit run --all-files | ||
.. note:: | ||
|
||
This project does follow the guidelines of `PEP-8 <https://peps.python.org/pep-0008/>`_ strictly. Please ensure that | ||
your code is in accordance with PEP-8. | ||
|
||
Static Code Analyzers | ||
--------------------- | ||
|
||
In addition to the tools mentioned, `SonarCloud <https://sonarcloud.io/>`_ is also used to analyze the codebase. | ||
If there is a issue raised by SonarCloud, please fix it. If you are unsure about the issue, | ||
please contact the dev lead (Noelle) for clarification. | ||
|
||
Pull Request Details | ||
-------------------- | ||
|
||
Source Control Branching Model | ||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
|
||
.. figure:: /_static/assets/trunk-workflow.svg | ||
:alt: Trunk Based Development Workflow | ||
:align: center | ||
|
||
The model used for source control branching is `trunk-based <https://www.atlassian.com/continuous-delivery/continuous-integration/trunk-based-development>`_. | ||
The ``main`` branch is known to contain working code, and thus cannot be touched directly. | ||
|
||
.. _Branch Naming Convention: | ||
|
||
Branch Naming Convention | ||
^^^^^^^^^^^^^^^^^^^^^^^^ | ||
|
||
When you create a branch, please use the following naming convention: | ||
|
||
.. code-block:: | ||
<name>/<type> | ||
``<name>`` is your name (you can use your GitHub name) and ``<type>`` is a concise one to three word description of the branch. | ||
For example, if a pull request has the name ``noelle/docs``, this indicates that the branch is created and owned by Noelle, | ||
and the purpose of the branch is to update documentation. | ||
|
||
Pull Request Checklist | ||
^^^^^^^^^^^^^^^^^^^^^^ | ||
|
||
When you create a pull request, please ensure that the following is done: | ||
|
||
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>`. | ||
2. Make sure that you have noted the changes in the ``changelog.md`` file. | ||
3. Your code is properly formatted and linted (and all workflows are passing). | ||
|
||
Git Commit Guidelines | ||
--------------------- | ||
|
||
1. Use present tense and imperative mood when writing commit messages. For example, ``Add new feature`` instead of ``Added new feature``. | ||
2. Reference issues or pull requests outside of the first line. | ||
a. Please use the shorthand ``#123`` and not the full URL. | ||
3. Commits that need to skip the CI workflows must be prefixed with ``[skip ci]``. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,57 @@ | ||
============ | ||
Features | ||
============ | ||
|
||
This document describes the features of Rodhaj and an general description on them. | ||
|
||
User Features | ||
============= | ||
|
||
These are the publicly available features that an user can use. | ||
|
||
Closing | ||
------- | ||
|
||
Naturally as communications come to an end, users cannot simply leave the ticket stale. | ||
In order to close a ticket, it is recommended to use the ``?close`` command. | ||
The ticket will be marked as closed to the user and subsequently closed on the ticket pool. | ||
Once closed, a ticket cannot be reopened. If a staff uses the ``?close`` command, | ||
the active ticket will be closed and the user will be notified of the closure. | ||
|
||
Note that there is no plans to support timed closures, as it is a design feature fudmentally flawed for this type of command. | ||
|
||
Administrative Features | ||
======================= | ||
|
||
Replying | ||
-------- | ||
|
||
In order to reply to a thread, use the ``?reply`` command. This will send a message to the user within an active ticket. | ||
Without executing this command, all messages will be seen as internal in the ticket. Images attachments, emojis, and stickers | ||
are supported. | ||
|
||
.. note:: | ||
|
||
Unlike ModMail, **none** of the messages sent with the ``?reply`` command, internally in the ticket, or by the user to staff | ||
will be logged. This is to ensure that the privacy of the user is respected. Staff can always look back at an closed ticket | ||
within the ticket channel if they need to refer to a particular message. | ||
|
||
Tags | ||
---- | ||
|
||
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. | ||
Tags can be used by using the ``?tag <tag name>`` command, where ``<tag name>`` represents the name of the tag that should be used. | ||
By default, they are sent directly to the user who is in the ticket, but can be sent internally by using the ``--ns`` flag. | ||
|
||
|
||
Ticket Assignee | ||
--------------- | ||
|
||
As tickets are created, they are assigned to a staff member. This is done to ensure that the ticket is not left unattended. | ||
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. | ||
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. | ||
|
||
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 | ||
and can act accordingly. | ||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,10 @@ | ||
================ | ||
User Guide | ||
================ | ||
|
||
This document represents the user guide for Rodhaj | ||
|
||
.. toctree:: | ||
:maxdepth: 2 | ||
|
||
features |