# Contributing
`journalmap` is the side-project of my side-hustle [Mjolnir](https://blacksheepswe.dev/mjolnir/)
and as such I only have so much time to give to it. Help is greatly appreciated!
Just make sure you follow the following guidelines to make it easy for all of us.
## LLM Guidelines
LLMs are a common but often misused tool. There are many programmers who have found
appropriate and responsible use cases which will be permitted, along with many
inappropriate and negligent uses of it which are prohibited.
To be able to contribute to this codebase you *must* adhere to the following rules,
otherwise by neglecting the following rules I reserve the right to ban you from
committing future code and to revert all changes you've made to the codebase.
**[It is prohibited to use commercial LLMs](#avoid-commercial-llms)**
### LLMs are prohibited to:
* Generate PR request messages
* Generate issue messages
* Generate and/or partially generate code that is not marked as LLM generated + forfeited to public domain
### LLMs are permitted to:
* Assist you in development
* Document code
* Review + find bugs in code
* Generate and/or partially generate code so long as it is properly marked and disclosed as such
### Properly disclosing LLM generated code
Due to potential copyright issues pertaining to LLM generated content in
general, all code generated under LLMs must be clearly marked as such and
must be public domain.
For example, let's say you generated the following function with an LLM:
```rust
fn add(lhs: f32, rhs: f32) -> f32 {
lhs - rhs
}
```
In order to make the function applicable to merge into this project, you must
add the following disclaimer:
```rust
// The following function was generated and/or partially generated via an LLM,
// and as a result I, Jane Jimmy Doe, forfit all claims to copyright and/or
// liability of said function and recognize it belongs to the public domain.
fn add(lhs: f32, rhs: f32) -> f32 {
lhs - rhs
}
```
Here is a template for said disclaimer:
```rust
// The following *function/struct/variable/etc* was generated and/or partially generated via an LLM
// and as a result I, *your name here*, forfit all claims to copyright and/or
// liability of said *function/struct/variable/etc* and recognize it belongs to the public domain.
```
**Note: It is recommended you don't generate LLM code at all**, simply due to
the fact that there is a good chance that if you need to use it you're either
making *too much code and complicating the project*, or you're out of your depth
and it would be better if you either learned more about the subject or let someone
else fix it.
### Avoid Commercial LLMs
If you are going to use LLMs, it is required you use a locally hosted one.
It is not permitted to use a common commercial one provided by OpenAI, Anthropic
Google or etc.
The reasons are near innumeral, but here are a few I can think of off the top
of my head:
* Mass resource consumption and pollution
* Vast amounts of bribery(lobbying), often (if not always) going against the
wishes of voters
* Assistance in mass surveillance and warfare
* Total neglect for the licenses of open source projects
### "What do I do if I need AI?"
You don't contribute. If you can't follow the above guidelines you probably
aren't making code up to any respectable standard, so I don't want to see it.
## Formatting
Formatting is performed by running `./format.sh` and it mostly automatic. You can
run it yourself, but I will also run it before each merge just in case you're
on a system that can't run shell scripts or doesn't have nightly cargo installed.
### Other Formatting Guidelines
Besides automatic formatting there are a few things you should do yourself to
ensure that you follow these basic rules to make your code more maintainable:
* Make sure variable, struct and module names are self-documenting
* Include documentation for more complex structs and functions so that the
automatically generated rustdocs are user-friendly
* `unsafe` shouldn't be used in a high-level library like this and is forbidden
* `unwrap()` is also highly discourage and really shouldn't be used without
justification
* When writing functions order arguments from most generic to least generic, e.g.
`fn foo(&self, solver: &Solver, flumbo_factor: u16)`
* Avoid making massive functions, structs, and source files unless absolutely
necessary
* Add tests when adding functionality, and create example code in docs when
appropriate
* Mark code that needs future work done with a `// !TODO!` comment
* Write idiomatic Rust
* Follow the [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
## Code of Conduct
It is good life advice to be empathetic and respectable of other people, and
it is asked that you refrain from getting into heated arguments in contexts
related to this repo. If something makes you angry, please take a breather and
if it breaks the rules, report it and it will be dealt with. Do not feed trolls.
General conduct rules are as follows:
* Harassment or degradation of others based on their gender, race, country of
origin, identity, sexual orientation or any disability they may have is strictly
prohibited both in contexts in and outside of this repository, and will award you
a swift and permanent ban at my discretion
* Doxxing or any other illegal activities are also prohibited and will also award
you a swift and permanent ban
* Nazis are not allowed. This is not controversial and if you think it is
controversial, touch grass after I give you a swift and permanent ban
* Being excessively sexual or flirting with others makes everyone uncomfortable
and isn't appropriate for a *rust library repository*. First offenses will be a
warning and then if you ignore the warning you will be banned
* Political arguments are also not appropriate for a *rust library repository*
and will also reward a warning on first offenses and a ban on second offenses
## Misc. Contributing Rules
* Avoid large pull requests. Pull requests longer than a few hundred lines are
a PITA to review and should really be broken up into multiple PRs instead if
possible.
* Name your branches in the format `initials-yy-mm-dd-feature`
## Regarding Questions & Comments on The Above Rules
If you have anything to say about the rules laid out in this file, please
contact me directly at my email instead of raising an issue.