Minor comments on the README
sodface opened this issue · 6 comments
Hi sodface
Thank you for taking the time to review our documents.
Your first quote is from our quick introduction section
and intentionally brief. (Quick Intro includes everything we hope one might
want to know at a glance on a single page)
Your second quote is from the actual contributing section and explains
this further.
The word "iff" is actually not a typo, but instead a shorthand for "if
and only if". However, we figured that it is rather more confusing than
helpful and have therefore removed it.
To improve all this, we have changed the Quick Intro and Contributing
sections and propose the patch which you may find attached. What do you
think?
Regarding PRs and DCOs, we have decided to add a PR template, to present the
relevant documentation where it is needed.
We propose the one below, but any feedback from your side would be
greatly appreciated.
# Description
Replace this with a description of your pull request.
Please reference any relevant issues, PRs etc.
## Type of Change
* [ ] Fix
* [ ] Backwards-compatible Feature
* [ ] Breaking Change
## Considerations
Replace this with a description of what might be missing, any points of confusion or
side effects you would like to point out.
## Credit
* [ ] I want to be credited as YOUR_NAME_OR_PSEUDONYM in your contributor section
* [ ] I don't want to be credited.
(by signing off, you state that you are allowed to contribute and allow us to publish
your contribution under the MIT License)
signed-off-by: YOUR_NAME_OR_PSEUDONYM
The patch for README.md:
diff --git a/README.md b/README.md
index 1781cc3..09d5f84 100644
--- a/README.md
+++ b/README.md
@@ -9,25 +9,21 @@ based on [Cage](https://github.com/Hjdskes/cage) and inspired by [ratpoison](htt
### Purpose
-The goal of this project is to provide a successor to ratpoison for Wayland.
+This project provides a successor to ratpoison for Wayland.
However, this is no reimplementation of ratpoison.
#### New Features, Bugs and Contact Information
-Should you want to know if a feature will be implemented, file a bug or
-get in touch, [open an issue](https://github.com/project-repo/cagebreak/issues/new)
+You can [open an issue](https://github.com/project-repo/cagebreak/issues/new)
or write an e-mail (See [SECURITY.md](SECURITY.md) for details.).
-The Roadmap section outlines what is planned for the future.
+The Roadmap section outlines our plans.
#### Compatibility & Development Distribution
Cagebreak supports [Arch Linux](https://archlinux.org/) and uses the libraries
-(and software versions) as they are obtained through [pacman](https://wiki.archlinux.org/title/Pacman)
-at the time of release. Any other use is out of scope.
-
-Most other setups probably work with a bit of luck. We
-make no guarantees.
+and versions from extra and core at the time of release.
+Most other setups work with a bit of luck.
### Quick Installation
@@ -42,17 +38,12 @@ details on getting started and the documentation for everything else.
### Documentation
- * the rest of this file
- * the man pages:
- * [cagebreak](man/cagebreak.1.md)
- * [configuration](man/cagebreak-config.5.md)
- * [socket](man/cagebreak-socket.7.md)
- * the [FAQ](FAQ.md)
- * [SECURITY.md](SECURITY.md)
+ * the man pages: [cagebreak](man/cagebreak.1.md), [configuration](man/cagebreak-config.5.md) & [socket](man/cagebreak-socket.7.md)
+ * the [README](README.md), [FAQ](FAQ.md) & [SECURITY.md](SECURITY.md)
#### What's new?
-See the [Changelog](Changelog.md).
+Check the [Changelog](Changelog.md).
### Uninstallation
@@ -60,9 +51,9 @@ See the [Changelog](Changelog.md).
### Contributing
- * Just [open an issue](https://github.com/project-repo/cagebreak/issues/new) and state your idea.
- We will consider the proposal and get back to you.
- * Don't open a pull request. We might not accept your code and
+ * [Open an issue](https://github.com/project-repo/cagebreak/issues/new) and state your idea.
+ We will get back to you.
+ * Ask before you open a pull request. We might not accept your code and
it would be sad to waste the effort.
* Respect the [Code of Conduct](CODE_OF_CONDUCT.md) (To date, we never
had to intervene - Keep it that way!)
@@ -208,16 +199,16 @@ as a source of inspiration and explanations for certain particularities.
## Contributing
* Read this document.
- * Just [open an issue](https://github.com/project-repo/cagebreak/issues/new) and state your feature request.
- We will consider the proposal and get back to you.
- * Don't open a pull request without asking first. We might not accept your
+ * [Open an issue](https://github.com/project-repo/cagebreak/issues/new) and state your feature request.
+ We will get back to you.
+ * Ask before opening a pull request. We might not accept your
code and it would be sad to waste the effort.
* Respect the [Code of Conduct](CODE_OF_CONDUCT.md) (To date, we never
had to intervene - Please keep it that way!)
### Good First Contributions
- * Reviewing the project is always welcome.
+ * Reviews are always welcome.
* Read the code.
* Read the documentation.
* Test whether the documentation matches the code.
@@ -225,12 +216,12 @@ as a source of inspiration and explanations for certain particularities.
* Compile the code.
* Ideas on improving the testing and quality assurance are particularly
welcome.
- * If you want, you can share your cagebreak scripts and we might include them
- in the repository provided you agree to release them under MIT and we agree
- with the use case and coding style.
- * Iff you are happy with Cagebreak and use Arch Linux, you may vote for
+ * You can share your cagebreak scripts and we might include them with Cagebreak
+ provided you agree to release them under MIT and we agree with the
+ use case and coding style.
+ * If you are happy with Cagebreak under Arch Linux, you may vote for
[Cagebreak in the AUR](https://aur.archlinux.org/packages/cagebreak).
- * The points above still apply.
+ * The points from the Contributing section above still apply.
### Philosophy
The word "iff" is actually not a typo, but instead a shorthand for "if and only if".
Ah! Today I learned...
My ignorance is showing (again!).
any feedback
README updates look good to me.
Hi sodface
The changes as discussed above have been released in 2.2.2 with the exception of the PR template.
cheers
project-repo
Great and thanks for the new releases. Shall we close this issue?
I think it's better if we leave it open until the PR template is
implemented (so as to minimize the risk of us forgetting it).
Hi sodface
A PR template has been added with release 2.3.0.
I am closing this issue.
Cheers
project-repo