-
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:
![](https://raw.githubusercontent.com/wiki/sy2002/MiSTer2MEGA65/assets/tags.jpg)
-
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.
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:
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.
Remember, communication is key to the success of your release.
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:
-
MEGA65 Forum as part of Forum64.de
-
r/mega65 on reddit