# Contributing to venus

I'm glad you are interested in contributing to venus!

__Table of Contents__

* How can I contribute?
    * Reporting a Bug
    * Requesting an Enhancement
    * Submitting a Pull Request
* Development
    * Getting Started
    * Documentation
    * Sourcemap
    * What should I work on?
    * Code Guidelines

## How can I contribute?

There are many ways to contribute to venus, not all of which require writing code!

### Reporting a Bug

Some things which would be helpful to include:

* What browser you were using
* A code sample, if applicable
* The expected result vs what actually happened

### Requesting an Enhancement

Enhancement requests are welcomed. Feel free to open a Github Issue with any suggestions.

### Submitting a Pull Request

Pull requests are welcome. Pull requests should include:

* A description of what your pull request does
* What existing issues (if any) it fixes

I will try to review all pull requests in a timely manner.

## Development

### Getting Started

Start by forking venus on Github. Then pull the repository and enter the directory:

    $ git pull <your fork>
    $ cd venus

Install node packages and `grunt`. You might need to install Node.js and npm.

    $ npm install
    $ npm install -g grunt

Build the backend:

    $ ./gradlew build

Build the frontend+backend bundle:

    $ grunt dist

Run the unit tests:

    $ grunt test

If everything works, you can start developing now! Start by creating a new git branch:
    
    $ git checkout -b <feature branch> develop

Note that feature branches should be based off the `develop` branch, according to [the Gitflow Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows#gitflow-workflow).

Make any changes you need.

To recompile:

    $ ./gradlew build && grunt dist

You can see your local version of venus by opening `out/index.html` in any browser.

### Documentation

Javadoc can be generated by running `./gradlew dokka`. The resulting documentation is in the `doc/` folder.

### Sourcemap

All source code is included in the `src` directory.

* `main` - the main application itself
    * `frontend` - the visual part of venus
        * `css` - all CSS files should be included here
        * `images` - all images should be included here
        * `js` - all Javascript files should be included here
        * `index.html` - the simulator frontend itself
    * `kotlin/venus` - the backend part of venus
        * `assembler` - the assembler backend
            * `pseudos` - all pseudoinstructions
        * `glue` - code which links the backend and frontend
        * `linker` - linker which resolves branches and jumps
        * `riscv` - includes things common to all parts of venus
            * `insts` - contains all instructions and DSL
                * `dsl` - a domain specific language for specifying instructions
                    * `disasms` - describe how to get from machine code to human readable code
                    * `formats` - describes the fields of an instruction which must be set
                    * `impls` - gives an implementation of an instruction
                    * `parsers` - describe how to get from an instruction to its machine code
                    * `relocators` - describe how to fill in fields to relocate an instruction
        * `simulator` - the instruction set simulator
            * `diff` - describe how to undo operations
* `test` - tests which are run with `grunt test`

### What should I work on?

Check out the Issues tab. Larger projects will be included in the Projects tab.

### Code Guidelines

I _highly_ recommend using IntelliJ IDEA. It has great built-in Kotlin support and will format your code appropriately. `ktlint` will run automatically and fail your build if it doesn't pass some basic lint tests, however it is not comprehensive.

* Indentation is four spaces for all files -- except HTML which is two spaces.
* Avoid semicolons.
* Braces should be on the same line.
* Use lowerCamelCase for everything, except classes which should use PascalCase.
