mirror of
https://github.com/pinnacle-comp/pinnacle.git
synced 2024-11-16 07:48:11 +01:00
Add CONTRIBUTING
This commit is contained in:
Ottatop
parent
b4f723f7b5
commit
55350bbd03
2 changed files with 187 additions and 0 deletions
184
CONTRIBUTING.md
Normal file
184
CONTRIBUTING.md
Normal file
|
|
@ -0,0 +1,184 @@
|
||||||
|
# Repository Guidelines
|
||||||
|
|
||||||
|
Interested in contributing? Have a feature request, bug report, or question? Well, you've come to the right place!
|
||||||
|
|
||||||
|
You can use the table of contents below to navigate directly to what is relevant for you.
|
||||||
|
|
||||||
|
> ### Table of Contents
|
||||||
|
> 1. [Contributing](#contributing)
|
||||||
|
> 2. [Feature requests](#feature-requests)
|
||||||
|
> 3. [Bug reports](#bug-reports)
|
||||||
|
> 4. [Questions](#questions)
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
Thank you for taking your time to contribute! As with many repositories out there,
|
||||||
|
there are some guidelines on what you should and shouldn't do, listed below.
|
||||||
|
|
||||||
|
> ### Before you continue...
|
||||||
|
> - If you are thinking about contributing towards a new feature request that has no prior issue,
|
||||||
|
> consider opening one to gauge interest and feedback. This will help prevent unnecessary work if
|
||||||
|
> your pull request would be denied.
|
||||||
|
> - Check to see if someone else isn't already drafting a pull request on the same thing.
|
||||||
|
|
||||||
|
### By contributing to Pinnacle, you acknowledge that you have rights to the code you provide, and you agree to license your work under the GNU General Public License v3.0.
|
||||||
|
|
||||||
|
### 1. Fork the project.
|
||||||
|
|
||||||
|
### 2. Add your contributions.
|
||||||
|
- If you are contributing to the Lua API, **document user-facing functions** using Lua LS
|
||||||
|
[annotations](https://github.com/LuaLS/lua-language-server/wiki/Annotations). Provide parameter and return types,
|
||||||
|
as well as documentation that follows the following format:
|
||||||
|
> ````lua
|
||||||
|
> ---A short one line summary of the function.
|
||||||
|
> ---
|
||||||
|
> ---Additional paragraph or paragraphs detailing more information about the function
|
||||||
|
> ---should be added below the summary.
|
||||||
|
> ---
|
||||||
|
> ---### Example(s)
|
||||||
|
> ---```lua
|
||||||
|
> ----- Provide an example/examples of the usage of the function where appropriate,
|
||||||
|
> ----- including function overloads when applicable.
|
||||||
|
> ---print("hi mom!") -- Print with a string
|
||||||
|
> ---print(true) -- Print with a boolean
|
||||||
|
> ---```
|
||||||
|
> ---@param (if applicable)
|
||||||
|
> ---@return (if applicable)
|
||||||
|
> ---@see (if applicable)
|
||||||
|
> ---@and_other_appropriate_annotations
|
||||||
|
> function thingy(param1, param2, ...) end
|
||||||
|
> ````
|
||||||
|
- You will also need to duplicate documentation for LDoc. This is unfortunate, but Lua LS documentation
|
||||||
|
exporting *really* isn't that great, and I haven't gotten around to finding a way to make it better.
|
||||||
|
- Place dummy functions of the same names in a respective file in the [`api/lua/doc`](api/lua/doc) folder.
|
||||||
|
- You can follow the above format with some minor changes:
|
||||||
|
- Replace `@param` with `@tparam` and swap the parameter name and type.
|
||||||
|
- Replace `@return` with `@treturn`.
|
||||||
|
- Instead of an H3 markdown section for examples, place them in `@usage` without the fences
|
||||||
|
(you may need to add a space between the beginning 3 dashes and any start-of-the-line comments).
|
||||||
|
- LDoc documentation will then be auto-generated on pull request.
|
||||||
|
- Format Rust code using [rustfmt](https://github.com/rust-lang/rustfmt) and the provided
|
||||||
|
[rustfmt.toml](rustfmt.toml) file.
|
||||||
|
- Format Lua code with [StyLua](https://github.com/JohnnyMorganz/StyLua) and the provided
|
||||||
|
[stylua.toml](api/lua/stylua.toml) file.
|
||||||
|
|
||||||
|
> #### Keep commit messages short.
|
||||||
|
> They should also use imperative speech, e.g. "Add feature" or "Fix bug" instead of
|
||||||
|
"Added feature" or "Fixing bug".
|
||||||
|
|
||||||
|
### 3. Open a pull request against the main branch.
|
||||||
|
- Have a clear and succinct title.
|
||||||
|
- Provide a description of what the pull request is for.
|
||||||
|
- Link any issues that may be closed after merging, if any.
|
||||||
|
> If we deem the pull request unnecessary or out of the project's scope, we'll close it.
|
||||||
|
|
||||||
|
### 4. Respond to any questions and code reviews.
|
||||||
|
|
||||||
|
### 5. Wait for merge! :tada:
|
||||||
|
|
||||||
|
## Feature Requests
|
||||||
|
If you have an idea for a new feature or enhancement, follow the steps below.
|
||||||
|
|
||||||
|
> ### Before you continue...
|
||||||
|
> - Search open issues to see if someone has already requested your feature.
|
||||||
|
> - Duplicate requests will be closed as duplicate.
|
||||||
|
> - See if your feature request can already be implemented through Lua.
|
||||||
|
> - Pinnacle is built to give you great control and configurability. This means there *might* be a
|
||||||
|
> way to whip up something to fulfill what you want.
|
||||||
|
> - For example, if you want something like a scratchpad, you can rig up a keybind to toggle a window
|
||||||
|
> in the scratchpad tag and one to toggle the scratchpad itself. TODO: show an example config for this.
|
||||||
|
> - If you believe that what you want *can* be implemented through configuration but are unsure on
|
||||||
|
> how to do it, search for or open a GitHub discussion! There *should* be someone around to help.
|
||||||
|
|
||||||
|
### 1. Have a clear and succinct title.
|
||||||
|
|
||||||
|
### 2. Describe your feature request or enhancement in detail.
|
||||||
|
If you have any ideas on implementation details and whatnot, include those as well. We'd love to hear your ideas!
|
||||||
|
|
||||||
|
### 3. Add appropriate labels.
|
||||||
|
All feature requests should have the https://github.com/Ottatop/pinnacle/labels/enhancement label.
|
||||||
|
If there are other labels you feel are appropriate, add them as well!
|
||||||
|
|
||||||
|
### 4. Submit the feature request!
|
||||||
|
We'll determine if what you're asking for is within the scope of and appropriate for the project.
|
||||||
|
|
||||||
|
If we're onboard, we'll start working on it, time permitting.
|
||||||
|
|
||||||
|
If we decide that your feature request isn't right for the project, it will be closed as not planned.
|
||||||
|
|
||||||
|
## Bug Reports
|
||||||
|
So... you've finally run into the dreaded `thread 'main' panicked at 'already borrowed: BorrowMutError'`.
|
||||||
|
Or maybe you haven't. Either way, if you've run into a bug, crash, or something that you don't
|
||||||
|
think should be happening, these are the guidelines you should follow when submitting a bug report.
|
||||||
|
|
||||||
|
> ### Before you continue...
|
||||||
|
> - Search open issues to see if the problem has already been reported.
|
||||||
|
> - If you submit a bug that already has an open issue, it will be closed as duplicate.
|
||||||
|
> - Search the wiki to see if there is a solution or workaround to your problem.
|
||||||
|
> - Ensure that the problem is reproducible or at least happens more than once.
|
||||||
|
> - See if you can reliably reproduce the problem. If you can't, but the bug happens multiple times
|
||||||
|
> and you have a hunch on what is causing it, still submit a bug report anyway. We'll see what we can do!
|
||||||
|
|
||||||
|
### 1. Have a clear and succinct title.
|
||||||
|
You have the entire body of the issue to go into more depth, so keep the title short, sweet, and easily parsable!
|
||||||
|
|
||||||
|
### 2. Provide necessary details.
|
||||||
|
This includes the following:
|
||||||
|
- Your Linux distribution
|
||||||
|
- The version of Rust you used to compile and run Pinnacle
|
||||||
|
- Any tracebacks or logs
|
||||||
|
- Tracebacks can be obtained by running Pinnacle with the environment
|
||||||
|
variable `RUST_BACKTRACE=1` or `RUST_BACKTRACE=full`.
|
||||||
|
- Your Lua config (or any applicable parts)
|
||||||
|
|
||||||
|
> #### Important:
|
||||||
|
> **If you have a log, config, or similar that is over 50 lines, please either upload it to
|
||||||
|
> a place like [pastebin](https://pastebin.com/) and link to it or place the text in the
|
||||||
|
> `<details>` tag, as shown below. The whitespace lines and indentation are important.**
|
||||||
|
> This helps both desktop and mobile users not have to scroll several miles to reach the next comment.
|
||||||
|
> > ````md
|
||||||
|
> > <details>
|
||||||
|
> >
|
||||||
|
> > <summary>The stack trace</summary> // Optional summary
|
||||||
|
> >
|
||||||
|
> > ```
|
||||||
|
> > Stack trace starting at the dingaling function...
|
||||||
|
> > Many lines here...
|
||||||
|
> > Stack trace ending at main or whatever
|
||||||
|
> > ```
|
||||||
|
> >
|
||||||
|
> > </details>
|
||||||
|
> > ````
|
||||||
|
> This will become:
|
||||||
|
> <details>
|
||||||
|
>
|
||||||
|
> <summary>The stack trace</summary>
|
||||||
|
>
|
||||||
|
> ```
|
||||||
|
> Stack trace starting at the dingaling function...
|
||||||
|
> Many lines here...
|
||||||
|
> Stack trace ending at main or whatever
|
||||||
|
> ```
|
||||||
|
> </details>
|
||||||
|
|
||||||
|
### 3. Go in detail regarding the bug and reproduction steps.
|
||||||
|
Document what the bug is and, if you have them, list all steps to reproduce the bug in detail.
|
||||||
|
If not, describe what you were doing when the bug happened.
|
||||||
|
|
||||||
|
### 4. Add appropriate labels.
|
||||||
|
The one label all bug reports should have is the aptly named https://github.com/Ottatop/pinnacle/labels/bug label.
|
||||||
|
If there are other labels you feel are appropriate, like https://github.com/Ottatop/pinnacle/labels/xwayland
|
||||||
|
for XWayland issues, add them as well. These labels help us filter out issues reliably.
|
||||||
|
|
||||||
|
### 5. Smash that `Submit new issue` button!
|
||||||
|
Congrats! You've helped Pinnacle move one step closer towards the summit!
|
||||||
|
Don't forget to ~~like and comment~~ star and watch the repo! :thumbsup:
|
||||||
|
|
||||||
|
## Questions
|
||||||
|
Have a question about the future of the project? Perhaps you're writing your own
|
||||||
|
compositor with Smithay and you need help with *that one issue* that you've been
|
||||||
|
mulling over for days.
|
||||||
|
|
||||||
|
In any case, instead of using GitHub issues, please use
|
||||||
|
[GitHub discussions](https://github.com/Ottatop/pinnacle/discussions), which I feel is
|
||||||
|
better tailored towards questions and general, well, *discussions*. GitHub issues
|
||||||
|
should only be used for bug reports and feature requests.
|
||||||
|
|
@ -129,3 +129,6 @@ The following controls are currently hardcoded:
|
||||||
- `Ctrl + Alt + Shift + Esc`: Kill Pinnacle. This is for when the compositor inevitably locks up because I did a dumb thing :thumbsup:
|
- `Ctrl + Alt + Shift + Esc`: Kill Pinnacle. This is for when the compositor inevitably locks up because I did a dumb thing :thumbsup:
|
||||||
|
|
||||||
You can find the rest of the controls in the [`example_config`](api/lua/example_config.lua).
|
You can find the rest of the controls in the [`example_config`](api/lua/example_config.lua).
|
||||||
|
|
||||||
|
## Feature Requests, Bug Reports, Contributions, and Questions
|
||||||
|
See [CONTRIBUTING.md](CONTRIBUTING.md).
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue