mirror of
https://cagebreak.project-repo.co/cagebreak.git
synced 2026-08-09 15:19:11 +02:00
bea18c7a6f
- Adjust dependency versions - Add release tests - Add a quick installation script - Add small utility scripts - Add note on review and developer certificate of origin (DCO) - Add note on accessibility
769 lines
26 KiB
Markdown
769 lines
26 KiB
Markdown
# Cagebreak: A Wayland Tiling Compositor
|
|
|
|
[](https://bestpractices.coreinfrastructure.org/projects/6532) [](https://repology.org/project/cagebreak/versions) [](https://repology.org/project/cagebreak/versions)
|
|
|
|
## Quick Introduction
|
|
|
|
Cagebreak is a [Wayland](https://wayland.freedesktop.org/) tiling compositor
|
|
based on [Cage](https://github.com/Hjdskes/cage) and inspired by [ratpoison](https://www.nongnu.org/ratpoison/).
|
|
|
|
### Purpose
|
|
|
|
The goal of this project is to provide 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)
|
|
or write an e-mail (See [SECURITY.md](SECURITY.md) for details.).
|
|
|
|
The Roadmap section outlines what is planned for the future.
|
|
|
|
#### 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.
|
|
|
|
### Quick Installation
|
|
|
|
This assumes Arch Linux:
|
|
|
|
1. Use the [cagebreak PKGBUILD](https://aur.archlinux.org/packages/cagebreak).
|
|
2. Add an example config such as [config](examples/config) to `$USER/.config/cagebreak/config`
|
|
3. Execute cagebreak like any other binary.
|
|
|
|
See the [ArchWiki](https://wiki.archlinux.org/title/Cagebreak#Getting_started) for
|
|
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)
|
|
|
|
#### What's new?
|
|
|
|
See the [Changelog](Changelog.md).
|
|
|
|
### Uninstallation
|
|
|
|
`pacman -R cagebreak` should be sufficient.
|
|
|
|
### 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
|
|
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!)
|
|
|
|
### Name
|
|
|
|
Cagebreak is based on [Cage](https://github.com/Hjdskes/cage), a Wayland kiosk
|
|
compositor. Since it breaks the kiosk into tiles the name
|
|
Cagebreak seemed appropriate.
|
|
|
|
## Installation
|
|
|
|
On Arch Linux, just use the PKGBUILDs from the [AUR](https://aur.archlinux.org/):
|
|
|
|
* Using [cagebreak](https://aur.archlinux.org/packages/cagebreak), Cagebreak is
|
|
compiled on the target system (since release 1.3.0)
|
|
* Using [cagebreak-bin](https://aur.archlinux.org/packages/cagebreak-bin),
|
|
the pre-built binaries are extracted to
|
|
appropriate paths on the target system (since release 1.3.2)
|
|
|
|
See [cagebreak-pkgbuild](https://github.com/project-repo/cagebreak-pkgbuild) for details.
|
|
|
|
### Obtaining Source Code
|
|
|
|
There are different ways to obtain cagebreak source:
|
|
|
|
* [git clone](https://github.com/project-repo/cagebreak) (for all releases)
|
|
* [download release asset tarballs](https://github.com/project-repo/cagebreak/releases) (starting at release 1.2.1)
|
|
|
|
#### Verifying Source Code
|
|
|
|
There are corresponding methods of verifying that you obtained the correct code:
|
|
|
|
* our git history includes signed tags for releases
|
|
* release assets starting at release 1.2.1 contain a signature for the tarball
|
|
|
|
## Building Cagebreak
|
|
|
|
You can build Cagebreak with the [meson](https://mesonbuild.com/) build system. It
|
|
requires wayland, wlroots and xkbcommon to be installed. Note that Cagebreak is
|
|
developed against the latest tag of wlroots, in order not to constantly chase
|
|
breaking changes as soon as they occur.
|
|
|
|
Simply execute the following steps to build Cagebreak:
|
|
|
|
```
|
|
$ meson setup build
|
|
$ ninja -C build
|
|
```
|
|
|
|
#### Release Build
|
|
|
|
By default, this builds a debug build. To build a release build, use `meson
|
|
setup build --buildtype=release`.
|
|
|
|
##### Xwayland Support
|
|
|
|
Cagebreak comes with compile-time support for XWayland. To enable this,
|
|
first make sure that your version of wlroots is compiled with this
|
|
option. Then, add `-Dxwayland=true` to the `meson` command above. Note
|
|
that you'll need to have the XWayland binary installed on your system
|
|
for this to work.
|
|
|
|
##### Man Pages
|
|
|
|
Cagebreak has man pages. To use them, make sure that you have `scdoc`
|
|
installed. Then, add `-Dman-pages=true` to the `meson` command.
|
|
|
|
### Running Cagebreak
|
|
|
|
You can start Cagebreak by running `./build/cagebreak`. If you run it from
|
|
within an existing X11 or Wayland session, it will open in a virtual output as
|
|
a window in your existing session. If you run it in a TTY, it'll run with the
|
|
KMS+DRM backend. Note that a configuration file is required. For more
|
|
configuration options, see the man pages.
|
|
|
|
Please see `example_scripts/` for example scripts and a basis to customize
|
|
from.
|
|
|
|
#### Usage Philosophy
|
|
|
|
Cagebreak was originally built to suit the needs of its creators. This section outlines
|
|
how we intended some parts of cagebreak and might ease learning how to use cagebreak a
|
|
little bit. Please note that this does not replace the man pages or the FAQ.
|
|
Also, this is in no way intended as a guide on how cagebreak must be used but rather
|
|
as a source of inspiration and explanations for certain particularities.
|
|
|
|
1. Cagebreak is keyboard-based. Everything regarding cagebreak can be done
|
|
through the keyboard and it is our view that it should be. This does not mean
|
|
that pointers, touchpads and such are not available for the few applications
|
|
that do require them.
|
|
|
|
2. Cagebreak is a tiling compositor. Every view takes up as much screen space
|
|
as possible. We believe this is useful, as only very few programs are typically
|
|
necessary to complete a task. To manage multiple tasks concurrently, we use
|
|
workspaces.
|
|
|
|
3. Each task deserves its own workspace. Any given task (the sort of thing you
|
|
might find in your calendar or on your todo list) probably requires very few
|
|
views and ideally, these take up as much of the screen as possible.
|
|
|
|
> Combining 2. and 3. might look like this in practice:
|
|
|
|
> * Task 1: Edit introduction section for paper on X
|
|
> * Task 2: Coordinate event with person Y
|
|
|
|
> * split screen vertically
|
|
> * open web browser or pdf viewer to read literature
|
|
> * focus next
|
|
> * open editor
|
|
> * change to a different workspace
|
|
> * split screen vertically
|
|
> * open calendar application
|
|
> * focus next
|
|
> * open chat application
|
|
|
|
> Now each task has its own workspace and switching between tasks is possible
|
|
> by switching between workspaces.
|
|
|
|
> Note that, for example by using the socket, more advanced setups are
|
|
> possible. But the user is warned that excessive tweaking eats into the work
|
|
> to be done.
|
|
|
|
4. Use keybindings and terminal emulators for the right purpose. Given the
|
|
philosophy outlined above you probably launch the same few programs very
|
|
often and others are very rarely used. We believe that commonly
|
|
used programs should have their own keybindings together with the most
|
|
important cagebreak commands. All the rarely used programs should be launched
|
|
from a terminal emulator as they probably require special flags, environment
|
|
variables and file paths anyway.
|
|
|
|
> In practice this means thinking about the applications and cagebreak commands
|
|
> you use and taking your keyboard layout into account when defining keybindings for
|
|
> your individual needs.
|
|
|
|
5. Cagebreak can't do everything, but with scripting you can do most things.
|
|
Through the socket and with a bit of scripting, you can use the internal state
|
|
of cagebreak in combination with cagebreak commands and the full power of
|
|
a scripting language of your choice to do almost whatever you want.
|
|
|
|
> Example scripts can be found in the repository under `example_scripts/`.
|
|
|
|
## 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
|
|
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.
|
|
* Read the code.
|
|
* Read the documentation.
|
|
* Test whether the documentation matches the code.
|
|
* Test Cagebreak in more esoteric setups (many monitors, for instance).
|
|
* 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
|
|
[Cagebreak in the AUR](https://aur.archlinux.org/packages/cagebreak).
|
|
* The points above still apply.
|
|
|
|
### Philosophy
|
|
|
|
Cagebreak is currently developed to fit the needs of its creators.
|
|
|
|
The feature set is intentionally limited - we removed
|
|
support for a desktop background image for example.
|
|
|
|
Nonetheless, don't be intimidated by any other part of this file.
|
|
Do your best and we will collaborate toward a solution.
|
|
|
|
## Development
|
|
|
|
### 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.
|
|
|
|
However, Cagebreak may also work on other distributions given the
|
|
proper library versions (Some package maintainers have done this and it
|
|
seems to work (To date, we dealt with a few Issues and never felt the
|
|
need to ask for the distribution the user was having the issue on.)).
|
|
|
|
[](https://repology.org/project/cagebreak/versions)
|
|
|
|
You should use Arch Linux if you want to modify Cagebreak
|
|
for yourself.
|
|
|
|
### Review Requirements
|
|
|
|
Project-repo will review your proposal before your implementation for feasibility
|
|
and desirability. After your pull request, the code will be reviewed in conjunction
|
|
with all other changes before the release as per the release procedure.
|
|
|
|
All reviews performed by project-repo are verified by at least two people internally.
|
|
|
|
### Developer Certificate of Origin (DCO)
|
|
|
|
On any pull requests please include a
|
|
|
|
```
|
|
signed-off-by: YOUR IDENTIFIER OR NAME
|
|
```
|
|
|
|
DCO statement.
|
|
|
|
By doing this you claim that you are legally allowed to contribute the
|
|
code and agree to let project-repo publish it under the MIT License.
|
|
|
|
#### Development Environment
|
|
|
|
CAVEAT: This script works exclusively on Arch Linux, which, as outlined above,
|
|
is the development distribution of Cagebreak.
|
|
|
|
Cloning the Cagebreak repository and building it is sufficient as a starting point.
|
|
|
|
All other dependencies can be installed by invoking
|
|
|
|
```
|
|
meson compile devel-install -C build
|
|
```
|
|
|
|
if meson is already available or
|
|
|
|
```
|
|
./scripts/install-development-environment
|
|
```
|
|
|
|
otherwise.
|
|
|
|
#### Scripts
|
|
|
|
Cagebreak provides a few convenience tools to facilitate development.
|
|
|
|
##### Fuzzing
|
|
|
|
If your fuzzing corpus is located in the directory `fuzz_corpus` you can
|
|
just call:
|
|
|
|
```
|
|
meson compile fuzz -C build
|
|
```
|
|
|
|
If you want to use a different directory, configure cagebreak with
|
|
`-Dcorpus=OTHERDIRECTORY` or call `./scripts/fuzz OTHERDIRECTORY`.
|
|
|
|
##### Adjusting Epoch
|
|
|
|
To facilitate the creation of reproducible man pages an arbitrary release
|
|
time has to be set in `meson.build`:
|
|
|
|
```
|
|
meson compile adjust-epoch -C build
|
|
```
|
|
|
|
or
|
|
|
|
```
|
|
./scripts/adjust-epoch
|
|
```
|
|
|
|
##### Git tag
|
|
|
|
If you are on the master branch, everything is ready and you want to create
|
|
a release tag you can call:
|
|
|
|
```
|
|
meson compile git-tag -C build
|
|
```
|
|
|
|
If you want to use another signing key than the prespecified one, configure
|
|
Cagebreak with `-Dgpg_id=GPGID`.
|
|
|
|
```
|
|
./scripts/git-tag GPGID CBVERSION
|
|
```
|
|
|
|
can be used alternatively.
|
|
|
|
##### Output Hashes
|
|
|
|
Hashes of release versions of all binaries can be output to `local-hashes.txt`
|
|
via:
|
|
|
|
```
|
|
meson compile output-hashes -C build
|
|
```
|
|
|
|
Or
|
|
|
|
```
|
|
./scripts/output-hashes VERSION
|
|
```
|
|
|
|
if meson is unavailable.
|
|
|
|
##### Create Signatures
|
|
|
|
Creation of signatures for releases can be achieved through:
|
|
|
|
```
|
|
meson compile create-sigs -C build
|
|
```
|
|
|
|
Configure Cagebreak with `-Dgpg_id=GPGID` for a different gpg signing
|
|
key.
|
|
|
|
Without meson use:
|
|
|
|
```
|
|
./scripts/create-signatures GPGID
|
|
```
|
|
|
|
##### Set Version Number
|
|
|
|
Once the version number is set within meson.build, you can use
|
|
|
|
```
|
|
meson compile set-ver -C build
|
|
```
|
|
|
|
to set the version number in the man pages and README repology minversion.
|
|
|
|
Use of the script without meson is discouraged because meson.build is
|
|
not touched by the script.
|
|
|
|
##### Create Release Artefacts
|
|
|
|
The following command generates the release artefacts which must be created
|
|
once a release is completely ready to be published (the commit is tagged with
|
|
the version of the master branch, etc.):
|
|
|
|
```
|
|
meson compile create-artefacts -C build
|
|
```
|
|
|
|
Use of the script version is discouraged.
|
|
|
|
### GCC and -fanalyzer
|
|
|
|
Cagebreak should compile with any reasonably new gcc or clang. Consider
|
|
a gcc version of at least [10.1](https://gcc.gnu.org/gcc-10/changes.html) if
|
|
you want to get the benefit of the brand-new
|
|
[-fanalyzer](https://gcc.gnu.org/onlinedocs/gcc/Static-Analyzer-Options.html)
|
|
flag. However, this new flag sometimes produces false-postives and we
|
|
selectively disable warnings for affected code segments as described below.
|
|
|
|
Meson is configured to set `CG_HAS_FANALYZE` if `-fanalyzer` is available.
|
|
Therefore, to maintain portability, false-positive fanalyzer warnings are to be
|
|
disabled using the following syntax:
|
|
|
|
```
|
|
#if CG_HAS_FANALYZE
|
|
#pragma GCC diagnostic push
|
|
#pragma GCC diagnostic ignored "WARNING OPTION"
|
|
#endif
|
|
```
|
|
and after
|
|
|
|
```
|
|
#if CG_HAS_FANALYZE
|
|
#pragma GCC diagnostic pop
|
|
#endif
|
|
```
|
|
|
|
### Test Suite
|
|
|
|
```
|
|
meson test -C build
|
|
```
|
|
|
|
invokes all tests. This is required for a release to occur.
|
|
|
|
There are four test suites:
|
|
|
|
* basic: tests actual outward-facing functionality
|
|
* Note optional dependencies for efficient socket interaction
|
|
* nc (openbsd-netcat)
|
|
* jq
|
|
* devel: tests internal properties of the repository
|
|
* Note potentially heavier dependencies such as
|
|
* shellcheck
|
|
* clang-format
|
|
* devel-long: applies more costly testing
|
|
* Note potentially heavier dependencies such as
|
|
* scan-build (static analysis (including security-relevant issues))
|
|
* release: tests release specific considerations
|
|
* Note that this is only expected to pass just before
|
|
a release. This checks mostly administrative things
|
|
to check that a release is ready.
|
|
* Note that non-auto tests are files in `release-non-auto-checks`
|
|
and have to contain the release version and current date in
|
|
YYYY-mm-dd format on seperate lines. This is our imperfect attempt
|
|
to guarantee some hard-to-automate checks are carried out before
|
|
a release is undertaken.
|
|
|
|
Every commit should pass at least the basic and devel suites.
|
|
|
|
It is expected that cagebreak passes at least the
|
|
basic, devel and devel-long suites when commits are pushed:
|
|
|
|
```
|
|
meson test -C build --suite basic --suite devel
|
|
```
|
|
|
|
The basic suite can be used to test a binary. This is
|
|
useful for PKGBUILDs and their equivalents in other
|
|
systems.
|
|
|
|
```
|
|
meson test -C build --suite basic
|
|
```
|
|
|
|
### Fuzzing
|
|
|
|
Along with the project source code, a fuzzing framework based on `libfuzzer` is
|
|
supplied. This allows for the testing of the parsing code responsible for reading
|
|
the `cagebreak` configuration file. When `libfuzzer` is available (please
|
|
use the `clang` compiler to enable it), building the fuzz-testing software can
|
|
be enabled by passing `-Dfuzz=true` to meson. This generates a `build/fuzz/fuzz-parse`
|
|
binary according to the `libfuzzer` specifications. Further documentation on
|
|
how to run this binary can be found [here](https://llvm.org/docs/LibFuzzer.html).
|
|
|
|
Here is an example workflow:
|
|
|
|
```
|
|
rm -rf build
|
|
CC=clang meson setup build -Dfuzz=true -Db_sanitize=address,undefined -Db_lundef=false
|
|
ninja -C build/
|
|
mkdir build/fuzz_corpus
|
|
cp examples/config build/fuzz_corpus/
|
|
WLR_BACKENDS=headless ./build/fuzz-parse -jobs=12 -max_len=50000 -close_fd_mask=3 build/fuzz_corpus/
|
|
```
|
|
|
|
You may want to tweak `-jobs` or add other options depending on your own setup.
|
|
We have found code path discovery to increase rapidly when the fuzzer is supplied
|
|
with an initial config file. We are working on improving our fuzzing coverage to
|
|
find bugs in other areas of the code.
|
|
|
|
#### Caveat
|
|
|
|
Currently, there are memory leaks which do not seem to stem from our code but rather
|
|
the code of wlroots or some other library we depend on. We are working on the problem.
|
|
In the meantime, add `-Db_detect-leaks=0` to the meson command to exclude memory leaks.
|
|
|
|
### Reproducible Builds
|
|
|
|
Cagebreak offers reproducible builds given the exact library versions specified
|
|
in `meson.build`. Should a version mismatch occur, a warning will be emitted. We have
|
|
decided on this compromise to allow flexibility and security. In general we will
|
|
adapt the versions to the packages available under Arch Linux at the time of
|
|
release.
|
|
|
|
There are reproducibility issues up to and including release `1.2.0`. See
|
|
`Issue 5` in [Bugs.md](Bugs.md).
|
|
|
|
#### Reproducible Build Instructions
|
|
|
|
All hashes and signatures are provided for the following build instructions.
|
|
|
|
```
|
|
meson setup build -Dxwayland=true -Dman-pages=true --buildtype=release
|
|
ninja -C build
|
|
```
|
|
|
|
#### Hashes for Builds
|
|
|
|
For every release after 1.0.5, hashes will be provided.
|
|
|
|
For every release after 1.7.0, hashes will be provided for man pages too.
|
|
|
|
See [Hashes.md](Hashes.md)
|
|
|
|
#### GPG Signatures
|
|
|
|
For every release after 1.0.5, a GPG signature will be provided in `signatures`.
|
|
|
|
The current signature is called `cagebreak.sig`, whereas all older signatures
|
|
will be named after their release version.
|
|
|
|
Due to errors in the release process, the releases 1.7.1 and 1.7.2 did not include the release
|
|
signatures in the appropriate folder of the git repository. However, signatures were provided
|
|
as release-artefacts at the time of release. The signatures were introduced into the
|
|
repository with 1.7.3. The integrity of cagebreak is still the same because the signatures were
|
|
provided as release-artefacts (which were themselves signed) and the hashes in Hashes.md
|
|
are part of a signed release tag.
|
|
|
|
#### Signing Keys
|
|
|
|
All releases are signed by at least one of the following collection of
|
|
keys.
|
|
|
|
* E79F6D9E113529F4B1FFE4D5C4F974D70CEC2C5B
|
|
* 4739D329C9187A1C2795C20A02ABFDEC3A40545F
|
|
* 7535AB89220A5C15A728B75F74104CC7DCA5D7A8
|
|
* 827BC2320D535AEAD0540E6E2E66F65D99761A6F
|
|
* A88D7431E5BAAD0B6EAE550AC8D61D8BD4FA3C46
|
|
* 8F872885968EB8C589A32E9539ACC012896D450F
|
|
* 896B92AF738C974E0065BF42F2576BD366156BB9
|
|
* AA927AFD50AF7C6810E69FE8274F2C605359E31B
|
|
* BE2DED372287BC4EB2213E13A0C743848A638955
|
|
* 0F3476E4B2404F95EC41600683D5810F7911B020
|
|
* 4E82C72C6B3E58A7BC4FF8554909F84CA83BB867
|
|
* 5AEB1A2EB0D13F67E306AC59DC0CC81BE006FD85
|
|
|
|
Should we at any point retire a key, we will only replace it with keys signed
|
|
by at least one of the above collection.
|
|
|
|
We registered project-repo.co and added mail addresses after release `1.3.0`.
|
|
|
|
We now have a mail address and its key is signed by signing keys. See Security
|
|
Bugs for details.
|
|
|
|
The full public keys can be found in `keys/` along with any revocation certificates.
|
|
|
|
### Versioning & Branching Strategy
|
|
|
|
Cagebreak uses [semantic versioning](https://semver.org).
|
|
|
|
There are three permanent branches in cagebreak:
|
|
|
|
* `master` (for releases)
|
|
* `development` (for polishing code between releases)
|
|
* `hotfix` (for small emergent releases, usually up-to-date with master)
|
|
|
|
Releases are merged to master as per the release procedure, with
|
|
reasonable exceptions as the situation requires.
|
|
|
|
The release commit is tagged with the release version.
|
|
|
|
In the past, our git history did not perfectly reflect this scheme.
|
|
|
|
### Release Procedure
|
|
|
|
The release procedure outlines the process for a release to occur.
|
|
|
|
* [ ] `git checkout development`
|
|
* [ ] `git pull origin development`
|
|
* [ ] `git push origin development`
|
|
* [ ] Arch Build System is up to date
|
|
* [ ] `meson test -C build/` just to get an overview
|
|
* [ ] Update internal wiki
|
|
* [ ] Adjust version number in meson.build
|
|
* [ ] `meson compile set-ver -C build`
|
|
* [ ] Add new files to meson.build or hardcoded testing variable
|
|
* [ ] Commit changes
|
|
* [ ] `git push origin development`
|
|
* [ ] Complete relevant documentation
|
|
* [ ] New features
|
|
* [ ] tests added and old test scripts adjusted
|
|
* [ ] man pages
|
|
* [ ] cagebreak
|
|
* [ ] cagebreak-config
|
|
* [ ] cagebreak-socket
|
|
* [ ] example config
|
|
* [ ] FAQ.md
|
|
* [ ] Changelog.md for major and minor releases but not patches
|
|
* [ ] Check changes for SECURITY.md relevance (changes to socket scope for example)
|
|
* [ ] Synchronize any socket changes to cagebreak-socket man page
|
|
* [ ] Document fixed bugs in Bugs.md
|
|
* [ ] Include issue discussion from github, where applicable
|
|
* [ ] Commit changes
|
|
* [ ] `git push origin development`
|
|
* [ ] Testing
|
|
* [ ] Manual testing
|
|
* [ ] `meson compile fuzz -C build` for at least one hour
|
|
* [ ] Complete release-non-auto-checks
|
|
* [ ] Use `meson compile output-hashes -C build` to add Hashes or aid in repro check
|
|
* [ ] `meson compile create-signatures -C build`
|
|
* [ ] Commit and push signatures, hashes and non-auto-check files
|
|
* [ ] `meson test -C build` passes everything except some release tests
|
|
* [ ] `git add` relevant files
|
|
* [ ] `git commit`
|
|
* [ ] `git push origin development`
|
|
* [ ] `git checkout master`
|
|
* [ ] `git merge --squash development`
|
|
* [ ] `git commit` and insert message
|
|
* [ ] `meson compile git-tag -C build`
|
|
* [ ] `meson compile create-artefacts -C build`
|
|
* [ ] `meson test -C build` THIS MUST PASS WITHOUT ANY FAILURES WHATSOEVER
|
|
* [ ] `git push --tags origin master`
|
|
* [ ] `git checkout development` (merge to development depends on whether release was a hotfix)
|
|
* [ ] `git merge master`
|
|
* [ ] `git push --tags origin development`
|
|
* [ ] `git checkout hotfix` (hotfix is to be kept current with master after releases)
|
|
* [ ] `git merge master`
|
|
* [ ] `git push --tags origin hotfix`
|
|
* [ ] Upload archives and signatures as release assets
|
|
* [ ] Manage package release
|
|
|
|
## Roadmap
|
|
|
|
Cagebreak plans to do or keep doing the following things
|
|
in the future:
|
|
|
|
* React to all issues.
|
|
* Add or modify features, which the authors find convenient or important.
|
|
* Improve the [OpenSSF Best Practices Badge Program](https://bestpractices.coreinfrastructure.org/en) level
|
|
|
|
## Governance
|
|
|
|
Cagebreak is managed by project-repo.
|
|
|
|
Project-repo is a pseudonym of at least two individuals acting
|
|
as benevolent dictators for the project by the others mutual consent.
|
|
|
|
The individuals comprising project-repo are not otherwise associated
|
|
by payment from any organisation or grant.
|
|
|
|
For all intents and purposes consider project-repo as a single
|
|
benevolent dictator for life that happens to occupy at least two brains.
|
|
|
|
### Roles
|
|
|
|
There are members of project-repo and those who are not.
|
|
|
|
There are no specific roles forced unto anyone.
|
|
|
|
### Bus Factor
|
|
|
|
The Bus Factor is a measure of how many people have to be
|
|
incapacitated for a project to be unable to continue.
|
|
|
|
The current bus factor for Cagebreak is: 1
|
|
|
|
Project-repo could still react to issues (even confidential
|
|
e-mails) and fix easier issues if any one individual were
|
|
incapacitated.
|
|
|
|
However, not all aspects of the code or release engineering
|
|
are fully resilient to the loss of any one individual.
|
|
|
|
We strive to improve the Bus Factor to at least two in all
|
|
aspects of Cagebreak.
|
|
|
|
### Governance Issues
|
|
|
|
Anyone can use the information in [SECURITY.md](SECURITY.md) to
|
|
contact the members of project-repo and bring governance
|
|
issues to their attention.
|
|
|
|
## Bugs
|
|
|
|
For any bug, please [create an issue](https://github.com/project-repo/cagebreak/issues/new) on
|
|
[GitHub](https://github.com/project-repo/cagebreak).
|
|
|
|
Fixed bugs are to be assigned a number and summarized inside Bugs.md for future reference
|
|
independent of github, in case this service is unavailable.
|
|
|
|
For other means of contacting the Cagebreak authors and for security issues
|
|
see [SECURITY.md](SECURITY.md).
|
|
|
|
## Accessibility
|
|
|
|
* We use text input/output to interact with the user whenever possible. For
|
|
example, sending text-based commands to the cagebreak sockets allows
|
|
one to change every configurable feature of cagebreak.
|
|
* Color is displayed but never a vital part to operating cagebreak.
|
|
* Text size can be increased and background color adjusted using text commands.
|
|
* There is no screen reader support per se but using a screen reader on socket output
|
|
would work and cagebreak does not preclude the use of a screen reader
|
|
for any software run with it.
|
|
|
|
## Contributors
|
|
|
|
* Aisha Tammy
|
|
* [make man pages optional](https://github.com/project-repo/cagebreak/pull/4), released
|
|
in 1.6.0 with slight modifications
|
|
* Oliver Friedmann
|
|
* [Add output scaling](https://github.com/project-repo/cagebreak/pull/34), released
|
|
in 2.0.0 with slight modifications
|
|
|
|
## License
|
|
|
|
Copyright (c) 2020-2023 The Cagebreak authors
|
|
Copyright (c) 2018-2020 Jente Hidskes
|
|
Copyright (c) 2019 The Sway authors
|
|
|
|
Permission is hereby granted, free of charge, to any person obtaining a copy of
|
|
this software and associated documentation files (the "Software"), to deal in
|
|
the Software without restriction, including without limitation the rights to
|
|
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
|
|
of the Software, and to permit persons to whom the Software is furnished to do
|
|
so, subject to the following conditions:
|
|
|
|
The above copyright notice and this permission notice shall be included in all
|
|
copies or substantial portions of the Software.
|
|
|
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
SOFTWARE.
|