Skip to content

Latest commit

 

History

History
257 lines (209 loc) · 11.9 KB

README.adoc

File metadata and controls

257 lines (209 loc) · 11.9 KB
Raw

StudyGuide

build status Ohloh widget

Planning and verifying tool for all the requirements of your studies (for European-style university school systems).

Screenshot

StudyGuide screenshot

Getting help

For users looking for help: a manual describing all possible features of StudyGuide is available in the app itself: in the upper menu bar item Help → Help.

Post any development questions or comments you may have on Stack Overflow and/or don’t hesitate to open an issue.

Running StudyGuide releases

  • Download a release from https://github.com/oskopek/StudyGuide/releases

  • To directly run StudyGuide, download the executable JAR file: StudyGuide-VERSION-jar-with-dependencies.jar

  • If you want to run a release, just try: java -jar StudyGuide-VERSION-jar-with-dependencies.jar

Building & running StudyGuide

  • See the section (further down) on How-to setup your build environment first.

  • Recommended: mvn clean install -DskipTests

  • To run unit tests: mvn clean install

  • To run integration tests: mvn clean install -Pit

  • To clean, run: mvn clean

  • Run StudyGuide:

    • If you followed the build environment setup and want to run your version of StudyGuide, run mvn exec:java from the main project directory.

    • If you want to run a translated version of StudyGuide, set your system locale accordingly and restart StudyGuide. If you want to try out a translated version (on Linux), try: LC_ALL="LOCALE" java -jar StudyGuide.jar, where LOCALE is any locale available on your system (run locale -a to view all available).

StudyGuide uses semantic versioning.

Setup your build environment

Linux & Mac

  1. Install Git

    • Fedora: sudo dnf install git

    • Ubuntu: sudo apt-get install git

  2. Install Java8 JDK — Oracle JDK Downloads — Select: Java Platform (JDK)

    • NOTE: You need jdk-8u40 or newer (JavaFX 8 dependency).

  3. Install Maven — preferably the latest version you can. Usually, your distribution’s package management repository is enough:

    • Fedora: sudo dnf install mvn

    • Ubuntu: sudo apt-get install maven

  4. Fork the repository — Create a fork of the oskopek/StudyGuide repository (right upper corner) on GitHub, usually the fork will be called: yourusername/StudyGuide.

  5. Clone the your fork — run git clone https://github.com/yourusername/StudyGuide.git (or, preferably, use SSH: git clone git@github.com:yourusername/StudyGuide.git)

  6. Run the build (see the Building section)

Windows

  1. Install Java8 JDK — Oracle JDK Downloads — Select: Java Platform (JDK)

  2. Install Maven — (preferably the latest version you can). See: Maven on Windows and Maven Downloads.

  3. Download and install GitHub for Windows at http://windows.github.com/. If you encounter any problems, see the GitHub for Windows FAQ.

  4. Find the oskopek/StudyGuide repository on GitHub.

  5. Create a fork of the repository (right upper corner), usually the fork will be called yourusername/StudyGuide.

  6. Run the build (see the Building section)

  7. The following workflow may be useful for you, if you’re not familiar with Git/GitHub for Windows:

    1. In the upper left window, you can view all uncommitted changes. Write the name and description of your changes and click the check button.

    2. Once in a while, be sure to sync to send all commits to your GitHub fork.

    3. After testing your changes, submit a pull request to oskopek/StudyGuide through GitHub.

      1. Click on compare across forks.

      2. Set the following:

        • base fork: oskopek/StudyGuide

        • base: master

        • head fork: yourusername/StudyGuide

        • compare: branchname

    4. Click on Click to create a pull request for this comparison.

    5. Our Travis continuous integration server will test the merge of your pull request. You can view the results in the thread of the pull request.

    6. Congratulations! Your pull request will get reviewed and probably be merged in.

Submitting an Issue

We use the GitHub issue tracker to track bugs and features. Before submitting a bug report or feature request, check to make sure it hasn’t already been submitted. When submitting a bug report, please include a Gist that includes a stack trace and any details that may be necessary to reproduce the bug, including your Java version and operating system.

Contributing

Everyone is encouraged to help improve this project.

Here are some ways you can contribute:

  • by using alpha, beta, and pre-release versions

  • by reporting bugs

  • by suggesting new features

  • by implementing planned features

  • by translating to a new language

  • by writing or editing documentation

  • by writing specifications

  • by writing code (no patch is too small: fix typos, add comments, clean up inconsistent whitespace)

  • by refactoring code

  • by closing issues

  • by reviewing patches

