2020-05-24 20:49:41 +00:00
# Contributing Guide
Hi! I'm really excited that you are interested in contributing to this project.
Before submitting your contribution, please make sure to take a moment and read through the following guidelines:
- [Code of Conduct ](CODE_OF_CONDUCT.md )
- [Issue Reporting Guidelines ](#issue-reporting-guidelines )
- [Pull Request Guidelines ](#pull-request-guidelines )
- [Development Setup ](#development-setup )
- [Project Structure ](#project-structure )
## Issue Reporting Guidelines
- Report a new issue either through [GitHub ](https://github.com/bra1n/townsquare/issues/new/choose ) or [Email ](mailto:steffen@baumgart.biz )
- Please include with your issue the browser and operating system you're using as well as steps necessary to reproduce the bug, if any
- Be patient, I'm working on this project in my spare time :-)
## Pull Request Guidelines
2020-06-30 11:59:33 +00:00
- The `main` branch is what is currently deployed to the website. All development should be done in dedicated branches.
2020-05-24 20:49:41 +00:00
2021-05-09 19:43:51 +00:00
- The `develop` branch contains the changes that will be deployed to main next. In order to prepare a release, development
branches should have their Pull Request against `develop` and only releases should be merged from `develop` into `main` .
2020-05-24 20:49:41 +00:00
- Work in the `src` folder and **DO NOT** checkin `dist` in the commits.
- It's OK to have multiple small commits as you work on the PR - GitHub will automatically squash it before merging.
- If adding a new feature:
- Provide a convincing reason to add this feature. Ideally, you should open a suggestion issue first before working on it.
- Feel free to write a test for it, but so far I didn't have time for that.
- If fixing a bug:
- If you are resolving a special issue, add `(fix #xxxx[,#xxxx])` (#xxxx is the issue id) in your PR title for a better release log, e.g. `update entities encoding/decoding (fix #3899)` .
- Provide a detailed description of the bug in the PR. Live demo preferred.
2021-05-09 19:43:51 +00:00
- You'll need to update the `CHANGELOG.md` with a description of your changes before you open a pull request and your code
should pass the lint check.
2020-05-24 20:49:41 +00:00
## Development Setup
You will need [Node.js ](http://nodejs.org ) **version 8+** and a Chrome browser.
After cloning the repo, run:
``` bash
$ npm install
```
The development server can be started with `npm run serve` .
2021-01-09 20:33:09 +00:00
### Deploying to GitHub pages or with a non-root path
Deploying a forked version to GitHub Pages or running your local
development copy in a sub-path (instead of the web root) will require you to modify
2021-02-28 12:37:16 +00:00
the `vue.config.js` and configure the path at which the website will be served, as well
as removing the CNAME file and updating the GitHub pages configuration. Otherwise, your fork
2021-02-28 12:37:54 +00:00
will think it should be served at clocktower.online instead of \<user\>.github.io/townsquare/.
2021-01-09 20:33:09 +00:00
For example, deploying your forked `townsquare` project to GitHub pages would need the following
`vue.config.js` changes:
```js
module.exports = {
publicPath: process.env.NODE_ENV === "production" ? "/townsquare/" : "/"
};
```
2020-05-24 20:49:41 +00:00
### Committing Changes
Commit messages should be verbose enough to allow someone else to follow your changes and should include references to issues that are being worked on.
### Commonly used NPM scripts
``` bash
# watch and auto re-build dist/
$ npm run serve
# build all dist files, including npm packages
$ npm run build
# run linting scripts
2020-07-06 13:23:22 +00:00
$ npm run lint
2020-05-24 20:49:41 +00:00
```
## Project Structure
- **`dist`**: contains built files for distribution.
2021-01-09 20:33:09 +00:00
- **`public`**: static assets and templates that don't need to be built dynamically.
- **`server`**: NodeJS code for the live session backend server.
2020-05-24 20:49:41 +00:00
- **`src`**: contains the source code. The codebase is written in ES2015.
- **`assets`**: contains all graphical assets like images, fonts, icons, etc.
- **`editions`**: edition logos and icons
- **`fonts`**: webfonts used on the page
- **`icons`**: character token icons
2021-01-09 20:33:09 +00:00
- **`sounds`**: sound effects used on the page
2020-05-24 20:49:41 +00:00
- **`components`**: the internal components used in the project
- **`modals`**: the modals have a separate subfolder
- **`store`**: the VueX data store and modules
2021-01-09 20:33:09 +00:00
- **`modules`**: VueX modules that live in their own namespace