Issue

The project doesn't have a document outlining the differences between SNES address mode and PC address mode

Features

While SNES headerless LoROM to PC address conversion are quite simple, it would be beneficial to attach a document outline how to go from one to the other. Additionally, covering the other address modes wouldn't be a bad idea.

Task List

• - How the address mode is decided in a ROM
• - LoROM
• - HiROM
• - ExLoROM
• - ExHiROM

Issue

The project does not have a commit message guideline.

Features

Like Issue and Pull Request Templates, a guide for writing commit messages will keep us organized and increase the amount of information we can put in commits.

Resolution

This document seems to cover everything we want to add just fine. Our proposed resolution is therefore to add this to the CONTRIBUTING file.

Task List

• - Research a resolution

My Running Environment

• OS: Windows 10 Home x64
• CPU: Intel i7 960 3.20GHz
• RAM: DDR3 12.0GB
• GPU: NVIDIA GeForce GTX 970 1.2GHz 6GB VRAM

Issue

Let's start with a good one! We need to document the SMB1 level format (objects, sprites, etc.)

Features

Proper documentation of the level format is more useful than writing the code to parse it and trying to study that.

Resolution

I'm proposing a markdown file that comprehensively outlines the SMB1 level format.

Task List

• - Object Pointers
• - Sprite Pointers
• - Object Data
• - Sprite Data

Things to do before diving into the project

We need a good guideline for building this project. Too many times have I let myself focus so much on writing code and never maintaining it that it always ends up an unmanageable beast. Below is a short list of things to do before submitting contributions.

Task List