Submitting a Pull Request

  1. Fork the repository

  2. Create a topic branch

  3. Optional: To ease the process of contributing code back into StudyGuide, please set-up IDE coding templates first

  4. Implement your feature or bug fix

  5. If applicable, add tests and documentation for your feature or bug fix (see How-to write documentation)

  6. Run mvn clean install -Pit

  7. If the tests fail, return to step 3 and 4

  8. Add, commit, and push your changes

  9. Submit a pull request

Data format

For all input and output format, we use JSON. Currently, the input/output format depends directly on the model, and may be subject to future changes.

Data format details

The following is a grammar of the input/output data format. Do note it may be outdated.

Conventions:

  • JSON uses the character pair { and } often, therefore we write zero-or-more repeated statements using ( and )*, which JSON doesn’t use (just like regexes).

  • Also, since JSON uses [ and ] for lists, they do not mean an optional statement - we use ( and ) (without the star) for that.

  • Under <character> we assume any valid UTF-8 character.

  • Under <string> we assume any valid, non-empty sequence of UTF-8 characters.

  • Under <integer> we assume any non-negative whole number smaller than or equal to 2^31 - 1.

<study_plan> ::= {
                   "courseRegistry" : <course_registry>,
                   "semesterPlan" : <semester_plan>,
                   "constraints" : <constraints>

                 }
<semester_plan> ::= {
                      "semesterList" : [ (<semester>}, )* ]
                    }
<constraints> ::= {
                    "courseGroupConstraintList": [ (<course_group_constraint>, )* ],
                    "globalConstraintList": [ (<global_constraint>, )* ],
                    "courseEnrollmentConstraintList": [ (<course_enrollment_constraint>, )* ]
                  }
<course_registry> ::= {
                        "courses" : {
                                      ("<string>" : <course>, )*
                                    }
                      }
<semester> ::= {
                 "name": "<string>",
                 "courseEnrollmentList": [ (<course_enrollment>, )* ]
               }
<course_group_constraint> ::= ((<course_group_credits_percentage_constraint>|<course_group_credits_sum_constraint>
                                |<course_group_fulfilled_all_constraint>), )*
<global_constraint> ::= ((<global_course_repeated_enrollment_constraint>|<global_credits_sum_constraint>), )*
<course_enrollment_constraint> ::= ((<course_enrollment_corequisite_constraint>
                                     |<course_enrollment_prerequisite_constraint>), )*
<course_group_credits_percentage_constraint> ::= {
                                                   "CourseGroupCreditsPercentageConstraint": {
                                                     "courseGroup": <course_group>,
                                                     "neededFraction": <fraction>
                                                   }
                                                 }
<course_group_credits_sum_constraint> ::= {
                                            "CourseGroupCreditsSumConstraint": {
                                              "courseGroup": <course_group>,
                                              "totalNeeded": <credits>
                                            }
                                          }
<course_group_fulfilled_all_constraint> ::= {
                                              "CourseGroupCreditsSumConstraint": {
                                                "courseGroup": <course_group>
                                              }
                                            }
<global_course_repeated_enrollment_constraint> ::= {
                                                     "GlobalCourseRepeatedEnrollmentConstraint": {
                                                       "maxRepeatedEnrollment": <integer>
                                                     }
                                                   }
<global_credits_sum_constraint> ::= {
                                      "GlobalCreditsSumConstraint": {
                                        "totalNeeded": <credits>
                                      }
                                    }
<course_enrollment_corequisite_constraint> ::= {
                                                 "CourseEnrollmentCorequisiteConstraint": {
                                                   "courseEnrollment": <course_enrollment>
                                                 }
                                               }
<course_enrollment_prerequisite_constraint> ::= {
                                                  "CourseEnrollmentCorequisiteConstraint": {
                                                    "courseEnrollment": <course_enrollment>
                                                  }
                                                }
<course_group> ::= {
                     "courseList": [ (<course>, )* ]
                   }
<fraction> ::= " <integer> / <integer> "
<string> ::= <character>(<character>)*
<course> ::= {
               "@id" : <uuid>,
               "id" : <string>,
               "name" : <string>,
               "localizedName" : <string>,
               "locale" : <locale>,
               "credits" : <credits>,
               "teacherNames" : [ (<string>, )* ],
               "prerequisites" : [ (<course>, )* ],
               "corequisites" : [ (<course>, )* ]
             }
<course_enrollment> ::= {
                          "@id" : <uuid>,
                          "course" : <course>,
                          "fulfilled" : <boolean>
                        }
<locale> ::= <character><character>
<credits> ::= {
                "@id" : <uuid>,
                "creditValue" : <integer>
              }
<boolean> ::= true | false
<uuid> ::= (<character> | <integer>)(<character> | <integer> | -)*