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

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

FPGA 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 here. Create .cor files using the bit2core tool:

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.

M2M Config File

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.

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 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 comprehensive README.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 the README.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.

Tag the Git repository

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:

Release on GitHub

  • Read GitHub's documentation on how to create a release.

  • It is a best practice to use the same content that you used in VERSIONS.md for the current release also for GitHub's release description fields

  • Important: Since M2M comes with its own tags (such as V1.0.0), ensure that you are not mixing up your own release tags with M2M's release tags. Always choose your own tags in GitHubs "Draft a new release" dialog.

Here is an example of how an M2M based core release should look on GitHub.

3. MEGA65 Community Filehost

Upload the binary release of your core to the MEGA65 Filehost at https://files.mega65.org. This provides a central location for the community to access all M2M based cores.

  • You need to have an account on the Filehost.

  • ZIP the contents of the above-mentioned binary release folder. This very ZIP will be the actual release that you share with the MEGA65 community via the Filehost.

  • On the Filehost: Choose "My File Uploads" in the account menu.

  • If this is your first release then choose "Upload new file", otherwise choose the name of your old release as the Filehost supports versioning.

  • Fill the form. It is advisable to market the core on the file host. After all, you have invested a lot of time and energy in creating it. So at a minimum: Upload a few screenshots/pictures and maybe even a short video. Add an engaging Description that contains a link to the user's manual on GitHub.

  • Important: Choose "Alternate Core" as "Type" and since the Filehost versions all files you must select a version after you uploaded your ZIP.

Here is an example of how a release of your core could look like on the MEGA65 Filehost:

4. List of MEGA65 Cores

The official list of MEGA65 cores is at https://sy2002.github.io/m65cores/. This list is also normally the first search result that Google provides if one googles something like "mega65 cores" or "alternate mega65 cores". Contact the maintainer of the list as described under "Can I add a core to this list?". This ensures that community members can easily find your project.

5. Advertising / Communicating the Release to the Community

Remember, communication is key to the success of your release.

MEGA65 Discord Server

If you are not yet a member of the MEGA65 Discord Server then become a member now. The friendly MEGA65 community awaits you there. Go to the channel announcements-only and post an engaging description of your release including an image and a link to the MEGA65 Filehost in the channel.

Here is an example how this can look like:

Other places to advertise your core

Clone this wiki locally