Skip to content

XYZ. How to release your core to the MEGA65 community

Jump to bottom
sy2002 edited this page Jul 26, 2023 · 12 revisions

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.

1. Source Code

  • Change the header of the file CORE/m2m-rom/m2mrom.asm to fit your project: Replace YOUR-PROJECT-NAME by your project's name (e.g. C64 for MEGA65) and replace GITHUB-REPO-SHORTNAME by the GitHub repositories' name (e.g. C64MEGA65). Delete the line "This ROM is loaded by" and replace YOURNAME and YEAR.

  • 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 like grep -irn @todo . (or search manually) to find all occurances of @TODO in all files located in CORE/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).

2. Binaries

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.

3. GitHub Repository

README.md as user's manual

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.

AUTHORS

  • 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 headline Other 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... and DO NOT FORGET TO... and other instructions written in BOLD from the AUTHORS file.

VERSIONS.md

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.

Upload binaries to GitHub

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

Tagging the Git repository

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.

3. MEGA65 Community Filehost

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.

4. List of MEGA65 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.

5. Advertising / Communicating the Release to the Community

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!

Clone this wiki locally