gbdev/rgbds
1
0
Fork 0
mirror of https://github.com/gbdev/rgbds.git synced 2025-11-20 10:12:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

Convert reStructuredText to Markdown

Browse Source
This commit is contained in:
Rangi42
2024-02-18 14:06:49 -05:00
committed by Eldred Habert
parent f1b6ef204d
commit 289910fe83
7 changed files with 260 additions and 326 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
CONTRIBUTING.rst → CONTRIBUTING.md
View File

@@ -1,37 +1,30 @@
Contributing # Contributing
============
RGBDS was created in the late '90s and has received contributions from several RGBDS was created in the late '90s and has received contributions from several
developers since then. It wouldn't have been possible to get to this point developers since then. It wouldn't have been possible to get to this point
without their work, and it is always open to the contributions of other people. without their work, and it is always open to the contributions of other people.
Reporting Bugs ## Reporting Bugs
--------------
Bug reports are essential to improve RGBDS and they are always welcome. If you Bug reports are essential to improve RGBDS and they are always welcome. If you
want to report a bug: want to report a bug:
1. Make sure that there isn't a similar issue already reported 1. Make sure that there isn't a similar issue already reported
`here <https://github.com/gbdev/rgbds/issues>`__. [here](https://github.com/gbdev/rgbds/issues).
2. Figure out a way of reproducing it reliably. 2. Figure out a way of reproducing it reliably.
3. If there is a piece of code that triggers the bug, try to reduce it to the 3. If there is a piece of code that triggers the bug, try to reduce it to the
smallest file you can. smallest file you can.
4. Create a new [issue](https://github.com/gbdev/rgbds/issues).
4. Create a new `issue <https://github.com/gbdev/rgbds/issues>`__.
Of course, it may not always be possible to give an accurate bug report, but it Of course, it may not always be possible to give an accurate bug report, but it
always helps to fix it. always helps to fix it.
Requesting new features ## Requesting new features
-----------------------
If you come up with a good idea that could be implemented, you can propose it to If you come up with a good idea that could be implemented, you can propose it to
be done. be done.
1. Create a new `issue <https://github.com/gbdev/rgbds/issues>`__. 1. Create a new [issue](https://github.com/gbdev/rgbds/issues).
2. Try to be as accurate as possible. Describe what you need and why you need 2. Try to be as accurate as possible. Describe what you need and why you need
it, maybe with examples. it, maybe with examples.
@@ -40,8 +33,7 @@ simple requests are more likely to catch the interest of a contributor than
complicated ones. If you really need something to be done, and you think you can complicated ones. If you really need something to be done, and you think you can
implement it yourself, you can always contribute to RGBDS with your own code. implement it yourself, you can always contribute to RGBDS with your own code.
Contributing code ## Contributing code
-----------------
If you want to contribute with your own code, whether it is to fix a current If you want to contribute with your own code, whether it is to fix a current
issue or to add something that nobody had requested, you should first consider issue or to add something that nobody had requested, you should first consider
@@ -49,7 +41,7 @@ if your change is going to be small (and likely to be accepted as-is) or big
(and will have to go through some rework). (and will have to go through some rework).
Big changes will most likely require some discussion, so open an Big changes will most likely require some discussion, so open an
`issue <https://github.com/gbdev/rgbds/issues>`__ and explain what you want to [issue](https://github.com/gbdev/rgbds/issues) and explain what you want to
do and how you intend to do it. If you already have a prototype, it's always a do and how you intend to do it. If you already have a prototype, it's always a
good idea to show it. Tests help, too. good idea to show it. Tests help, too.
@@ -59,25 +51,19 @@ but doesn't know that there's someone working on it.
Note that you must contribute all your changes under the MIT License. If you are Note that you must contribute all your changes under the MIT License. If you are
just modifying a file, you don't need to do anything (maybe update the copyright just modifying a file, you don't need to do anything (maybe update the copyright
years). If you are adding new files, you need to use the ``SPDX-License-Identifier: MIT`` years). If you are adding new files, you need to use the `SPDX-License-Identifier: MIT`
header. header.
1. Fork this repository. 1. Fork this repository.
2. Checkout the `master` branch.
2. Checkout the ``master`` branch. 3. Create a new branch to work on. You could still work on `master`, but it's
3. Create a new branch to work on. You could still work on ``master``, but it's
easier that way. easier that way.
4. Compile your changes with `make develop` instead of just `make`. This
4. Compile your changes with ``make develop`` instead of just ``make``. This
target checks for additional warnings. Your patches shouldn't introduce any target checks for additional warnings. Your patches shouldn't introduce any
new warning (but it may be possible to remove some warning checks if it makes new warning (but it may be possible to remove some warning checks if it makes
the code much easier). the code much easier).
5. Format your changes according to `clang-format`, which will reformat the
5. Format your changes according to ``clang-format``, which will reformat the coding style according to our standards defined in `.clang-format`.
coding style according to our standards defined in ``.clang-format``. 6. Create a pull request against the branch `master`.
6. Create a pull request against the branch ``master``.
7. Be prepared to get some comments about your code and to modify it. Tip: Use 7. Be prepared to get some comments about your code and to modify it. Tip: Use
``git rebase -i origin/master`` to modify chains of commits. `git rebase -i origin/master` to modify chains of commits.

33
CONTRIBUTORS.md Normal file
View File

@@ -0,0 +1,33 @@
# Contributors to RGBDS
## Original author
- Carsten Elton Sørensen &lt;csoren@gmail.com&gt;
## Main contributors
- Justin Lloyd &lt;jlloyd@imf.la&gt;
- Vegard Nossum &lt;vegard.nossum@gmail.com&gt;
- Anthony J. Bentley &lt;anthony@anjbe.name&gt;
- stag019 &lt;stag019@gmail.com&gt;
- Antonio Niño Díaz &lt;antonio_nd@outlook.com&gt;
- Eldred "ISSOtm" Habert &lt;eldredhabert0@gmail.com&gt;
- Sylvie "Rangi" Oukaour &lt;http://github.com/Rangi42&gt;
## Other contributors
- Ben Hetherington &lt;dev@ben-h.uk&gt;
- Björn Höhrmann &lt;bjoern@hoehrmann.de&gt;
- Christophe Staïesse &lt;chastai@skynet.be&gt;
- David Brotz &lt;dbrotz007@gmail.com&gt;
- Jakub Kądziołka &lt;kuba@kadziolka.net&gt;
- James "JL2210" Larrowe &lt;https://github.com/JL2210&gt;
- The Musl C library &lt;http://www.musl-libc.org&gt;
- obskyr &lt;powpowd@gmail.com&gt;
- The OpenBSD Project &lt;http://www.openbsd.org&gt;
- Quint Guvernator &lt;quint@guvernator.net&gt;
- Sanqui &lt;gsanky@gmail.com&gt;
- YamaArashi &lt;shadow962@live.com&gt;
- yenatch &lt;yenatch@gmail.com&gt;
- phs &lt;phil@philhsmith.com&gt;
- jidoc01 &lt;jidoc01@naver.com&gt;

57
CONTRIBUTORS.rst
View File

@@ -1,57 +0,0 @@
Contributors to RGBDS
=====================
Original author
---------------
- Carsten Elton Sørensen <csoren@gmail.com>
Main contributors
-----------------
- Justin Lloyd <jlloyd@imf.la>
- Vegard Nossum <vegard.nossum@gmail.com>
- Anthony J. Bentley <anthony@anjbe.name>
- stag019 <stag019@gmail.com>
- Antonio Niño Díaz <antonio_nd@outlook.com>
- Eldred "ISSOtm" Habert <eldredhabert0@gmail.com>
- Sylvie "Rangi" Oukaour <http://github.com/Rangi42>
Other contributors
------------------
- Ben Hetherington <dev@ben-h.uk>
- Björn Höhrmann <bjoern@hoehrmann.de>
- Christophe Staïesse <chastai@skynet.be>
- David Brotz <dbrotz007@gmail.com>
- Jakub Kądziołka <kuba@kadziolka.net>
- James "JL2210" Larrowe <https://github.com/JL2210>
- The Musl C library <http://www.musl-libc.org>
- obskyr <powpowd@gmail.com>
- The OpenBSD Project <http://www.openbsd.org>
- Quint Guvernator <quint@guvernator.net>
- Sanqui <gsanky@gmail.com>
- YamaArashi <shadow962@live.com>
- yenatch <yenatch@gmail.com>
- phs <phil@philhsmith.com>
- jidoc01 <jidoc01@naver.com>

144
README.md Normal file
View File

@@ -0,0 +1,144 @@
# RGBDS
RGBDS (Rednex Game Boy Development System) is a free assembler/linker package
for the Game Boy and Game Boy Color. It consists of:
- rgbasm (assembler)
- rgblink (linker)
- rgbfix (checksum/header fixer)
- rgbgfx (PNG‐to‐Game Boy graphics converter)
This is a fork of the original RGBDS which aims to make the programs more like
other UNIX tools.
This toolchain is maintained [on GitHub](https://github.com/gbdev/rgbds).
The documentation of this toolchain can be viewed online [here](https://rgbds.gbdev.io/docs/).
It is generated from the man pages found in this repository.
The source code of the website itself is on GitHub as well under the repo
[rgbds-www](https://github.com/gbdev/rgbds-www).
If you want to contribute or maintain RGBDS, and have questions regarding the code, its
organisation, etc. you can find the maintainers [on the gbdev community channels](https://gbdev.io/chat)
or via mail at `rgbds at gbdev dot io`.
## 1. Installing RGBDS
The [installation procedure](https://rgbds.gbdev.io/install) is available
online for various platforms. [Building from source](https://rgbds.gbdev.io/install/source)
is possible using `make` or `cmake`; follow the link for more detailed instructions.
```sh
make
sudo make install
```
```sh
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
cmake --install build
```
## 2. RGBDS Folder Organization
The RGBDS source code file structure is as follows:
```
.
├── .github/
│ ├── scripts/
│ │ └── ...
│ └── workflows/
│ └── ...
├── contrib/
│ ├── zsh_compl/
│ │ └── ...
│ └── ...
├── include/
│ └── ...
├── man/
│ └── ...
├── src/
│ ├── asm/
│ │ └── ...
│ ├── extern/
│ │ └── ...
│ ├── fix/
│ │ └── ...
│ ├── gfx/
│ │ └── ...
│ ├── link/
│ │ └── ...
│ ├── CMakeLists.txt
│ └── ...
├── test/
│ ├── ...
│ └── run-tests.sh
├── .clang-format
├── CMakeLists.txt
├── Dockerfile
├── Makefile
└── README.md
```
- `.github/` - files and scripts related to the integration of the RGBDS codebase with
GitHub.
* `scripts/` - scripts used by workflow files.
* `workflows/` - CI workflow description files.
- `contrib/` - scripts and other resources which may be useful to users and developers of
RGBDS.
* `zsh_compl` contains tab completion scripts for use with zsh. Put them somewhere in
your `fpath`, and they should auto-load.
* `bash_compl` contains tab completion scripts for use with bash. Run them with `source`
somewhere in your `.bashrc`, and they should load every time you open a shell.
- `include/` - header files for the respective source files in `src`.
- `man/` - manual pages.
- `src/` - source code of RGBDS.
* Note that the code unique to each RGBDS tool is stored in its respective subdirectory
(rgbasm's code is in `src/asm/`, for example). `src/extern/` contains code imported from
external sources.
- `test/` - testing framework used to verify that changes to the code don't break or
modify the behavior of RGBDS.
- `.clang-format` - code style for automated C++ formatting with
[`clang-format`](https://clang.llvm.org/docs/ClangFormat.html).
- `Dockerfile` - defines how to build RGBDS with Docker.
## 3. History
- 1996-10-01: Carsten Sørensen (a.k.a. SurfSmurf) releases
[xAsm](http://otakunozoku.com/RGBDSdocs/asm.htm),
[xLink](http://otakunozoku.com/RGBDSdocs/link.htm), and
[RGBFix](http://otakunozoku.com/RGBDSdocs/fix.htm),
a Game Boy SM83 (GBZ80) assembler/linker system for DOS/Win32.
- 1997-07-03: Sørensen releases [ASMotor](http://otakunozoku.com/RGBDSdocs/geninfo.htm),
packaging the three programs together and moving towards making them a
general-purpose target-independent system.
- 1999-08-01: Justin Lloyd (a.k.a. Otaku no Zoku) adapts ASMotor to re-focus
on SM83 assembly/machine code, and releases this version as
[RGBDS](http://otakunozoku.com/rednex-gameboy-development-system/).
- 2009-06-11: Vegard Nossum adapts the code to be more UNIX-like and releases
this version as [rgbds-linux](https://github.com/vegard/rgbds-linux).
- 2010-01-12: Anthony J. Bentley [forks](https://github.com/bentley) Nossum's
repository. The fork becomes the reference implementation of RGBDS.
- 2015-01-18: stag019 begins implementing [rgbgfx](https://github.com/stag019/rgbgfx),
a PNG‐to‐Game Boy graphics converter, for eventual integration into RGBDS.
- 2016-09-05: rgbgfx is [integrated](https://github.com/gbdev/rgbds/commit/c3c31138ddbd8680d4e67957e387f2816798a71b)
into Bentley's repository.
- 2017-02-23: Bentley's repository is moved to the [rednex](https://github.com/rednex)
organization.
- 2018-01-26: The codebase is [relicensed](https://github.com/gbdev/rgbds/issues/128)
under the MIT license.
- 2020-09-15: The repository is [moved](https://github.com/gbdev/rgbds/issues/567)
to the [gbdev](https://github.com/gbdev) organization.
- 2022-05-17: The [rgbds.gbdev.io](https://rgbds.gbdev.io) website for RGBDS
documentation and downloads is published.
## 4. Acknowledgements
RGBGFX generates palettes using algorithms found in the paper
["Algorithms for the Pagination Problem, a Bin Packing with Overlapping Items"](http://arxiv.org/abs/1605.00558)
([GitHub](https://github.com/pagination-problem/pagination), MIT license),
by Aristide Grange, Imed Kacem, and Sébastien Martin.
RGBGFX's color palette was taken from [SameBoy](https://sameboy.github.io), with permission and help
by [LIJI](https://github.com/LIJI32).

171
README.rst
View File

@@ -1,171 +0,0 @@
RGBDS
=====
RGBDS (Rednex Game Boy Development System) is a free assembler/linker package
for the Game Boy and Game Boy Color. It consists of:
- rgbasm (assembler)
- rgblink (linker)
- rgbfix (checksum/header fixer)
- rgbgfx (PNG‐to‐Game Boy graphics converter)
This is a fork of the original RGBDS which aims to make the programs more like
other UNIX tools.
This toolchain is maintained `on GitHub <https://github.com/gbdev/rgbds>`__.
The documentation of this toolchain can be viewed online `here <https://rgbds.gbdev.io/docs/>`__.
It is generated from the man pages found in this repository.
The source code of the website itself is on GitHub as well under the repo
`rgbds-www <https://github.com/gbdev/rgbds-www>`__.
If you want to contribute or maintain RGBDS, and have questions regarding the code, its
organisation, etc. you can find the maintainers `on the gbdev community channels <https://gbdev.io/chat>`__
or via mail at ``rgbds at gbdev dot io``.
1. Installing RGBDS
-------------------
The `installation procedure <https://rgbds.gbdev.io/install>`__ is available
online for various platforms. `Building from source <https://rgbds.gbdev.io/install/source>`__
is possible using ``make`` or ``cmake``; follow the link for more detailed instructions.
.. code:: sh
make
sudo make install
.. code:: sh
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
cmake --install build
2. RGBDS Folder Organization
----------------------------
The RGBDS source code file structure is as follows:
::
.
├── .github/
│ ├── scripts/
│ │ └── ...
│ └── workflows/
│ └── ...
├── contrib/
│ ├── zsh_compl/
│ │ └── ...
│ └── ...
├── include/
│ └── ...
├── man/
│ └── ...
├── src/
│ ├── asm/
│ │ └── ...
│ ├── extern/
│ │ └── ...
│ ├── fix/
│ │ └── ...
│ ├── gfx/
│ │ └── ...
│ ├── link/
│ │ └── ...
│ ├── CMakeLists.txt
│ └── ...
├── test/
│ ├── ...
│ └── run-tests.sh
├── .clang-format
├── CMakeLists.txt
├── Dockerfile
├── Makefile
└── README.rst
.. |clang-format| replace:: ``clang-format``
.. _clang-format: https://clang.llvm.org/docs/ClangFormat.html
- ``.github/`` - files and scripts related to the integration of the RGBDS codebase with
GitHub.
* ``scripts/`` - scripts used by workflow files.
* ``workflows/`` - CI workflow description files.
- ``contrib/`` - scripts and other resources which may be useful to users and developers of
RGBDS.
* ``zsh_compl`` contains tab completion scripts for use with zsh. Put them somewhere in
your ``fpath``, and they should auto-load.
* ``bash_compl`` contains tab completion scripts for use with bash. Run them with ``source``
somewhere in your ``.bashrc``, and they should load every time you open a shell.
- ``include/`` - header files for the respective source files in ``src``.
- ``man/`` - manual pages.
- ``src/`` - source code of RGBDS.
* Note that the code unique to each RGBDS tool is stored in its respective subdirectory
(rgbasm -> ``src/asm/``, for example). ``src/extern/`` contains code imported from
external sources.
- ``test/`` - testing framework used to verify that changes to the code don't break or
modify the behavior of RGBDS.
- ``.clang-format`` - code style for automated C++ formatting with |clang-format|_.
- ``Dockerfile`` - defines how to build RGBDS with Docker.
3. History
----------
- 1996-10-01: Carsten Sørensen (a.k.a. SurfSmurf) releases
`xAsm <http://otakunozoku.com/RGBDSdocs/asm.htm>`__,
`xLink <http://otakunozoku.com/RGBDSdocs/link.htm>`__, and
`RGBFix <http://otakunozoku.com/RGBDSdocs/fix.htm>`__,
a Game Boy SM83 (GBZ80) assembler/linker system for DOS/Win32.
- 1997-07-03: Sørensen releases `ASMotor <http://otakunozoku.com/RGBDSdocs/geninfo.htm>`__,
packaging the three programs together and moving towards making them a
general-purpose target-independent system.
- 1999-08-01: Justin Lloyd (a.k.a. Otaku no Zoku) adapts ASMotor to re-focus
on SM83 assembly/machine code, and releases this version as
`RGBDS <http://otakunozoku.com/rednex-gameboy-development-system/>`__.
- 2009-06-11: Vegard Nossum adapts the code to be more UNIX-like and releases
this version as `rgbds-linux <https://github.com/vegard/rgbds-linux>`__.
- 2010-01-12: Anthony J. Bentley `forks <https://github.com/bentley>`__ Nossum's
repository. The fork becomes the reference implementation of RGBDS.
- 2015-01-18: stag019 begins implementing `rgbgfx <https://github.com/stag019/rgbgfx>`__,
a PNG‐to‐Game Boy graphics converter, for eventual integration into RGBDS.
- 2016-09-05: rgbgfx is `integrated <https://github.com/gbdev/rgbds/commit/c3c31138ddbd8680d4e67957e387f2816798a71b>`__
into Bentley's repository.
- 2017-02-23: Bentley's repository is moved to the `rednex <https://github.com/rednex>`__
organization.
- 2018-01-26: The codebase is `relicensed <https://github.com/gbdev/rgbds/issues/128>`__
under the MIT license.
- 2020-09-15: The repository is `moved <https://github.com/gbdev/rgbds/issues/567>`__
to the `gbdev <https://github.com/gbdev>`__ organization.
- 2022-05-17: The `rgbds.gbdev.io <https://rgbds.gbdev.io>`__ website for RGBDS
documentation and downloads is published.
4. Acknowledgements
-------------------
RGBGFX generates palettes using algorithms found in the paper
`"Algorithms for the Pagination Problem, a Bin Packing with Overlapping Items" <http://arxiv.org/abs/1605.00558>`__
(`GitHub <https://github.com/pagination-problem/pagination>`__, MIT license),
by Aristide Grange, Imed Kacem, and Sébastien Martin.
RGBGFX's color palette was taken from `SameBoy <https://sameboy.github.io>`__, with permission and help by `LIJI <https://github.com/LIJI32>`__.

67
RELEASE.md Normal file
View File

@@ -0,0 +1,67 @@
# Releasing
This describes for the maintainers of RGBDS how to publish a new release on
GitHub.
1. Update, commit, and push [include/version.hpp](include/version.hpp) with
values for `PACKAGE_VERSION_MAJOR`, `PACKAGE_VERSION_MINOR`,
`PACKAGE_VERSION_PATCH`, and `PACKAGE_VERSION_RC`, as well as
[Dockerfile](Dockerfile) with a value for `ARG version`. Only define
`PACKAGE_VERSION_RC` if you are publishing a release candidate! You can
use <code>git commit -m "Release <i>&lt;version&gt;</i>"</code> and
`git push origin master`.
2. Create a Git tag formatted as <code>v<i>&lt;MAJOR&gt;</i>.<i>&lt;MINOR&gt;</i>.<i>&lt;PATCH&gt;</i></code>,
or <code>v<i>&lt;MAJOR&gt;</i>.<i>&lt;MINOR&gt;</i>.<i>&lt;PATCH&gt;</i>-rc<i>&lt;RC&gt;</i></code>
for a release candidate. <code><i>MAJOR</i></code>, <code><i>MINOR</i></code>,
<code><i>PATCH</i></code>, and <code><i>RC</i></code> should match their values from
[include/version.hpp](include/version.hpp). You can use <code>git tag <i>&lt;tag&gt;</i></code>.
3. Push the tag to GitHub. You can use <code>git push origin <i>&lt;tag&gt;</i></code>.
GitHub Actions will run the [create-release-artifacts.yaml](.github/workflows/create-release-artifacts.yaml)
workflow to detect the tag starting with "`v[0-9]`" and automatically do the following:
1. Build 32-bit and 64-bit RGBDS binaries for Windows with `cmake`.
2. Package the binaries into zip files.
3. Package the source code into a tar.gz file with `make dist`.
4. Create a draft GitHub release for the tag, attaching the three
packaged files. It will be a prerelease if the tag contains "`-rc`".
If an error occurred in the above steps, delete the tag and restart the
procedure. You can use <code>git push --delete origin <i>&lt;tag&gt;</i></code> and
<code>git tag --delete <i>&lt;tag&gt;</i></code>.
4. GitHub Actions will run the [create-release-docs.yml](.github/workflows/create-release-docs.yml)
workflow to add the release documentation to [rgbds-www](https://github.com/gbdev/rgbds-www).
For a release candidate, which creates a prerelease, you will have to
take these steps yourself.
1. Clone [rgbds-www](https://github.com/gbdev/rgbds-www). You can use
`git clone https://github.com/gbdev/rgbds-www.git`.
2. Make sure that you have installed `groff` and `mandoc`. You will
need `mandoc` 1.14.5 or later to support `-O toc`.
3. Run <code>.github/actions/get-pages.sh -r <i>&lt;path/to/rgbds-www&gt;</i> <i>&lt;tag&gt;</i></code>.
This will render the RGBDS documentation as HTML and PDF and copy it to
`rgbds-www`.
If you do not have `groff` installed, you can change
`groff -Tpdf -mdoc -wall` to `mandoc -Tpdf -I os=Linux` in
[.github/actions/get-pages.sh](.github/actions/get-pages.sh) and it
will suffice.
4. Commit and push the documentation. You can use <code>git commit -m
"Create RGBDS <i>&lt;tag&gt;</i> documentation"</code> and `git push origin master`
(within the `rgbds-www` directory, not RGBDS).
5. Write a changelog in the GitHub draft release.
6. Click the "Publish release" button to publish it!
7. Update the `release` branch. You can use `git push origin release`.

68
RELEASE.rst
View File

@@ -1,68 +0,0 @@
Releasing
=========
This describes for the maintainers of RGBDS how to publish a new release on
GitHub.
1. Update, commit, and push `include/version.hpp <include/version.hpp>`__ with
values for ``PACKAGE_VERSION_MAJOR``, ``PACKAGE_VERSION_MINOR``,
``PACKAGE_VERSION_PATCH``, and ``PACKAGE_VERSION_RC``, as well as
`Dockerfile <Dockerfile>`__ with a value for ``ARG version``. Only define
``PACKAGE_VERSION_RC`` if you are publishing a release candidate! You can
use ``git commit -m "Release <version>"`` and ``git push origin master``.
2. Create a Git tag formatted as ``v<MAJOR>.<MINOR>.<PATCH>``, or
``v<MAJOR>.<MINOR>.<PATCH>-rc<RC>`` for a release candidate. ``MAJOR``,
``MINOR``, ``PATCH``, and ``RC`` should match their values from
`include/version.hpp <include/version.hpp>`__. You can use ``git tag <tag>``.
3. Push the tag to GitHub. You can use ``git push origin <tag>``.
GitHub Actions will run the `create-release-artifacts.yaml
<.github/workflows/create-release-artifacts.yaml>`__ workflow to detect the
tag starting with "``v[0-9]``" and automatically do the following:
1. Build 32-bit and 64-bit RGBDS binaries for Windows with ``cmake``.
2. Package the binaries into zip files.
3. Package the source code into a tar.gz file with ``make dist``.
4. Create a draft GitHub release for the tag, attaching the three
packaged files. It will be a prerelease if the tag contains "``-rc``".
If an error occurred in the above steps, delete the tag and restart the
procedure. You can use ``git push --delete origin <tag>`` and
``git tag --delete <tag>``.
4. GitHub Actions will run the `create-release-docs.yml
<.github/workflows/create-release-docs.yml>`__ workflow to add the release
documentation to `rgbds-www <https://github.com/gbdev/rgbds-www>`__.
For a release candidate, which creates a prerelease, you will have to
take these steps yourself.
1. Clone `rgbds-www <https://github.com/gbdev/rgbds-www>`__. You can use
``git clone https://github.com/gbdev/rgbds-www.git``.
2. Make sure that you have installed ``groff`` and ``mandoc``. You will
need ``mandoc`` 1.14.5 or later to support ``-O toc``.
3. Run ``.github/actions/get-pages.sh -r <path/to/rgbds-www> <tag>``. This
will render the RGBDS documentation as HTML and PDF and copy it to
``rgbds-www``.
If you do not have ``groff`` installed, you can change
``groff -Tpdf -mdoc -wall`` to ``mandoc -Tpdf -I os=Linux`` in
`.github/actions/get-pages.sh <.github/actions/get-pages.sh>`__ and it
will suffice.
4. Commit and push the documentation. You can use ``git commit -m
"Create RGBDS <tag> documentation"`` and ``git push origin master``
(within the ``rgbds-www`` directory, not RGBDS).
5. Write a changelog in the GitHub draft release.
6. Click the "Publish release" button to publish it!
7. Update the ``release`` branch. You can use ``git push origin release``.