CONTRBUTING.md

Contributing

Table of Contents

• Introduction
• Development
  • Project Setup
    • With write permissions
    • Everyone else
  • Contribute Code
• Management
  • Issue Tracking
  • Pull Requests Review & Management

Introduction ⭐

This guide should serve as a set of guidelines and instructions for all contributors with respect to how they can participate and improve the project.

The purpose of this guide is to establish a clear and consistent process for contributing to the project. This guide outlines how to setup the project locally, submit issues, branching conventions submit and review pull requests.

Project Setup 🔨

If you have write permissions:

Follow these instructions if you have permissions to edit the remote repository

Clone the repo in Android Studio

1. Open Android Studio
2. File > New > Project from VCS

For everyone else:

Follow these instructions if you do not have permissions to edit the remote repository

Note: This project uses GitHub Pull Requests to manage contributions, so read up on how to fork a GitHub project and file a PR if you've never done it before

Clone the repo in Android Studio

1. Open Android Studio
2. File > New > Project from VCS

Code Contribution 🚧

We welcome all contributions to the project. Follow the step-by-step guide below to ensure that your contribution fits the required standard and can be added to the project!

To contribute code:

• Set up the project.

• Identify any required modifications in the source code.

• Create and checkout a new branch.

  • git checkout -b <token/summary>
  • Tokens that should be used:

    Token Type	Description
    feat	This is a new feature
    refac	This is for refactoring an existing feature
    bug	This is for a bug fix
    doc	This is for creating & editing documentation
    test	This is a branch used for experimenting

  • Your summary should be no more than 2-3 words and seperated by dashes.
  • Your ticket number can be found in the issues / projects tab of the repo.
  • Example:
    • git checkout -b refac/readme-update

• Implement these changes accordingly.

• Incorporate supplementary documentation as needed to support the modifications made.

• Add modified code for staging

  From CLI

  • git add <path/to/file>

  From Android Studio

  • Jump to commit step
  • Note: Add each changed file individually, this will allow for better tracking of issues.

• Commit staged file with a descriptive message

  From CLI

  • git commit -m "your message"

  From Android Studio

  • Git > Commit > Add all changes > Commit changes > Ensure no errors > Commit and push
  • Guidelines for writing a commit message:
    • You should use the imperative mood for writing your commit messages.
    • Additional resource: https://initialcommit.com/blog/Git-Commit-Message-Imperative-Mood
    • Example:
      • git commit -m "Update README"
    • Typical commit messages begin with: Add, Update, Delete, Refactor and so forth.

• Once you are satisfied with your contribution, go to Pull Requests and open a new pull request with your changes.

• A maintainer or specified reviewer will be assigned to verify and test your changes. See more here.

Warning: If your contribution does not align with the instructions above, it will not be acknowledged.

Issue Tracking 🚨

Issues will be used for every possible contribution that needs to be made to the project - this includes, bugs, fixes, enhancements, testing and so on.

Github has predefined labels, they should be used as follows:

Labels	Description
bug	Use if something isn't working / defective
documentation	Use when creating / editing / deleting documentation
duplicate	Use for issue tickets with similar problems
enhancement	Use for new contributions to the codebase
good first issue	Don't use lol - need to remove
help wanted	Use if you are having issues solving a problem
invalid	Use if the issue might break the codebase
question	Use if you are unsure about implementation
wontfix	Use if you no longer want to work on this contribution / is redundant

Note: Multiple labels can be used on any specific issue.

Pull Requests Review & Management 📝

All comments and feedback are welcome on any Pull Request (PR). However, only repository maintainers can approve or deny these requests.

Once you successfully create a Pull Request, the maintainer will review and sufficently test the contribution to determine if it is merged into the main or any other branch. In the case where you want a speicific reviewer, Github has a feature that will allow you to assign the specified maintainer.

For more information regarding Github's Pull Request review feature, see here.

Author: Aidan Traboulay (26/10/2023)