-
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 and how to create .cor
files
here.
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.
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).
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. 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
https://git-scm.com/book/en/v2/Git-Basics-Tagging As soon as you are done with your release when it comes to all the files that you made the last commit to Git and GitHub https://git-scm.com/book/en/v2/Git-Basics-Tagging
For the release:
- Create a binary release of your core.
- Use GitHub's release feature, which allows you to package your software, release it with a version number, and provide release notes.
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!