UNPKG

7.65 kBMarkdownView Raw
1[![Build Status](https://travis-ci.org/FirstLegoLeague/fllscoring.png?branch=master)](https://travis-ci.org/FirstLegoLeague/fllscoring)
2[![Coverage Status](https://coveralls.io/repos/FirstLegoLeague/fllscoring/badge.png?branch=master)](https://coveralls.io/r/FirstLegoLeague/fllscoring?branch=master)
3[![Dependency Status](https://david-dm.org/FirstLegoLeague/fllscoring.png)](https://david-dm.org/FirstLegoLeague/fllscoring)
4[![devDependency Status](https://david-dm.org/FirstLegoLeague/fllscoring/dev-status.png)](https://david-dm.org/FirstLegoLeague/fllscoring#info=devDependencies)
5
6![en_US challenge screenshot](docs/user_interface/screenshots/26-8-2015_75711.png)
7
8FLL Scoring
9=============
10
11To have a look at what we are at:
12- see [Testing](https://github.com/FirstLegoLeague/fllscoring/wiki/Testing). No guarantees.
13- or check out our live [Live demo](http://firstlegoleague.github.io/fllscoring/). Even less guarantees.
14
15Using
16---------------
17
18Currently the scoring application can only be reliably used as a hosted service. To use:
19
20- set up a server running nodejs [nodejs.org](http://nodejs.org)
21- [download the source](https://github.com/FirstLegoLeague/fllscoring/archive/master.zip) or clone the repository using git.
22- Open a command prompt and navigate to the directory where you cloned the repository or extracted the downloaded zip-file.
23- Execute the following command: `npm install`
24(this installs all dependencies. It's a neccesarry step for each install)
25- Run `node localserver.js` then open [localhost:1390](http://localhost:1390) in your browser
26 - to specify another port, use `node localserver.js -p 8000`
27 - to add basic authentication, use `node localserver.js -u username:password`
28
29In the near future, we plan to have "ready to go" software available as:
30
31- executable, for Windows, Mac OS and Linux
32- app, for iOS, Android and windows
33- a hosted service, as described above
34
35Contributing
36---------------
37
38To contribute to this repository, please make a fork, make your changes and submit a pull request.
39
40This way of work allows us to maintain proper code quality, which is important when working with a large amount of people on the same project. Feel free to join the discussion on the [issues page](https://github.com/FirstLegoLeague/fllscoring/issues)
41
42The best way to work on a feature or a bug is to follow these steps:
43
44- fork the repository to your own github account
45- if already forked, make sure your fork is up to date with the base repo
46- create a new branch for your feature or bugfix
47- work
48- test
49- create a pull request to merge your development branch into a branch in the base repo
50- we will review your pull request, when ok, we will merge it into master
51
52In your own fork, you can create any branch structure you like, however, some best practices / tips are:
53
54- use [git flow](https://jeffkreeftmeijer.com/2010/why-arent-you-using-git-flow/) to structure your branches
55- keep pull requests small and concise. Try to limit a pr to only one feature / bug fix. We'd rather have many small pull requests than one large one
56- keep your fork up to date with the base repo on a regular basis, by rebasing against it. This makes sure your pull requests will merge nicely
57
58Development
59---------------
60
61Prerequisites
62
63- nodejs [nodejs.org](http://nodejs.org). Make sure you have a recent version (>6) to get npm version >3.
64- grunt (`npm install -g grunt-cli`)
65
66Steps
67------
68
69- Clone the repository
70- `npm install`
71
72Run local
73--------
74
75This is mainly used for development.
76
77- `node localserver.js` then open [localhost:1390/nocache.html](http://localhost:1390/nocache.html)
78 - to specify another port, use `node localserver.js -p 8000`
79 - to add basic authentication, use `node localserver.js -u username:password`
80 - to specify a data dir use `node localserver -d datadir` Relative paths are relative to the localserver script. Absolute paths are, well, absolute. Defaults to `data`
81- note that we load `nocache.html` to circumvent the offline cache mechanism
82
83Testing
84-------
85
86- run `karma start`
87- or run `grunt karma`
88
89Building
90--------
91
92- for a desktop build: `grunt nwjs`
93- for a mobile build: `grunt phonegap`
94 - to build only one of iOS or Android, use `grunt phonegap:ios` or `grunt phonegap:android` respectively
95
96For the phonegap build, copy `pgbuildconfig.example.json` to `pgbuildconfig.json` and adjust your phonegap build credentials. You can create an account on [phonegap build](http://build.phonegap.com/). Also, make sure you you copy .cordova/config.example.json to .cordova/config.json and insert your application ID from phonegap build into it. The first time you build the app you must comment the app ID line out, it will generate one for you. Afterwards check the Phonegap build website for the generated app ID.
97
98NOTE: remove the comments in the copied file, as it is not valid JSON as it is.
99
100For iOS, see [Building for iOS](https://github.com/FirstLegoLeague/fllscoring/wiki/Building-for-iOS)
101
102(Only) when XML definition files have changed:
103-----------------------------
104
105- run `grunt challenge`
106
107This will rebuild html, pdf and js versions of the challenge. This can also be done individually if you'd wish:
108
109- run `grunt html`
110- run `grunt pdf`
111- run `grunt js`
112
113These files are also included in the repo: `challenges/html`, `challenges/pdf`, `challenges/js`
114
115Documentation
116-------------
117
118- [original proposal](docs/proposal/Scoring System project proposal-v2.pdf)
119- [architecture documents](docs/architecture/readme.md)
120- [templating](docs/templating/readme.md)
121- [interface](docs/user_interface/readme.md)
122- [internationalization](docs/i18n/readme.md)
123
124TODO's
125--------
126
127See [case issues](https://github.com/FirstLegoLeague/fllscoring/issues?direction=desc&labels=case&page=1&sort=updated&state=open)
128
129Help is welcome. Please comment on the case if you plan to start working on one.
130
131License
132--------
133This projected is licensed under the terms of the [GNU GPL v2.0 licenses](https://raw.githubusercontent.com/FirstLegoLeague/fllscoring/master/LICENSE.txt)
134
135Basically, it allows users to legally copy, distribute and modify software. This means you can:
136* Copy it onto your own servers, your client’s servers, your own computer, pretty much anywhere you want. There’s no limit to the number of copies you can make.
137* Provide a download link on your website. Put the software on a bunch of thumb drives and give them away. Print out the source code and throw it from the rooftops (please don’t, though, because that would waste a lot of paper and make a mess).
138Charge a fee to distribute the software.
139* If you want to charge someone to provide the software, set it up on their website or do anything else related to it, you can do so. But, you must give them a copy of the GNU GPL, which basically tells them that they could probably get the software elsewhere for free. Best to be up front about that, and about why you’re charging them.
140* If you want to add or remove functionality, go ahead. If you want to use a portion of the code in another project, you can. The only catch is that the other project must also be released under the GPL. Ideally we would want you to share your improvements back with us on this GitHub.
141* We welcome your feedback but please remember that this software comes with no guarantees. We are dedicated volunteer and experienced software developers and will do our best make sure we make a valuable and reliable contribution to the community. However the use of this software is at your own risk.
142
143Authors
144--------
145
146- [Rikkert Koppes](mailto:rikkert@rikkertkoppes.com)
147- [Kenny Meesters](mailto:k.meesters@gmail.com)