CONTRIBUTING.md 14 KB
Contributing to rAthena
Table of Contents
- Reporting Bugs
- Suggesting Enhancements
- Issue Labels
- Local Development Environment
- Become a Team Member
Reporting Bugs
This bit of information is here to guide you through the process of creating a bug report for rAthena! Issues cannot only be used for developers to track bugs, but they can also track enhancements and tasks. The more detailed your report is, the easier it is for developers to reproduce and resolve the bug!
Did you find a bug? :bug:
- Ensure the bug is not coming from a customization within your files!
- Ensure the bug was not already reported by searching on GitHub under Issues. If the same issue exists, feel free to leave a comment and tell us you are experiencing the issue as well and if possible add some additional or missing information!
- If you are unable to find an open issue addressing the problem, open a new one!
Submit A Bug Report :inbox_tray:
There are several things that go into making a bug report a good bug report!
This is a breakdown of a generic Issue:
- Title should give some general insight as to what the bug is about.
- Description should give greater detail of the bug that cannot be explained in the Title.
- Labels are colored to represent a category they fall into.
- Milestones are what developers use to group tasks together and quickly evaluate how close the project deliverable is near completion.
- Assignees are developers who are directly linked to resolve the issue.
- Comments allow other members to give feedback on the issue.
What are some good details to provide in a bug report? :pencil2:
When describing your Issue through the Description area, it is recommended that you provide as much information as possible to resolve the Issue as fast as possible. Keep in mind that you can tag people within the Description area through the @mention feature. You can also tag other Issues or Pull Requests by typing # which will pull up a list of issues. You can find a markdown guide at Mastering Markdown.
Some information to keep in mind while creating an Issue:
- GitHub Hash: The hash is a 40 alpha-numeric string (which can be broken down to the first 7 characters) which states the version you are at. (If you are using SVN instead of Git: Please also put the change date and first line of the commit message beside the revision number, or we will not be able to look up the corresponding Git hash).
- Client Date: The client date provides specific details depending on the issue. The main detail is that it helps narrow down issues that are related to a packet problem.
- Modifications that may affect results: It is always best to try to reproduce your issue on a clean rAthena if you have lots of modifications.
- Description of Issue: Describe your issue in detail! Screenshots and videos help a lot! Please also provide crash dumps if one of the servers is crashing.
- How to Reproduce Issue: Describe how to reproduce your issue in detail! The more the merrier!
- Official Info: Provide creditable sources to state why it is a bug! Please do not provide an iRO Wiki link as there is a high chance it does not match kRO behavior.
Be wary of the @mention feature! :warning:
Since rAthena uses custom @commands, when describing an issue that deals with these commands please keep in mind that this does clash with the @mention system for GitHub! Always quote the text when mentioning an `@command`(like this) so that you do not tag uninvolved GitHub users!
Suggesting Enhancements
Did you write a patch that fixes a bug? :bookmark_tabs:
- Open a new GitHub Pull Request with the patch.
- Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable.
Do you intend to add a new feature or change an existing one? :bulb:
- Open a new GitHub Pull Request with the feature addition or changes.
- Ensure the PR description clearly describes what the addition or changes are for. Include the relevant issue number if applicable.
How to create Pull Requests :pencil:
- Make sure you have a GitHub account.
- Next, you will need to fork rAthena to your account.
- Before making changes, make sure you create a new branch for your working tree. Never use your master branch! :bangbang:
- After completing your changes, commit and push it to your branch.
- Now you are ready to create a Pull Request for rAthena!
- Upon creating the Pull Request, make sure you follow our template and provide the required information.
- OPTIONAL: We would greatly appreciate those that check the box to allow edits by maintainers, so we can apply small cleanups or additions to your changes before merging them!
Issue Labels
For the most part you as a user will have no reason to worry about the Milestone or Assignee parts of an Issue. The different Labels of an Issue allow developers to quickly understand the issue and also allows for fast searching or sorting.
:bangbang: Users should be aware of the 'Mode' and 'Status' Type Labels as these sometimes require feedback! :bangbang:
Component
| Label Name | Search Link | Description |
|---|---|---|
component:core |
search | A fault that lies within the main framework of rAthena. |
component:database |
search | A fault that lies within the database of rAthena. |
component:documentation |
search | A fault that lies within the documentation of rAthena. |
component:script |
search | A fault that lies within the scripts of rAthena. |
component:skill |
search | A fault that deals specifically with a skill. |
component:tool |
search | A fault that lies within a tool of rAthena. |
Missing
| Label Name | Search Link | Description |
|---|---|---|
missing:clientdate |
search | Issue Title or Description does not state the client date used to create the bug. |
missing:mode |
search | Issue Title or Description does not state pre-renewal or renewal mode. |
missing:revision |
search | Issue Description does not state the revision of rAthena used when the bug occurred. |
Mode
| Label Name | Search Link | Description |
|---|---|---|
mode:prerenewal |
search | A fault that exists within the pre-renewal mode. |
mode:renewal |
search | A fault that exists within the renewal mode. |
Priority
| Label Name | Search Link | Description |
|---|---|---|
priority:high |
search | A fault that makes rAthena unstable or unusable. |
priority:medium |
search | A fault that makes rAthena have significant repercussions but does not render rAthena unusable. |
priority:low |
search | A fault that affects rAthena in one piece of functionality and is self-contained. |
Status
| Label Name | Search Link | Description |
|---|---|---|
status:code-review |
search | Pull Request that requires reviewing from other developers before being pushed to master. |
status:confirmed |
search | Issue that has been validated by a developer to affect rAthena. |
status:duplicate |
search | Issue that has been reported before. |
status:inprogress |
search | Issue that has begun resolution by a developer. |
status:invalid |
search | Issue that is either not official or is not related to rAthena. |
status:need more info |
search | Issue that needs more information from a creditable source. |
status:need user input |
search | Issue that needs more information from the issue creator. |
status:outdated emulator |
search | Issue that requires the creator's local files to be updated to be resolved. |
status:unable to reproduce |
search | Issue that was unable to be reproduced on rAthena. |
status:wontfix |
search | Issue that cannot be fixed through some limitation or is intended behavior. |
Type
| Label Name | Search Link | Description |
|---|---|---|
type:bug |
search | Issue that is a bug within rAthena. |
type:enhancement |
search | Issue that is an enhancement to rAthena. |
type:maintenance |
search | Issue for refactoring rAthena. |
type:question |
search | Issue that is a question for rAthena. |
Local Development Environment
Developers can get up and running quickly with a Dockerized development environment that installs all dependencies needed to run and develop on rAthena. See Docker documentation for details
Become a Team Member
- Before you send in a staff application, make sure you have an rAthena account.
- If you are new to the community, go ahead and introduce yourself!
- Please fill out the Staff Application and you will be notified shortly.
The rAthena team is comprised of all volunteers (AUTHORS). We encourage you to pitch in and submit bug reports or Pull Requests!
Thanks!
rAthena Team