-
Notifications
You must be signed in to change notification settings - Fork 8
XYZ. How to release your core to the MEGA65 community
This guide serves as a checklist to maintain a consistent standard for all releases based on the MiSTer2MEGA65 (M2M) framework. Adhering to these guidelines ensures quality in both source code and accompanying files. It also makes sure that the great MEGA65 community learns about your core and therefore is able to enjoy it.
-
Change the header of the file
CORE/m2m-rom/m2mrom.asm
to fit your project: ReplaceYOUR-PROJECT-NAME
by your project's name (e.g.C64 for MEGA65
) and replaceGITHUB-REPO-SHORTNAME
by the GitHub repositories' name (e.g.C64MEGA65
). Delete the line "This ROM is loaded by" and replaceYOURNAME
andYEAR
. -
Similarly, change the header of the file
CORE/vhdl/top_mega65-r3.vhd
by removing the placeholders and adding your own project's details. -
Check the headers of all other files in
CORE/vhdl
and make sure that any generic statements like "your core" are replaced by information relevant to your core. -
In the folder
CORE/vhdl
use a command likegrep -irn @todo .
(or search manually) to find all occurances of@TODO
in all files located inCORE/vhdl
: Confirm if you are OK with the seemingly open TODO. Sometimes these are also just reminders for you to adjust some comment to the behavior of your actual core vs. the generic M2M framework's behavior. -
In
CORE/vhdl/main.vhd
: Make sure that you document and comment very well the way you wired the MiSTer core to the M2M framework, document certain decisions you made and why and document also why you feed certain default values into the MiSTer core (and don't forget to mention "special" behaviors such as low-active).
An alternate core for the MEGA65 consists at least of a .cor
binary file. It is a best practice to also offer a
raw bitstream .bit
file. Learn more about these two file types
here. Create .cor
files using the bit2core
tool:
- Download
bit2core
for your platform: @TODO-link-from-lydon - Compile
bit2core
by yourself: mega65-tools repository
The bit2core
tool outputs help if you start it without any parameters.
You need to create release binaries for each MEGA65 model. As of the time of writing this article, there are three
models out there in the wild: R2
, R3
and R3A
. While R3
and R3A
are very similar and are able to use the
very same release binaries, R2
is very different. Soon there will be more advanced MEGA65 models.
Currently, MiSTer2MEGA65 only supports R3
and R3A
.
If your core uses M2M's ability to save the On-Screen-Menu's settings persistently, then you need to prepare and ship a config file using M2M/tools/make_config.sh and name it as configured in globals.vhd.
Include a README.md
file in the repo's root folder that provides a clear overview of your project, installation
instructions, and usage examples. Make sure that the explanations you give in the user's manual are detailed enough
so that a user who never heard of your core before is able to install, use and enjoy it.
Here
is an example of how such a README.md
could look like.
-
Be a nice member of the Open Source community and always give credit to everybody who contributed to your core in the
AUTHORS
file that is located in the root folder of the repository. -
In the case of most MiSTer2MEGA65 projects these are at least the authors of the MiSTer project that you are porting and more often than not the original authors of the project(s) that the MiSTer folks took to create the MiSTer port. You will find this information in the MiSTer code repository and sometimes in the original projects' repositories mentioned in the MiSTer repository. Have a look here how a good AUTHORS file looks like and examine the file from line 33 on how it mentions all the main authors of a MiSTer core and the original authors of all preceeding work that culminated in the MiSTer core.
-
Also make sure you continue to credit all the authors that are already in the template version of the
AUTHORS
file particularly everybody listed under the headlineOther than that and my own work, REPO SHORT NAME uses:
. -
Replace all placeholders such as
REPO SHORT NAME
,YOUR PROJECT NAME
, etc. by meaningful content. -
Remove all editing instructions such as
LIST SOME MORE SIGNIFICANT...
andDO NOT FORGET TO...
and other instructions written in BOLD from the AUTHORS file.
The VERSIONS.md
delivered by the M2M framework in the repo's root folder is the M2M's own version history.
Delete it and replace it by your own versions file. In early stages of the development of your core
(for example first release), it is highly recommended to use the VERSIONS.md as a place where you tell your
users what the core already does well and also have a section where you are adding constraints. For example
missing features compared to the MiSTer core or other things that you plan to add in future. When interacting
with your users (e.g. on Discord) then you can share a link to this very VERSIONS.md file to answer frequently
asked questions.
Have a look how the VERSIONS.md
of the
first release of the C64 core
looked like or have a look how the VERSIONS.md
of
V0.8 of the GameBoy core
looked like. As you can see, these VERSIONS.md
files incorporate the principles mentioned above.
In later stages, as your core matures, you can then evolve your VERSIONS.md
to become
much more sophisticated
and then it might be the right moment in time to move the constraints and other thoughts about the future of your core to a
dedicated ROADMAP.md file.
The official place for all alternate MEGA65 cores that are supposed to be shared the the MEGA65
community is the
MEGA65 Filehost
(see below to learn how to release to the MEGA65 Filehost).
As an additional backup and also for having a nice release history on GitHub, too, it is a M2M best-practice
to add a bin
folder to your repository and store all the files that will become the release ZIP file for
the MEGA65 Filehost there. Name the subfolders of the bin
folders according to the naming
scheme that you decided for your versions. Examples include schemes like Version 1
, Version 2
, etc. as
well as V2.3
, V3.0
and others.
Here is an example
of one possible naming scheme and the corresponding folder structure.
Add sub-folders to the version folders that are named like the MEGA65 model that the binaries are built for.
M2M is only supporting the MEGA65 models R3
and R3A
and since these two models are binary compatible,
as of now the only sub-folder that you should have is a folder called R3
.
This sub-folder should contain at least these files:
-
.bit
generic FPGA bitstream -
.cor
MEGA65 core binary - If your core uses persistent settings, then you need a config file (see above)
- A brief
README.md
file. Remember that people who download the core from the MEGA65 Filehost are not necessarily aware that there is a user's manual type of a more comprehensiveREADME.md
available on GitHub or that they might need to copy the config file to a certain folder. So make sure that the minimum of information to run your core successfully is contained in theREADME.md
that you are placing into this binary release sub-folder.
Here is an example
of a binary release folder containing such a README.md
file. Have a look at the README.md
file and note that it contains links to the more comprehensive user's manual and other
sources of information. Also note the naming scheme for the bitstream and core binary that
contains the core's version as well as the MEGA65 model it runs on.
Releases should always happen in the master
branch of your repository. So make sure that
everything has been merged to this branch before you proceed.
As soon as you all the files in the Git and GitHub repository and your master
branch
are up-to-date and you are ready to release, you should
tag the last commit of this very
release using the release naming scheme you chose. Tag your local repository and then
push the tag to GitHub.
Here is an example how this looks in GitHub's tag browser when you successfully pushed your local tag(s) to GitHub:
Upload the binary release of your core to the MEGA65 community filehost at https://files.mega65.org. This provides a central location for the community to access all M2M based cores.
Add your core to the list of MEGA65 cores at https://sy2002.github.io/m65cores/. This ensures that community members can easily find your project.
Spread the word about your release within the community. This can be done through:
- Announcements on relevant forums or discussion boards.
- Posts on social media platforms.
- Word-of-mouth among community members.
Remember, communication is key to the success of your release.
By following these steps, you can ensure a successful and high-quality release of your core to the MEGA65 community. Happy coding!