diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.md similarity index 70% rename from CONTRIBUTING.rst rename to CONTRIBUTING.md index d00d839f..5b603b59 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.md @@ -1,37 +1,30 @@ -Contributing -============ +# Contributing 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 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 want to report a bug: 1. Make sure that there isn't a similar issue already reported - `here `__. - + [here](https://github.com/gbdev/rgbds/issues). 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 smallest file you can. - -4. Create a new `issue `__. +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 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 be done. -1. Create a new `issue `__. - +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 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 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 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). Big changes will most likely require some discussion, so open an -`issue `__ 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 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 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. 1. Fork this repository. - -2. Checkout the ``master`` branch. - -3. Create a new branch to work on. You could still work on ``master``, but it's +2. Checkout the `master` branch. +3. Create a new branch to work on. You could still work on `master`, but it's 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 new warning (but it may be possible to remove some warning checks if it makes the code much easier). - -5. Format your changes according to ``clang-format``, which will reformat the - coding style according to our standards defined in ``.clang-format``. - -6. Create a pull request against the branch ``master``. - +5. Format your changes according to `clang-format`, which will reformat the + coding style according to our standards defined in `.clang-format`. +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 - ``git rebase -i origin/master`` to modify chains of commits. + `git rebase -i origin/master` to modify chains of commits. diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md new file mode 100644 index 00000000..27587a89 --- /dev/null +++ b/CONTRIBUTORS.md @@ -0,0 +1,33 @@ +# 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> diff --git a/CONTRIBUTORS.rst b/CONTRIBUTORS.rst deleted file mode 100644 index 16eed0b1..00000000 --- a/CONTRIBUTORS.rst +++ /dev/null @@ -1,57 +0,0 @@ -Contributors to RGBDS -===================== - -Original author ---------------- - -- Carsten Elton Sørensen - -Main contributors ------------------ - -- Justin Lloyd - -- Vegard Nossum - -- Anthony J. Bentley - -- stag019 - -- Antonio Niño Díaz - -- Eldred "ISSOtm" Habert - -- Sylvie "Rangi" Oukaour - -Other contributors ------------------- - -- Ben Hetherington - -- Björn Höhrmann - -- Christophe Staïesse - -- David Brotz - -- Jakub Kądziołka - -- James "JL2210" Larrowe - -- The Musl C library - -- obskyr - -- The OpenBSD Project - -- Quint Guvernator - -- Sanqui - -- YamaArashi - -- yenatch - -- phs - -- jidoc01 diff --git a/README.md b/README.md new file mode 100644 index 00000000..a74652c0 --- /dev/null +++ b/README.md @@ -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). diff --git a/README.rst b/README.rst deleted file mode 100644 index f2ec80e6..00000000 --- a/README.rst +++ /dev/null @@ -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 `__. - -The documentation of this toolchain can be viewed online `here `__. -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 `__. - -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 `__ -or via mail at ``rgbds at gbdev dot io``. - -1. Installing RGBDS -------------------- - -The `installation procedure `__ is available -online for various platforms. `Building from 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 `__, - `xLink `__, and - `RGBFix `__, - a Game Boy SM83 (GBZ80) assembler/linker system for DOS/Win32. - -- 1997-07-03: Sørensen releases `ASMotor `__, - 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 `__. - -- 2009-06-11: Vegard Nossum adapts the code to be more UNIX-like and releases - this version as `rgbds-linux `__. - -- 2010-01-12: Anthony J. Bentley `forks `__ Nossum's - repository. The fork becomes the reference implementation of RGBDS. - -- 2015-01-18: stag019 begins implementing `rgbgfx `__, - a PNG‐to‐Game Boy graphics converter, for eventual integration into RGBDS. - -- 2016-09-05: rgbgfx is `integrated `__ - into Bentley's repository. - -- 2017-02-23: Bentley's repository is moved to the `rednex `__ - organization. - -- 2018-01-26: The codebase is `relicensed `__ - under the MIT license. - -- 2020-09-15: The repository is `moved `__ - to the `gbdev `__ organization. - -- 2022-05-17: The `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" `__ -(`GitHub `__, MIT license), -by Aristide Grange, Imed Kacem, and Sébastien Martin. - -RGBGFX's color palette was taken from `SameBoy `__, with permission and help by `LIJI `__. diff --git a/RELEASE.md b/RELEASE.md new file mode 100644 index 00000000..fd135256 --- /dev/null +++ b/RELEASE.md @@ -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 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`. diff --git a/RELEASE.rst b/RELEASE.rst deleted file mode 100644 index ae987f34..00000000 --- a/RELEASE.rst +++ /dev/null @@ -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 `__ with - values for ``PACKAGE_VERSION_MAJOR``, ``PACKAGE_VERSION_MINOR``, - ``PACKAGE_VERSION_PATCH``, and ``PACKAGE_VERSION_RC``, as well as - `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 "`` and ``git push origin master``. - -2. Create a Git tag formatted as ``v..``, or - ``v..-rc`` for a release candidate. ``MAJOR``, - ``MINOR``, ``PATCH``, and ``RC`` should match their values from - `include/version.hpp `__. You can use ``git tag ``. - -3. Push the tag to GitHub. You can use ``git push origin ``. - - 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 `` and - ``git tag --delete ``. - -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 `__. - - For a release candidate, which creates a prerelease, you will have to - take these steps yourself. - - 1. Clone `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 ``. 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 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``.