Skip to content

Commit 0fcb169

Browse files
committed
docs: draft contribution guide
1 parent ec3b67e commit 0fcb169

1 file changed

Lines changed: 57 additions & 0 deletions

File tree

CONTRIBUTING.md

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Contribution Guide
2+
3+
So, you wanna contribute to Bright? My oh my! You are very welcome to, just read the guide below to make sure what you're
4+
doing is a-okay.
5+
6+
## Bug Reporting
7+
8+
Before bug reporting, please check the following:
9+
10+
- Is this a security issue? **STOP!** Do not open a public issue! Please report the vulnerability via GitHub's advisory
11+
system. You are prompted with this option when you create a new issue.
12+
13+
- Is this a duplicate? Please add your information (if applicable) to that issue instead of making a new one.
14+
15+
- Is your problem easy to reproduce? Please provide a minimal reproduction with your issue. If a reproduction is not
16+
possible, please detail in the clearest way you can on how to reproduce the issue, otherwise it may be closed with
17+
"cannot reproduce".
18+
19+
## Code/Documentation Contributions
20+
21+
### AI Generation Policy
22+
23+
Bright will not accept pull requests that are written completely with AI. These sorts of contributions signify that effort
24+
was not put in to the pull request, and do not inspire any confidence that what is being contributed is functional. Please
25+
put in human work to your contributions, rather than relying on an AI tool to do the work for you.
26+
27+
For tools such as Copilot, make sure that the generated code works and has been modified to fit with the project's
28+
codestyle. Do not blindly trust generated code to be functional.
29+
30+
### Code
31+
32+
[to be done]
33+
34+
### Documentation
35+
36+
Bright's documentation is written to be a mix of serious and whimsy. Bright itself is not taken overly serious, as that
37+
would make it a boring tool, and my personal opinion is that a little sprinkle of humor and general unseriousness in
38+
documentation makes it more engaging for a developer to read through, but too much leads to it becoming annoying and
39+
repetitive.
40+
41+
The current documentation has a few humorous descriptions and bits that don't take itself serious, but when it comes to
42+
the main information, it should be considered as a more serious subject, and humor should be reduced or eliminated. The
43+
[Transformer Basics](https://brightluau.dev/developer-guide/tutorials/transformer-basics/) guide is not really a guideline
44+
per se, but is a good reference for what we're going for. Unserious parts are mixed in where appropriate, but the key
45+
information is kept serious so that developers aren't deciphering jokes and whatnot to work out what to do. Essentially,
46+
add whimsy in areas that can be ignored easier, and reduce it during key information.
47+
48+
Page descriptions are probably a massive exception to this rule, as they are almost exclusively written with humor in
49+
mind. These descriptions only show in social cards, rather than on the page themselves, so it's okay to make them silly
50+
since it won't affect the content of the page.
51+
52+
Most importantly though, documentation should be informal. Bright is not a company of any kind; it is a community ran thing.
53+
Formal English tends to give an impression that something is very uptight, and that is not the vibe that we should be
54+
going for.
55+
56+
The only exception to all of the above is the API documentation. It should be written in a relatively deadpan way as it's
57+
meant to describe code, rather than be a general piece of writing.

0 commit comments

Comments
 (0)