StudyGuide

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

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

Install Git
- Fedora: sudo dnf install git
- Ubuntu: sudo apt-get install git
Install Java8 JDK — Oracle JDK Downloads — Select: Java Platform (JDK)
- NOTE: You need jdk-8u40 or newer (JavaFX 8 dependency).
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
Fork the repository — Create a fork of the oskopek/StudyGuide repository (right upper corner) on GitHub, usually the fork will be called: yourusername/StudyGuide.
Clone the your fork — run git clone https://github.com/yourusername/StudyGuide.git (or, preferably, use SSH: git clone [email protected]:yourusername/StudyGuide.git)
Run the build (see the Building section)

Windows

Install Java8 JDK — Oracle JDK Downloads — Select: Java Platform (JDK)
Install Maven — (preferably the latest version you can). See: Maven on Windows and Maven Downloads.
Download and install GitHub for Windows at http://windows.github.com/. If you encounter any problems, see the GitHub for Windows FAQ.
Find the oskopek/StudyGuide repository on GitHub.
Create a fork of the repository (right upper corner), usually the fork will be called yourusername/StudyGuide.
Run the build (see the Building section)
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

Fork the repository
Create a topic branch
Optional: To ease the process of contributing code back into StudyGuide, please set-up IDE coding templates first
Implement your feature or bug fix
If applicable, add tests and documentation for your feature or bug fix (see How-to write documentation)
Run mvn clean install -Pit
If the tests fail, return to step 3 and 4
Add, commit, and push your changes
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> | -)*

oskopek / studyguide Goto Github PK

studyguide's Introduction

StudyGuide

Screenshot

Getting help

Running StudyGuide releases

Building & running StudyGuide

Setup your build environment

Linux & Mac

Windows

Submitting an Issue

Contributing

Submitting a Pull Request

Data format

Data format details

studyguide's People

Contributors

Stargazers

Watchers

Forkers

studyguide's Issues

Recommend Projects

Recommend Topics

Recommend Org