In all honesty as this is a personal project, I don't expect anyone else will
contribute. Moreso, this began life as a final project for my BSc and thus
until that is done I must remain the only contributor, lest I have to reference
everyone else on the paper. This is more an exercise in setting aside reminders
to myself about how I should approach this.
If however on the offchance somebody does, the following will hopefully help
guide them to make a good job of it:
A note on comments, both in code and out of it. Firstly plain don't be
offensive, thats what a code of conduct is for, ensure any comment you make is
helpful and constructive. Secondly, I once read a really good article on the
different kinds of comments and how they can be used to be both helpful and
efficient. Yes, I've also heard the old addage that good code is self
documenting, in fact I try to write my code like this as if the code can be
made more obvious without sacrifice, then it should be. However good code is
not enough, sometimes a good comment can save you half an hour of unnecessary
confusion, or other times there is no obvious way to write the code and it
needs some explanation. I will try to find and
[link that article here](http://antirez.com/news/124) so we can all have a good
read and be the better coders for it.
[This article](http://www.catb.org/~esr/faqs/smart-questions.html) also seems
useful, though doesn't really fit anywhere.
1. Study and gain a reasonable understanding of the subject matter, the aim of
the project, and the purpose to be fulfilled.
2. Attempt to make contact with the repository owner. (I appreciate this may be
hard for those who don't know me personally, but this project is inherently
personal.)
3. Once you are able, choose a part of the project you can dedicate yourself to
and provide some valuable insights.
4. You will require an unprotected branch to add your code to, it will most
likely be easier if you create yourself an individual one.
5. Be sure to pull in regular updates from the master branch, and keep an eye
on the files most relevant to your section for any changes.
6. Always try to leave a helpful message with each commit, this makes it easier
to unpick your code later and make sense of what you did and why.
7. When you believe your code is ready for use, submit a pull request, then sit
back, relax, and prepare for the "What the hell *is* this garbage?!"
No newline at end of file
# Contributing
First, thank you for considering contributing to the project. Your help is what makes this project possible. This document outlines the guidelines for contributing to the codebase.
In all honesty as this is a personal project, I don't expect anyone else will contribute.
Moreso, this began life as a final project for my BSc and thus until that is done I must remain the only contributor, lest I have to reference everyone else on the paper.
This is more an exercise in setting aside reminders to myself about how I should approach this.
If however on the offchance somebody does, the following will hopefully help guide them to make a good job of it:
A note on comments, both in code and out of it. Firstly plain don't be offensive, thats what a code of conduct is for.
Ensure any comment you make is helpful and constructive.
Secondly, I once read a really good article on the different kinds of comments and how they can be used to be both helpful and efficient.
Yes, I've also heard the old addage that good code is self documenting, in fact I try to write my code like this as if the code can be made more obvious without sacrifice, then it should be.
However good code is not enough, sometimes a good comment can save you half an hour of unnecessary confusion, or other times there is no obvious way to write the code and it needs some explanation.
You can find that article [here](http://antirez.com/news/124) so we can all have a good read and be the better coders for it.
[This article](http://www.catb.org/~esr/faqs/smart-questions.html) also seems useful, though doesn't really fit anywhere.
### What to Contribute
We welcome all kinds of contributions, no matter how small. This includes:
* Reporting bugs
* Suggesting new features or improvements
* Submitting code changes (bug fixes, new features, etc.)
* Improving documentation
### Code of Conduct
This project and everyone participating in it is governed by the project's Code of Conduct. By participating, you are expected to uphold this code.
### Getting Started
Firstly, please appreciate this is a personal project within a community server, while your suggestions may be helpful I may still be unwilling to permit you to develop on this project, the reasons are manifold.
If you are lucky enough to be permitted, here is how to do it:
1.**Study and Understand:** Study and gain a reasonable understanding of the subject matter, the aim of the project, and the purpose to be fulfilled.
2.**Contact the Owner:** Attempt to make contact with the repository owner (me). I appreciate this may be hard for those who don't know me personally, but this project is inherently personal.
3.**Choose a part of the project:** Once you are able find something you can dedicate yourself to and provide some valuable insights.
4.**Create a personal branch:** You will require an unprotected branch to add your code to, it will most likely be easier if you have an individual one. This will likely be done for you on initiation into the project.
4.**Clone the repo:** Clone the repository to your local machine.
5.**Set Up Your Environment:** Follow the instructions in the `README.md` file to set up the development environment.
6.**Stay Updated:** Keep your local copy of the repository in sync with the upstream `dev` branch.
### Reporting Issues
The best way to report a bug or suggest a feature is by creating a new **issue** on the repository.
***For Bug Reports:** Please include as much detail as possible. A good bug report should include:
* A clear, descriptive title.
* Steps to reproduce the bug.
* The expected behavior.
* The actual behavior.
* Details about your environment (OS, versions of Rust/Flutter, etc.).
***For Feature Suggestions:** Explain the feature you want to see, describe the problem it solves, and outline why it would be valuable to the project and its users.
### Submitting Code Changes
We use the standard Git flow for contributions. This means all changes are submitted via a **Merge Request (MR)**.
1.**Create a New Branch:** Create a new branch for your changes. Please use a descriptive name. For example, `feat/add-user-auth` or `fix/database-connection-bug`.
2.**Make Your Changes:** Write your code, following the established coding conventions for Rust and Dart.
3.**Write Tests:** All new features and bug fixes must be accompanied by appropriate tests. We follow a **Test-Driven Development (TDD)** approach.
4.**Always leave a helpful message with each commit:** This makes it easier to unpick your code later and make sense of what you did and why.
5.**Create a Merge Request:** Set up a merge request for the `dev` branch and notify a maintainer. Pushing to `main` and will be handled by the maintainers, even in the case of hotfixes.
6.**Describe Your Changes:** A good MR description should:
* Reference the issue it addresses (e.g., `Closes #123`).
* Clearly summarize the changes.
* Explain the reasoning behind your changes.
* Provide any necessary context for the reviewer.
### The SOLID 'Acid Test'
Before submitting a Merge Request, please ensure your new code adheres to the **SOLID** principles of software design. Running your work through this "acid test" helps us maintain a clean, scalable, and maintainable codebase.
***S**ingle-responsibility Principle: Does your class, module, or function have a single, well-defined purpose? Can you describe what it does without using the word "and"?
***Example:** A `MarketDataFetcher` class should only be responsible for fetching data, not for parsing it or saving it to the database.
***O**pen-closed Principle: Is your code open for extension but closed for modification? Can you add new functionality without changing existing, well-tested code?
***Example:** When adding a new data source, can you do so by creating a new class that implements a trait or interface, rather than modifying the core data fetching logic?
***L**iskov Substitution Principle: Can a derived class be used in place of its parent class without breaking the application?
***Example:** If you have an `Item` trait and you create a `Weapon` struct that implements it, can a function that takes an `Item` also accept a `Weapon` without unexpected behavior?
***I**nterface Segregation Principle: Are your traits or interfaces small and specific to their purpose?
***Example:** Instead of a single, large `DatabaseClient` trait, consider smaller traits like `MarketDataReadable` and `UserDataWritable`.
***D**ependency Inversion Principle: Does your code depend on abstractions (traits or interfaces) rather than on concrete implementations?
***Example:** A service that fetches market data should depend on a `MarketDataFetcher` trait, not a specific `ApiFetcher` struct. This allows the implementation to be swapped out easily.
### Licensing
By contributing to the project, you agree that your contributions will be licensed under the **GNU Affero General Public License (AGPL)**.
