craigthomas / chip8java Goto Github PK

🎃 Welcome to Hacktoberfest 2022! 🎃

Thank you for checking out my Super Chip 8 Java project! This repository contains an emulator for a computer called the Chip 8. Technically the Chip 8 isn't actually a computer, but rather an interpreted computer language that was meant to run on different computers from the 1970's and 1980's. Most famously, it's been used to run games on HP graphing calculators.

The emulator in this project is complete and runs on Windows, Linux, Mac, and UNIX computers. However, I need help with testing! There are a number of Chip 8 and Super Chip 8 ROMs that exist in the public domain that anyone can freely download and use (just Google keywords chip8 public domain roms to find them). I need your help testing those ROMs on the emulator to see if there are any problems. I also need your help to document which keys on the emulator do what when you run the ROM.

Here's how you can help with testing, and contribute a pull request to the repository for Hacktoberfest 2022!

Prerequisites

In order to run the emulator, you will need a Java Runtime Environment (JRE) version 8 or higher. See the README.md file for more information on how to install Java and set up your environment to run the emulator.

Also, please check out the project's Code of Conduct to learn more about the standards and values we have for community members.

For Testing

Here are the steps you will need to test out the emulator.

1. Download the Emulator. You can do this by going to the Releases page for this project. Make sure you download the latest archive file for the project (currently v1.0.1). Optionally, you can clone the repository to get the source files. To do this, you will need git installed. Type git clone [email protected]:craigthomas/Chip8Java.git to clone the project (see the README.md file for more information).
2. Indicate what ROM you are going to test. On this issue, make a comment about what ROM file you are going to test. Make sure you aren't testing a ROM file that someone else is already testing by checking that nobody else has already claimed that ROM in the comments, and that the ROM isn't already listed in the ROM Compatibility section of the README.md file.
3. Try out a ROM. Run the emulator by using the command-line options (see the README.md file for more details on how to run a ROM). Test out the ROM and make sure it works. Make sure each key works, and make special notes if there appear to be problems with the emulator.

If the ROM works...

If your testing is successful, that's great! It's time to document the README.md file with your success. Here is where you can make a pull request to count towards your Hacktoberfest 2022 progress! Here are the steps you will need to do this:

1. Fork this project. You can do this by pressing the Fork button at the top right-hand side of the repository. This will create a copy of the project in your own Github account that you can use to make the change.

2. Update the README.md file in your repository. This can be done easily by clicking on the README.md file in your repository, and then clicking the Edit this file button along the top navigation bar (it looks like a pencil).

3. Update the section called ROM Compatibility. In the README.md file, there is a section called ROM Compatibility. Add a new line to that section with the ROM name, a green check-mark, and notes about what keys work and what the keypress does when the ROM is running:

   | (ROM name here) | :heavy_check_mark: | (notes about what keys work) |
   

4. Commit your changes to your forked repository. At the bottom of the editor, there will be a section called Commit changes. Add a title for the commit, and a description of what you did. To save time, you can commit directly to the main branch.

5. Create a Pull Request. From your repository, click on the button labeled New pull request from the Code tab. By default, this should initiate a pull request from your repository back to the Chip8Java codebase. Make sure you provide a good working title and a good description of what you tested.

That's it! I'll look at your pull request and let you know if there is anything missing. If everything looks good, your change will be merged. Thank you for helping out!

If the ROM doesn't work...

If the ROM file doesn't work, that's okay! Your testing work is very valuable, and you can still create a pull request to count towards Hacktoberfest 2022! Follow the same procedure as listed above in the If the ROM works... section, but for step 3, change the line that you add to the README.md file to describe what isn't working:

| (ROM name here) | :x: | (Describe what is wrong) |

Follow the rest of the procedure to create a pull request so that the README.md file is updated with the results of your testing. If everything looks good, your change will be merged. Thank you for helping out!

Optional - you can also submit a bug report to the project that describes what is wrong. This will help another contributor fix the problem. Go to the Issues section of the repository, and next to Bug report, click on the Get started button. Fill out the template provided with details on what is wrong and how you can reproduce the bug. Thank you for submitting a bug report!

If you think you know how to fix the bug...

If your testing revealed a bug, and you can fix the bug, then please feel free to do so! I welcome code contributions you feel are helpful and reflect the spirit of the project. To make a code change, simply fork the project, make the changes in your own repository, and then submit a pull request back to the main project repository. Make sure to include a descriptive title and well-documented pull request body that explains the changes that you made and why. Ensure that the automated tests complete successfully, and try to have a unit test or two that covers the bug condition. Please check out the Contributing documentation for more information on making code contributions. Thank you for helping out!

