mirror of
https://github.com/ascii-boxes/boxes.git
synced 2025-07-24 09:05:36 +02:00
95 lines
4.6 KiB
Markdown
95 lines
4.6 KiB
Markdown
---
|
|
title: Contributing
|
|
permalink: /contributing.html
|
|
created_at: 2014-12-23 22:50:09 +0100
|
|
last_modified_at: 2024-09-28 15:00:00 +0200
|
|
---
|
|
|
|
# Contributing
|
|
|
|
You are considering a contribution to *boxes*? That's fantastic!
|
|
|
|
All *boxes* development happens in our [GitHub project](https://github.com/{{ site.github }}). Here are a few links
|
|
with more details:
|
|
|
|
- [How to build from source]({{ site.baseurl }}/build.html)
|
|
- [How to write test cases]({{ site.baseurl }}/testing.html)
|
|
- [Bug Reports and Feature Requests](https://github.com/{{ site.github }}/issues)
|
|
|
|
Boxes has been around a long time. Great care was taken to make the *boxes* source code as compatible as possible
|
|
with all kinds of different platforms.
|
|
|
|
The planned functionality has long been implemented, and it is very stable. Development has thus slowed down and
|
|
concentrates on maintenance and contributor-driven changes.
|
|
|
|
This is why we attach great importance to contributions.
|
|
|
|
|
|
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
|
|
{% include heading.html
|
|
level=2
|
|
text="Contribution Process" %}
|
|
|
|
Changes must be introduced by creating pull requests on GitHub. Note that you can improve the *boxes* code as well as
|
|
the website content.
|
|
|
|
Ideas for new box designs should be submitted via GitHub, but since the most beautiful designs sometimes come from
|
|
non-technical people, emails are acceptable for those.
|
|
|
|
It is best to discuss the planned change before actually doing work on it by [creating an issue for
|
|
it](https://github.com/{{ site.github }}/issues){:target="_blank"}. This is really not a big deal, and it helps to
|
|
ensure that your work will end up on the *boxes* master branch.
|
|
|
|
In order to create a pull request, you must first
|
|
[fork the *boxes* repo](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo){:target="_blank"}.
|
|
Then create a new feature branch for your change. Commit the changes to your feature branch. After that, you can
|
|
[create a pull
|
|
request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests){:target="_blank"}
|
|
against the *boxes* master.
|
|
|
|
The pull request must meet the criteria mentioned below. If additional changes are identified during the review, you
|
|
can simply push them to your forked repo, and the pull request will update automatically.
|
|
|
|
|
|
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
|
|
{% include heading.html
|
|
level=2
|
|
text="Pull Request Acceptance Criteria" %}
|
|
|
|
Since *boxes* is not actively being developed anymore, changes to the code base must be "production ready" from the
|
|
start. The following check list may help:
|
|
|
|
- The [GitHub workflow](https://github.com/{{ site.github }}/actions){:target="_blank"} must pass for the pull
|
|
request. This is indicated by a small green check mark next to your pull request.
|
|
- Provide [test cases]({{ site.baseurl}}/testing.html) for any code that you add. This helps make sure that nobody
|
|
else breaks it later.
|
|
- Cross-platform compatibility is very important for *boxes*. Since *boxes* does not (and cannot really) make use of
|
|
*autoconf*, the C code itself must work on every platform. In other words, you can use only such C commands that
|
|
are known on every platform. When in doubt, restrict yourself to commands that you already find in the current
|
|
code base.
|
|
|
|
These criteria apply only to code changes. (Although other changes should not break the build, either.)
|
|
|
|
|
|
{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
|
|
{% include heading.html
|
|
level=2
|
|
text="Debug Output" %}
|
|
|
|
*Boxes* has some debug logging built in, which may come in handy when troubleshooting during development.
|
|
It can be activated using the undocumented option `-x debug`. Optionally, `debug` may be followed by a colon and a
|
|
comma-separated list of "debug areas" which may be used to turn debug logging on and off for those sections of code.
|
|
Possible "debug areas" are `main`, `regexp`, `parser`, `lexer`, and `discovery`. The default debug area is `main`.
|
|
The option `-x debug:all` is available to activate all debug areas at the same time.
|
|
|
|
Debug logging requires a version of *boxes* newer than 2.3.0, or compiling from the current source.
|
|
|
|
The debug log messages are not super valuable. Don't expect too much. The author added them a long time ago
|
|
without thinking about other people reading them.
|
|
|
|
|
|
<h2 id="contributors" class="text-muted">Contributors</h2>
|
|
|
|
<p class="text-muted">Information on the people behind <i>boxes</i> has moved to
|
|
<a href="{{ site.baseurl }}/team.html">its own page</a>.</p>
|