You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
CHIP-8 is an open source community project, and everyone is welcome to contribute. This short guide will assist you with the workflow required in successfully having your features and bug fixes merged into the project.
4
+
5
+
# Table of Contents
6
+
7
+
-[How to Contribute Code](#how-to-contribute-code)
8
+
-[Creating a Fork](#creating-a-fork)
9
+
-[Keeping Your Fork Up to Date](#keeping-your-fork-up-to-date)
10
+
-[Creating a Development Branch](#creating-a-development-branch)
11
+
-[Submitting a Pull Request](#submitting-a-pull-request)
12
+
-[How to Submit a Bug Report](#how-to-submit-a-bug-report)
13
+
14
+
## How to Contribute Code
15
+
16
+
### Creating a Fork
17
+
18
+
The best approach to contribute code to CHIP-8 is to fork the [main repository](https://github.com/salindersidhu/CHIP8) on GitHub, then submit a pull request.
19
+
20
+
1.[Create an account](https://github.com/join) on GitHub if you do not have one.
21
+
22
+
2. Fork the repository by clicking on the 'Fork' button near the top-right section of the page. This creates a copy of the code under your account on GitHub.
23
+
24
+
3. Clone your fork to your local machine:
25
+
26
+
```bash
27
+
git clone https://github.com/USERNAME/CHIP8.git
28
+
29
+
# If you have an SSH key setup with GitHub
30
+
git clone git@github.com:USERNAME/CHIP8.git
31
+
32
+
# Navigate to your cloned fork
33
+
cd CHIP8
34
+
```
35
+
36
+
### Keeping Your Fork Up to Date
37
+
38
+
You will want to make sure you keep your fork synced with the original repository by tracking the original "upstream" repository that you forked.
2. Fetch the upstream repository's latest commits and branches:
48
+
49
+
```bash
50
+
git fetch upstream
51
+
```
52
+
53
+
3. Checkout the master branch and merge in the changes from the upstream repository's master branch:
54
+
55
+
```bash
56
+
git checkout master
57
+
git merge upstream/master
58
+
```
59
+
60
+
### Creating a Development Branch
61
+
62
+
A new branch is required when working on a new feature or bug fix. This ensures that your changes are kept seperate from the master branch making it easier to manage multiple pull requests for every task you complete.
63
+
64
+
1. Checkout the master branch as the starting point for the development branch:
65
+
66
+
```bash
67
+
git checkout master
68
+
```
69
+
70
+
2. Create a new development branch on your local machine and switch to it:
_Prefix is either `hotfix`, `feature` or `experiment` depending on the type of development work._
77
+
78
+
### Submitting a Pull Request
79
+
80
+
Prior to submitting a pull request, you must ensure that you have rebased your
81
+
development branch so that merging it into the original repository is a simple
82
+
fast-forward free of merge conflicts.
83
+
84
+
1.[Ensure that your fork is up to date.](#keeping-your-fork-up-to-date)
85
+
86
+
2. Rebase your development branch:
87
+
88
+
```bash
89
+
git checkout {prefix}/branch-name
90
+
git rebase master
91
+
```
92
+
93
+
Once you have committed and pushed all of your changes on your development branch to GitHub, go to the page for your fork on GitHub, select your development branch and click the pull request button. Once a pull request has been made, you can continue to make changes to the development branch and your pull request will automatically track the changes and update.
94
+
95
+
## How to Submit a Bug Report
96
+
97
+
If you find a bug in the code, please submit a ticket to the [Bug Tracker](https://github.com/salindersidhu/CHIP8/issues).
98
+
99
+
Before submitting your bug report, please ensure that your ticket contains the following:
100
+
101
+
- A short summary of the bug, typically a couple of sentences.
A Python based GUI implementation of the CHIP-8 system. A project I developed with the intention of gaining knowledge about emulators and cross platform GUI libraries.
5
23
For more specific information about the CHIP-8 system, please refer to the following technical reference article on [CHIP-8](http://devernay.free.fr/hacks/chip8/C8TECH10.HTM) and the [WIKI](https://en.wikipedia.org/wiki/CHIP-8).
- Windows 10, Mac OS X and Linux based distributions
26
35
27
36
## ROMs:
28
-
ROMs for the CHIP-8 system can be downloaded for free at [Chip8.com](http://www.chip8.com/?page=84) and [Zophar's Domain](http://www.zophar.net/pdroms/chip8.html). In order to load these ROMs with the interpreter, the files must be renamed to have a `.c8` extension.
ROMs for the CHIP-8 system can be obtained online for free at [Internet Archive](https://archive.org/details/Chip-8RomsThatAreInThePublicDomain). In order to load these ROMs with the interpreter, the files must be renamed to have a `.c8` extension.
39
+
40
+
# Development
41
+
42
+
> Information describing how to install and configure all the required tools to begin development.
43
+
44
+
## Prerequisites:
45
+
46
+
Ensure that you have the following installed and configured any environment variables.
47
+
48
+
-**Python**
49
+
- Version 3.7.5+
50
+
51
+
## Setup:
52
+
53
+
You will need to setup a python virtual environment and install the project's dependencies.
54
+
55
+
1. Skip this step if you're using Windows. If you're using Mac or Linux, you may need to install `pip` and `virtualenv` first:
33
56
34
-
## Running the Interpreter:
35
-
1. Download and install Python 3
36
-
+ Download and install PyQt 4
37
-
+ To launch the interpreter, open a terminal or command prompt and type `python3 interpreterapp.py`
38
-
+ To load a ROM, ensure that the ROM file has a `.c8` extension
57
+
```bash
58
+
sudo apt-get install python3-pip
59
+
sudo pip3 install virtualenv
60
+
```
61
+
62
+
2. Navigate to your CHIP-8 repo and create a new virtual environment with the following command:
63
+
64
+
```bash
65
+
# Windows
66
+
python -m venv venv
67
+
68
+
# Mac or Linux
69
+
virtualenv venv
70
+
```
71
+
72
+
3. Enable your virtual environment with the following command:
73
+
74
+
```bash
75
+
# Windows
76
+
source venv/Scripts/activate
77
+
78
+
# Mac or Linux
79
+
source venv/bin/activate
80
+
```
81
+
82
+
Your command line will be prefixed with `(venv)` which indicates that the virtual environment is enabled.
83
+
84
+
4. Install the project's dependencies with the following command:
85
+
86
+
```bash
87
+
pip install -r requirements.txt
88
+
```
89
+
90
+
## Running:
91
+
92
+
1. Enable your virtual environment with the following command:
93
+
94
+
```bash
95
+
# Windows
96
+
source venv/Scripts/activate
97
+
98
+
# Mac or Linux
99
+
source venv/bin/activate
100
+
```
101
+
102
+
2. Launch the CHIP-8 interpreter app with the following command:
103
+
104
+
```bash
105
+
python interpreterapp.py
106
+
```
39
107
40
108
## Controls:
109
+
41
110
The CHIP-8 system uses a `hexadecimal keyboard` that has 16 keys from 0 to 9 and A to F. Keys `2`, `4`, `6` and `8` are typically used for directional input.
42
111
43
112
The following keyboard layouts specify the `CHIP-8 Keyboard` and the `Interpreter KeyBoard` used in the application.
@@ -46,5 +115,24 @@ The following keyboard layouts specify the `CHIP-8 Keyboard` and the `Interprete
0 commit comments