😄 Welcome to Hacktoberfest 2019!

Thank you for checking out my Super Chip 8 Java project! This repository contains an emulator for a computer called the Chip 8. Technically the Chip 8 isn't actually a computer, but rather a language specification that was meant to run on different computers from the '70s and '80s. Most famously, it's been used to run games on HP graphing calculators.

The emulator is complete and runs on Windows, Linux, Mac, and UNIX computers. However, I need help with testing. There are a number of Chip 8 and Super Chip 8 ROMs that exist in the public domain that anyone can freely download and use (just Google chip8 public domain roms). I need your help testing those ROMs on the emulator to see if there are any problems.

Here's how you can help with testing, and contribute a pull request to the repository for Hacktoberfest 2019!

Prerequisites

In order to run the emulator, you will need a copy of the Java Runtime Environment version 8 or better. For most systems, you can install Java 8 JRE by visiting http://java.com and installing the Oracle Java Runtime Environment for your platform. This version of the JRE is free for personal use but contains a custom binary license from Oracle. Alternatively, if you prefer to use a JRE with an open-source license (GPL v2 with Classpath Exception), you may visit https://adoptopenjdk.net and install the latest Java Development Kit (JDK) for your system, which will include an appropriate JRE.

For Testing

Here are the steps you will need to test out the emulator.

1. Download the Emulator. You can do this by going to the Releases page for this project. Make sure you download the latest JAR file for the project (currently v1.0.1). Optionally, you can clone the repository and build from source. To do this, you will need git installed. Type git clone [email protected]:craigthomas/Chip8Java.git to clone the project, and then gradlew build to build it from source (see the README.md file for more information).
2. Indicate what ROM you are going to test. On this issue, make a comment about what ROM file you are going to test. Make sure you aren't testing a ROM file that someone else is already testing by checking that nobody else has already claimed that ROM in the comments, and that the ROM isn't already listed in the ROM Compatibility section of the README.md file.
3. Try out a ROM. Run the emulator by double-clicking the JAR file, or by using the command-line options (see the README.md file for more details on how to run a ROM). Test out the ROM and make sure it works. Make sure each key works, and make special notes if there appear to be problems with the emulator.

If the ROM works...

If your testing is successful, that's great! It's time to document the README.md file with your success. Here is where you can make a pull request to count towards your Hacktoberfest 2019 progress! Here are the steps you will need to do this:

1. Fork this project. You can do this by pressing the Fork button at the top right-hand side of the repository. This will create a copy of the project in your own Github account that you can use to make the change.

2. Update the README.md file in your repository. This can be done easily by clicking on the README.md file in your repository, and then clicking the Edit this file button along the top navigation bar (it looks like a pencil).

3. Update the section called ROM Compatibility. In the README.md file, there is a section called ROM Compatibility. Add a new line to that section with the ROM name, and a green check-mark:

   | (ROM name here) | :heavy_check_mark: | |
   

4. Commit your changes to your forked repository. At the bottom of the editor, there will be a section called Commit changes. Add a title for the commit, and a description of what you did. To save time, you can commit directly to the master branch.

5. Create a Pull Request. From your repository, click on the button labeled New pull request from the Code tab. By default, this should initiate a pull request from your repository back to the Chip8Java codebase. Make sure you provide a good working title and a good description of what you tested.

That's it! I'll look at your pull request and let you know if there is anything missing. If everything looks good, your change will be merged into the master file. Thank you for helping out!

If the ROM doesn't work...

If the ROM file doesn't work, that's okay! Your testing work is still valuable, and you can still create a pull request to count towards Hacktoberfest 2019! Follow the same procedure as listed above in the If the ROM works... section, but for step 3, change the line that you add to the README.md file that describes what isn't working:

| (ROM name here) | :x: | (Describe what is wrong) |

Follow the rest of the procedure to create a pull request so that the README.md file is updated with the results of your testing. Thank you for helping out!

If you think you know how to fix the bug...

If your testing revealed a bug, and you can fix the bug, then please feel free to do so! I welcome any code contributions you feel are helpful and reflect the spirit of the project. To make a code change, simply fork the project, make the changes in your own repository, and then submit a pull request back to the main project repository. Make sure to include a descriptive title and well-documented pull request body that explains the changes that you made and why. Ensure that the automated tests complete successfully, and try to have a unit test or two that covers the bug condition. Thank you for helping out!