• - Build a README file (#3)
• - Code of Conduct (#2)
• - Issue Template
• - Pull Request Template
• - Contributing
• - Set up Visual Studio
• - Establish code formatting rules
• - Outline project goals

Community

Build a README file

The README is the front page of project and therefore the first impression of what it can do for them. Ideally, I'd like the format of our README to follow GitHub's suggested guidelines. Note this is a documentation for the source code of the project itself, not the deployed product. More information provided in #3.

Code of conduct

Establishing a good code of conduct is a big deal to me and I want it to be to all contributors too. GitHub offers a few ready-made CoCs to use and one of these might work fine.

Contributing

I want a separate document that covers what would be most helpful for people who want to add to the project. I have a working outline of this right now but it's fairly extensive and could take some time to complete. This one ultimately needs to be done before any code can be added since in it I plan to define code formatting rules to maintain readability for everyone and minimize confusing changes in styles between contributors.

Development

Set up Visual Studio

I want this to be a cross-platform product, but I only have the resources to work on Windows 10 Desktop right now. My IDE of choice will be Visual Studio 2017 (or latest). Setting up new IDEs should be their own Issues when a contributor wants to add one.

Establish code formatting rules

This is mentioned in the Contributing section already, but it deserves more emphasis. Everyone likes to write code differently and, if the projects grows, it can get out of hand. So well-defined styles are essential as early as possible. This mostly emphasizes whitespace rules, bracket placement, class design, and test development. Maybe other things too that I can't think of right now.

Outline project goals

I want to open up issues that state the features that need to be added to our project. When an issue is opened, we should try to best defined what the features does, doesn't do, how to best separate components, and what tests can guide us in designing this feature. I'm aiming for test-driven-development, so the last requirement will be the most essential. I already have a lot of ideas about the project, so I'd like to create one task list Issue that addresses what I currently have in mind, and then make individual issues from that list.

Issue

We need a file that states what our project does/what we want it to do.

Feature

Having this file will help new contributors know exactly what we expect out of contributions and to not lose time trying to implement something we do not need.

Task List

• - Philosophy
• - Open source
• - Cross platform
• - Fully documented
• - Community driven
• - Accessible

Issue

A lot of the files from the archival Helper project are complete and usable in their current stage. It would be helpful to add them since they will get a lot of use.

Resolution

Some of the files are already fully documented and include unit tests. These can be added right away. Others are useful but lack documentation or unit tests. Those should be updated then added.

Task List

• - PixelFormats
  • - Readme file
  • - BitArray.cs
  • - Color15BppBgr.cs
  • - Color24BppBgr.cs
  • - Color32BppBgr.cs
• - Properties
  • - Resources
  • - Strong name key
• - AssertDictionary.cs
• - BlendMode.cs
• - ColorF.cs
• - ExtensionComparer.cs
• - ExtensionDictionary.cs
• - PathComparer.cs
• - PathDictionary.cs
• - SR.cs
• - SubstringPointer.cs
• - SuffixTree.cs

Problem

Our project needs a comprehensive and useful readme file for new contributors.

Resolution

I'd like to loosely follow the guide given under "Formatting your README".

Sections

• Project Name: MushROMs.
• Description: A library/app suite written primarily in C# that aids in editing Super NES games. Primarily Super Mario All-Stars
• Table of Contents: Add this if the README gets large enough.
• Installation: Provide instructions for building and possible dependencies for various environments, IDEs, and operating systems as their time comes. This feature cannot be added until we have one or more coding environments set up first.
• Contribution: Add a brief reference to the future contributing file.
• Milestones: Talk about what current milestones the project is looking at. This would be a good reference point for new users to see how they would want to contribute.
• Credits: Credit major contributors to the project
• License: Add a mention to the license used for our project.

These sections are likely to have subsections. Be sure to add them to the bullets and task list as they come to mind.

Sections remaining

• - Project Name
• - Description
• - Table of contents
• - Installation
• - Contribution
• - Milestones
• - Credits
• - License

Issue

The primary purpose of the last rewrite was that a lot of code was becoming tangled in an unsavory way. Code for windows controls would have editor and tilemap logic in them. And GUI-agnostic code would try to accommodate too much for GUI features. The source code upload is now at a stage where there is danger of this happening again. Therefore, it would be helpful to discuss what exactly these controls should do, and with that, where the logic for each feature belongs.

Features

Tilemaps

My personal definition of a "tilemap" has changed a lot since developing MushROMs. At its most basic, I should define it simply as a map of tiles. Some examples are given below:

Figure 1: A Palette TileMap

Figure 2: A GFX TileMap

Figure 3: A Map16 TileMap

These are all One-Dimensional tilemaps. Their data is stored in a single array. This may seem confusing since we've all been familiar with all of the above mentioned being 16x16 or 16x8 in almost any experience. However, a single Palette row defined in a rom could be 2 colors, 4, 8, 16, or 256. And legend of zelda, link to the past loads its palettes every 15 colors, ignoring the transparent first color. So there are several exceptions that merit these being 1D tilemaps.

For a 1D tilemap, the main parameter we have is its length, how many tiles it has. In each case, it's 256. Every 16 tiles, the image wraps to the next row. The utility of a 1D tilemap is that if we change the width of the view area, the data will wrap accordingly, as shown in the following examples:

Figure 4: A Palette tilemap with width reduced to 15 tiles

Figure 5: A GFX tilemap with width reduced to 9 tiles

Figure 6: A Map16 TileMap with width increased to 18 tiles

In each case, the data wraps according to the size of the view area. A good example of a 1D tilemap would be a line of text in a text editor that has word wrap turned on.

2D TileMaps

A 2D tilemap is one that has a defined height and width. In this case, change the view area doesn't change the layout. A good example would be a picture in an image editing program, or several lines of text in a text editor with no word wrapping.

In our case, a 2D tilemap would be a level editor (Lunar Magic has an obviously good example of this).

Properties of TileMaps

Properties that 1D and 2D tilemaps share are:

• View area
• Selected tile relative to view area

Properties that 1D tilemaps have are

• The length of tiles
• The index of the first viewable tile
• The number of tiles viewable in the region (If our view area exceeds the tiles length, or if the first index is high enough, this number can be different from the length of tiles or view area).
• Index of the selected relative to the tile array

The 2D tilemap properties are analagous

• Height and width of the tilemap
• Position of the first tile
• The number of tiles viewable by width and heigth
• Position of selected tile relative to origin

Resolution

It forms a .dll file, but what do you do with that? doesn't it need an executable file?

Issue

As the number of issues and branches starts growing, it's becoming apparent that the current organization could use some work. There are hints of improper organization and it would be beneficial to fix them now when it's easy.

Steps to Reproduce

A lot of branches are tackling multiple issues at once because they start to become quickly integrated. This is okay, but if they're going to be integrated and large, they should outlined and documented in an issue, so other users can track the progress.

Resolution

Currently, there are seven branches including master. Each branch should have an accompanying issue where progress discussion can be had.

Issue

The property is not virtual, so changing it can cause issues when user cast a DesignControl class to a UserControl. Also, when BorderStyle is set, OnStyleChanged is invoked. This may be sufficient and we probably don't need OnBorderStyleChanged at all. We just need to test first before pressing forward.

Issue

SnesXM needs an APU (audio processing unit) emulator.

Features

I don't know a lot about sound emulation, but obviously it's an essential component of SNES emulation.

Resolution

Port APU code from snes9x. Note that the Blargg files are just for environment configuration. They aren't needed in the C# environment.

Task List

• - Dsp
• - SpcDsp
• - Smp
• - SmpState
• - ApuEmulator
• - HermiteResampler
• - Msu1
• - Resampler
• - RingBuffer

Issue

I don't know what the Hermite Resampler is supposed to do, so I can't really write unit tests for it.

Resolution

Figure out what it does.

Issue

The config file class uses hard-coded strings.

Resolution

Replace all strings with culture-sensitive strings.

Issue

Put the subject of the issue here. This can be a sentence, a paragraph, or a whole page. Whatever best describes the problem.

Example:
The project currently does not have an ISSUE_TEMPLATE.md file

Features

List the benefits of resolving your issue here. This section is optional and likely not needed for bug reports.

Example:
An ISSUE_TEMPLATE.md file guides new contributors to discuss their problems and ideas in a format existing contributors are already familiar with.

Additionally, such a file helps improve our organizational quality by keeping a consistent standard for every issue. We spend more time thinking about the content provided and less time trying to make sense of how a contributor formatted their issue.

Resolution

If you have a proposed resolution ready, discuss it here. try to organize it in separate labels if there is a lot of content. This format is also helpful if you want to use the Task List section also.

Example:

Create an example template

Draft an ISSUE_TEMPLATE file and outline the use of each section with an example.

Have fun!

Now that this file exists, use it and have fun in the experience of open source contribution!

Task List

If your issue has multiple steps, create a task list so we can mark off each achievement. The text for each task is recommend to be one of your headers under Resolution

Example:

• - Create an example template
• - Have fun!

Issue

The project doesn't have a set of guidelines for formatting code.

Features

Coding conventions serve the following purposes:

• They create a consistent look to the code, so that readers can focus on content, not layout.
• They enable readers to understand the code more quickly by making assumptions based on previous experience.
• They facilitate copying, changing, and maintaining the code.
• They demonstrate C# best practices.

-Microsoft C# Coding Conventions

Resolution/Bug tracking progress

We will follow the guidelines provided in the Microsoft C# Coding Conventions. We may have to make minor changes. The task list outlines which sections are under review before submitting code format guidelines.

Task List

Sections for review:

• - Naming Conventions
• - Layout Conventions
• - Commenting Conventions
• - Language Guidelines
  • - String Data Type
  • - Implicitly Typed Local Variables
  • - Unsigned Data Type
  • - Arrays
  • - Delegates
  • - try-catch and using Statements in Exception Handling
  • - && and || Operators
  • - New Operator
  • - Event Handling
  • - Static Members
  • - LINQ Queries

Code style:

• - General
• - Formatting
  • - General
  • - Indentation
  • - New Lines
  • - Spacing
  • - Wrapping
• - Naming

Issue

There are several compression formats used by Lunar Compress.dll that would be handy if ported to MushROMs and made open source. However, a lot of these formats are still undocumented (even by the author). So it would be helpful to create documentation on their formats.

Features

Since I've wanted this code ported for a long time, having them documented is an essential first step. Further, it would be helpful to document all formats before writing the code for it, so we can see what properties all of the formats share.

Resolution

Create a "LZx Compression Format.md" doc for each format in the doc folder.

Task List

• - LZ1
• - LZ2
• - LZ3
• - LZ4
• - LZ5
• - LZ6
• - LZ7
• - LZ8
• - LZ9
• - LZ10
• - LZ11
• - LZ12
• - LZ13
• - LZ14
• - LZ15
• - LZ16
• - LZ17
• - LZ18
• - LZ19
• - RLE1
• - RLE2
• - RLE3
• - RLE4

Issue

The project currently does not have a PULL_REQUEST_TEMPLATE.md file

Features

A PULL_REQUEST_TEMPLATE.md allows our contributors to describe the features of their pull request in a standardized way. Refer to GitHub's mention on the subject for more information on why this is helpful.

Resolution

This repo seems to have a good list of templates to select from. It may be a good idea to just take one of theirs if any seem fitting.

Possible things to mention/check off:

• Does the pull request pass all unit tests?
• Are the commit messages formatted according to the CONTRIBUTING file?
• Is a test/benchmark included for the new feature/bug fix?
• Does the documentation reflect this change (if necessary)?
• Is there a duplicate/close duplicate pull request already present?
• Does this request close any open issues? (If not, create an issue first)
• Make sure your pull request does not target the master branch
• Does your description fully describe the pull request's changes?
• Are there any screenshots you could provide that better illustrate your change?
• Is this a breaking change? (Does it cause existing features to not work the same?)
• Does your code follow the code styles enforced by the project?

Issue

The ColorF class does not have unit tests for every method. There are a lot of blending options and therefore a lot of tests that need to be written.

Features

Given how sizeable the code is (and that I've made mistakes in it before), having an appropriate set of unit tests for all of it will ensure it's all running properly.

Resolution

First thing that needs to be done is create a task list for which methods still need to be unit tested. Then we need to actually write tests for them.

Task List

• - Create list of which methods need to be tested.

Issue

Our project needs a thorough outline that details how contributions can best be submitted.

Features

A CONTRIBUTING file tells your audience how to participate in your project.
-Open Source Guides

Resolution

I'm using the following resources to guide in designing a CONTRIBUTING file

• Writing your contributing guidelines
• Contributing Template
• Mozilla Contributing Guidelines

Our CONTRIBUTING file should have the following sections

Warm Welcome

Thank the user for wanting to contribute to the project, and state the importance of getting to know the contributing guidelines

Technical

How to file bug reports

We should probably make a template for this. Important things to add would be

• How to reproduce the bug
• A stack trace if available
• Screenshots if applicable

How to suggest a new feature

I'm not too sure where to take this one immediately. An issue template could help. One of the biggest problems is like "You should add support for X" where is very large and no extra information is given. So I guess a suggestion should be as detailed as the feature is large.

How to set up your environment and run tests

Provide a thorough guide on how to get started, successfully build the code, and run all tests to make sure they have a properly configured environment.

Code styles

I would like to have a set of enforceable code styles to avoid conflicting formatting styles from separate contributors.

Expectations

The types of contributions we're looking for.

Basically. We want to keep it within the scope of what our project actually does. The ambition is to have it do a lot, but we need to define set goals for it. Adding a VISION file (#5) could be a good idea.

Our vision for the project

Give a brief description of what it is we're doing. Link to possible VISION file (#5).

How to get in contact

Provide an escalation tree for users to get in contact with me over any questions
1 Read the FAQ (when we make one)
2 Read full documentation referenced in FAQ (if applicable)
3 Submit an Issue (if applicable)
4 Contact via email (include in email why 1-3 did not help).
Mention median response time.

Task List

• - Warm Welcome
• - How to file bug reports
• - How to suggest a new feature
• - How to set up your environment and run tests
• - Code styles
• - The types of contributions we're looking for
• - Our vision for the project
• - How to get in contact

Issue

MushROMs needs to improve the way it saves file data. Currently, it chooses a save format based on the editor type (Palette, GFX, Tilemap, etc.). However, this ignores the nuances of multiple formats between the same editor type. For example, Palette Editors can be saved in RPF, TPL, PAL, or MW3 format.

Resolution

I was looking at how Visual Studio handles file saving. There are several different document types (text, image, 3D mesh, etc.). It appears that VS handles them by first splitting by core document type, and then selecting by type format.

For example, all code files are text files, so VS will treat them universally as such and even ignore their basic extension types to show only .txt specifically.

You can further specify the encoding you want to save the text file with:

However, for image types, it will show only the specified image formats:

I suggest we follow this pattern for MushROMs. When the user prompts to save an editor, MushROMs will first look at the editor type. Once it gets the editor type, it will look at the file extension of the editor.Path field. It will use this extension to determine the file format to save the editor as. For example if the user saves a Palette file whose name is "Palette1.tpl", then it will default to the palette TPL encoding, with an option to save as any of the other Palette formats as well (RPF, PAL, MW3).

Issue

This just outlines a list of issues I still need to create. I'll add things as they come, to help me not forget.

Task List

• - Document SMB2 (J) level format
• - Document SMB2 (U) level format
• - Document SMB3 level format
• - Separate some unit tests that test multiple methods/constructors/paths
• - Create Palette stuff
• - Create GFX stuff
• - Create Map8 and Map16 stuff
• - Create common controls

Issue

The SPC-700 DSP code is up, but it was basically a direct port from snes9x and could stand to be refactored (especially changing member access, naming, and adding appropriate interfaces).

This is just a personal reminder to refactor the code eventually.

Issue

Preprend Memory to each enum.

Issue

The current icons used in MushROMs use many colors and can sometime be the same image with different colors. This can be frustrating for users with vision problems.

Resolution

If anyone wants to create icons that are solid colors, or rely on very few colors, that would be a huge help.

Issue

These two structs have empty messages for their overflow exceptions.

Resolution

Add culture-sensitive message strings similar to what Int.Parse would say.