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:
|
||||
|
||||
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