yacs-rcos / yacs

Yacs - The Scheduler for Everyone

Yacs - The Scheduler for Everyone

To use Yacs @ RPI, visit https://rpi.yacs.io. Coming soon to NYU, and a school near you.

See yacs.io for our complete documentation.

What is Yacs?

Yacs was created with the goal of making students' lives a little easier. It allows users to avoid the clunky UIs of proprietary Catalog Management and Student Information Systems, replacing these unpleseant experiences with easy browsing and searching of courses, and adds the additional functionality of easy schedule generation, and much more.

But Yacs has grown to be much more than a simple schedule generator. Our mission at Yacs is the following:

1. To alleviate the stress around academic and extracurrciluar planning for Students, Faculty and Staff by offering a Free, easy-to-use interface to supplement or replace traditional academic information and management systems.

2. To enable innovative, disruptive applications in the academic space by breaking down propreitary information silos and providing consistent, digestible, Open Data.

3. To empower students to take control of their academic experience and excel their careers through learning about and contributing to Open Source.

Further, Yacs aims to provide the best experience possible to as many people as possible by serving as many universities as we can. Yacs is built from the ground up to be modular and flexible, and as such can use data from any source, and even combine data from many sources in an intelligent way.

We have made it as easy as possible to connect Yacs to your university, and have designed this process to be accessible to developers of nearly any skill level. Please check out our documentation or contact us if you'd like to bring Yacs to your school, and help us make Yacs as great as it can be.

Yacs owes its creation and continued maintenance to RCOS, the Rensselaer Center for Open Source, and is developed in collaboration with BUGS, NYU's Open Source Club.

API

Yacs exposes an API that provides easy, open access to your school's public academic data. This API can be used to collect and analyze data, create extensions and third party applications, and provide valuable external services and integrations. Our API documentation can be found on our public site, yacs.io. We can't wait to see what you build.

Setup

Installing Yacs is easy as pie. Installation and setup documentation can be found on our public site, yacs.io.

Contributing

Yacs is a community built and run project, and we depend on your ideas and contributions. We encourage you to submit issues and contribute to Yacs! To contribute fork the repo, comment on an issue, and submit a pull request to the staging branch. Complete contributing information can be found on our public site, yacs.io.

Code of Conduct

In the interest of fostering an open and welcoming environment, Yacs pledges to be an inclusive and harassment-free experience for all, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, educational background, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.

To this end, the Yacs community adheres to the RCOS Code of Conduct. It is vital that all contributors read and respect the Code of Conduct.

License

Yacs is and always will be Free and Open Source software, and is released under the AGPL License.

Contributors

Thanks goes to these wonderful people for making Yacs awesome (emoji key):

Ada Young 💬 📝 🐛 💻 🎨 📖 📋 💡 🤔 🚇 📦 👀 📢 🔧	copperwater 📝 💻 🎨	Ayushi Mishra 📝 💻 🎨	Kathleen Burkhardt 💬 📝 🐛 💻 🎨 📖 📋 👀 📢	Mark Robinson 💻 🚇 📦	HaoxinLuo 💻 🔧	Arijit Deb 💻 🚇
James Grippo 📝 💻 🎨	Ryan Stillings 📝 💻 🎨 📖 🤔 🔌 📢	Jason Lee 💻	Elizabeth Fine 💻	Eli Schiff 💻	Shay Rosado 💻	Daniel Ackermans 📝 💻 ⚠️
Yuze Ma 💬 📝 💻 🎨 📖 📋 🤔 🚇 📢 🔧	Alex Zuckut 💻 ⚠️	Kelly Wang 💻	Raz Reed 💻 🤔	sjhuang26 💻 🎨 🤔	Haochang Caspar Qian 💻 🎨 📖	Perri Adams 📝 💻 🎨 🤔
Josh Goldberg 🐛 💻 🤔	huangmj7 💻	James Milne 📝 💻 🎨 🤔	Darren Lin 💻 🎨 🤔 ⚠️	Bryan Dieudonne 📝 💻 🎨 💵 🤔 🚇 🔧	Albert Liu 📖	bradleybrecher 📝 📖 📋 🤔
Briana Griffin 💻 🎨 🤔

This project follows the all-contributors specification. Contributions of all kinds welcome! If you are missing from this list, or would like to be removed, please open a PR or let us know <3

yacs's Issues

DRY up API views

There is a lot of repeated code in API views. There is currently no use of partials. Partial views should be used for each model.

Asynchronous AJAX calls

Ajax calls (namely getting course xml data from api) are synchronous, and cause the browser window to freeze during long response times. frontend caching would mitigate this issue as well, but the calls should really be asynchronous.

Don't select closed sections when clicking on a course

Title says it all. If someone wants to select a closed section they have to click on it specifically.

Refactor scheduler request specs to unit specs

Scheduler testing is currently done completely at the network level. While these tests adequately test the functionality of the scheduler code, the code should really be unit tested.

Representation of closed courses in the course list and on the schedule

There is nothing stopping students from selecting closed sections, as per our design. Therefore, there needs to be some noticeable way of representing closed sections.

We haven't discussed the appearance of closed courses on the course list (my initial idea is coloring the "0 seats" text YACS red.) For closed courses on the schedule, we decided that a diagonally striped background, perhaps in the same color as that course's background would be, would work.

Change day representation in database so that Sunday is 0

The frontend is capable of creating schedules with all seven days of the week, using a Sunday 0 - Saturday 6 index. However, in our database, the weekdays are represented as Monday 0 - Friday 4, because that is how they are represented in RPI's system.

We should support 7-day schedules (RPI doesn't have weekend classes, but other schools do), so the RPI catalog parsing script should add 1 to the day number it gets from the database to make it agree with the 7-day indexing scheme.

Implement a general school-balancing algorithm for the homepage

The XML API, as we know, does not consider the amount of columns of schools that the client can render and it is left to the frontend to determine how to fill the columns. The current algorithm for filling these is to sort them by "height" (roughly calculated as the number of departments in a school plus one on the assumption that departments will all be the same height and the school heading is around that height), and then iterate over the columns, placing the largest remaining school there, and looping back to the left column. The shortcomings of this approach are evident in how RPI's schools render in two columns: the left column is substantially taller than the right.

Optimally, there should be an algorithm in place which, given the array of school heights and number of columns to fill, returns data that places the schools in the columns such that their heights are as even as possible.

Optimize automated seat count updating

derived from https://github.com/aosdict/yacs/issues/23

Automated seat count updating has been implemented but should be optimized. taken from #23 , "A suggested approach is to poll this file every minute or so and store it in memory. On each subsequent poll, diff the new file with the one previously stored, and update sections corresponding to changed lines. (obviously) then update the locally stored copy. The records corresponding to the changes seat counts should then be updated in the database."

Design - notify users when we cannot serve very recent/instantaneous data

The registrar's servers must be treated as unreliable - YACS cannot assume that it can get data whenever it wants. What we can assume, though, is that the server will deliver data the great majority of the time.

I know we made plans to have some way of displaying how up-to-date the data is. My suggestion is that whenever the server fails to get data, there is a prominent display warning the users that the information is X minutes outdated.

API - Partial data requests by date

Applications should be able to pass the time of their last API request, and receive only information that has changed since that time

Caching for API views

There is a lot of performance to be gained from partial caching of API views. Most of the records in our database rarely change, if ever. Once the API views are DRY, caching should be added following the rails "Russian Doll" caching pattern.
Blocked by https://github.com/aosdict/yacs/issues/27

Fancy search

Ideally, the search bar should be able to process basic sentence structure, such as: "math class taught by Professor Rainsford at 10 AM on Monday and Thursday", which would then break down into the search components (department = math && professor = Rainsford && start-time = 10AM && (day = Monday || day = Thursday).

Schedule image export

Users should be able to save their schedule to a PDF file or print it directly from the browser. Different from using normal browser print function because it shouldn't print the header bar or anything else on the page except maybe a text list of courses and times.

This is something that should be done well after YACS is launched and working properly, far in the future.

License

We need to decide on a license for this version of YACS, because it's not open-source till we have an open source license.

Document configuration and setup steps

Currently we have almost no documentation on how someone downloading this repository should configure and build YACS.

Things I can point out right now:

• The README.rdoc is the default one and contains no information about proper setup. Also it should probably be renamed to SETUP.rdoc so we don't have two README files.
• The vagrant.sh probably needs some comments in it.
• Maybe the various Ruby config and runtime files sitting around at top level can get comments explaining what they do.

Conflicting courses on the schedule for non-vital conflicts and conflict comparison

The schedule view should eventually be able to support schedules with courses with overlapping times, since it is administratively possible to do this.

As a student, I would like to specify inclusive and exclusive search terms so I can search for courses more effectively

According to Richie, toggling between a default AND search and a default OR search on the backend is easy. There should be a configuration option somewhere to set this default.

Additionally, we want to look into letting users put pipes/ampersands in their searches. This would be added to the parsing step in the search API.

create rake task for loading catalog

currently, to load the catalog, the database must be cleared and the line Catalog::RpiCatalogLoader.new.load_catalog must be run in the rails console. This should be a rake task.

Create behavior on the page that will tell users they need to enable Javascript

We don't appear to have any plans to make a Javascript-less version of the site. The main page should use <noscript> tags to detect whether the client is enabling Javascript and inform them that YACS requires Javascript to work.

Copyright and authorship

The old YACS page has meta tags naming Jeff Hui as the author and marking the site "(c) 2011 Jeff Hui". I don't know what to put in the author/copyright tags on our page; while we are using Jeff's ideas, we are using none of his code.

Loading catalog should update previously populated database

Currently, the database cam only be populated from empty in one shot. loading the catalog should update existing entries and add new ones where appropriate.

Lots of tests are broken

API tests need to be updated to new xml structure

Display section period information

In the courses view, period information should be displayed alongside each section. Each section should show the day, time, and type of each period. Please comment with how this data should preferably exposed by the xml api.

Loading message needed when loading course xml from api

Could be a message, wheel, bar, whatever you want get creative.

Create benchmarks for Scheduler

The scheduling algorithm needs to be benchmarked before performance enhancements can be attempted.

Course titles and descriptions pulled from course catalog are badly formatted

As the issue title says. There are known problems with capitalization in the course titles - looking through ITWS courses gets me results like "Introduction To Hci" and "It and Society".

In addition, course descriptions contain a repeat of the course department, number, and title smushed up against the actual description text, like "ITWS 2210 - Introduction to Human Computer InteractionAn introduction to the current theories, methods, and issues in human-computer interaction..."

This is a problem with the course catalog parser (the erroneous text is represented that way in the database).

Create HTML schedule tables from the JSON API

Make YACS generate a fully populated schedule page able to display all schedules from selected courses and navigate between different schedules. The schedule table need not have any interactive parts.

I'm already working on this; it's just good to have it here for project management.

Implement RPI Catalog API

Currently we are parsing and scraping catalog data from multiple sources. There exists an API for the RPI catalog and we should be taking advantage of that. Information on this API will be posted here as it becomes available.

Selection Persistence

Section selections (and thus generated schedules) should persist after navigating away from the site

Use schools.txt and departments.txt to control data population of schools and departments

Currently, RPI provides us no school data whatsoever, and department names are sometimes represented in a truncated form we don't want to display (e.g. "Information Technology and Web Science" -> "Information Technlgy & Web Sci.") Also, it has a lot of departments that either don't exist, exist but for other campuses, or are never used by anyone. The proposal is to use schools.txt and departments.txt as data files to act as controls on the data coming from the parse script. This will let the YACS administrators (who could be at any college with its own data quirks) show only the departments they want and arrange them into schools however they want.

schools.txt is a tab-separated file with the school name first and any number of department codes after that. departments.txt is a tab-separated file with the department code first and the department's extended name second. When the database populates the schools and departments tables, it will use the data in these files.

Richie already implemented this now; this issue is mainly for us making it an official part of the design and documenting it.

Centering schedule table

The schedule table is slightly off-center because it has the extra column at the left for the hours.
It would really look better if Wednesday were centered on the page.
One possible solution is to create an extra column with the same width as the hour column on the right (filled with  ?) but that will make the overall table larger, which we may not want.

Investigate performance enhancements for scheduler

Once benchmarks are created, other algorithms for scheduling can be explored and comparatively benchmarked. Additionally, the procedure can be written as a native C extension, or as an PostgreSQL procedure. The SQL option may be best as it would spare the server a number of avoidable load operations, but every options should be tested.

blocked by #50

As a student, I would like to navigate back and forward natively so I can navigate the site more effectively

The History API should be implemented to allow the user to navigate around the site properly using the forward and back buttons. Because the site only consists of one true page and uses AJAX for all content changes, there is no history and the forward/back navigation buttons do not perform any useful purpose by default.

This is a feature of HTML5 and in order for this to work on older browsers a library such as History.js could be used.

Course watch/notification system

Have some sort of system which monitors certain courses to see whether their size was increased or seats became available.
Students can choose courses they want to register for and YACS will notify them personally if seats become available. Failing that, YACS can just watch courses (flagged by students?) and publicly announce size increases over RSS/Twitter/some other similar medium.

Support weekend sections in the schedule page

RPI doesn't have any courses with meeting times on weekends. However, other schools do. The schedule page must eventually support weekend courses and generate the class grid accordingly. I recommend that the days appear in SMTWTFS order, and any days on either end that don't have any courses don't become part of the table. (I.e. if you select one class that meets on Tuesday and Thursday you get a schedule with only Tuesday, Wednesday and Thursday on it.)

This shouldn't require any backend work; weekend classes can already be represented in the database and passed through the API.

Create benchmarks for API

All API responses should be benchmarked before any caching is implemented

Make the home page resizable

As the title says:

• Currently, the course lists handle resizing well and only run into a few cosmetic problems when you smush it so small that section names and times can't fit on the same line. No changes are really needed.
• The home page should have resize events that detect when it has grown too small for as many columns as it has or large enough to accommodate more, and repopulate the page accordingly.
• The schedule page will be problematic. I don't quite like the fixed-pixel scheme it currently has, since that prevents resizing and also forces a standard font size. If there's any way to make it dependent on ems only, that should be done and then resizing should be added (perhaps by shrinking the font, or something.)

Text between schedule selection arrows does not change when arrows are pressed

Pressing the selection arrows should update the text "1/N" to "2/n" ...

Also, the text and should not be selectable. currently, clicking them a few times results in them being highlighted.

Search - order results by number of terms matched

When the search API is used to find courses, it should keep track of how many terms in the search query matched a given course. Then when it returns the courses to the user, it should sort the list of courses by that number. All matching results will be displayed, but in order of relevance. This combines the benefits of OR-based searches (show anything that matched) with the benefits of AND-based searches (multiple search terms give the best, most specific result).

Example: Searching for "CourseName ProfName" will return first courses named CourseName which are taught by ProfName, then any other courses named or matching CourseName, then all other courses taught by ProfName.

Easy way to get CRNs submitted

Right now, we have no way of expediting the process of getting Course Reference Numbers into the SIS registration form. We can display them on the page and the user can copy and paste them one by one and that's about it. This offers no improvement over yacs.me.

There should be a way to either copy all CRNs from a schedule and be able to paste them all at once into the fields on SIS, or to submit a POST request directly from the page that will submit the numbers for the user.

API - Courses

create courses api views:

• index
• show

API - Departments

create departments api views:

• index
• show

Create Facebook Page

A Facebook page should serve to notify the RPI community of the new app and keep them up to date with changes, enhancements, and new features

Re-add course title tooltip to periods on the schedule view

Currently, the schedule generates one guaranteed line of text for each period - the department code, course number, section number, and class type. I'd like to add course titles for periods that are long enough to hold them. These course titles are already exposed in the API and are parsed into the period objects in yacs-main.js.

The problem is that course titles can get quite lengthy and there's no good way to estimate how many lines they will take up at our font size and width. (I tested it and found that the longest string of "m" that will fit on one line is only 10 characters long, but of course the average amount of characters per line is much higher.) The general formula for now is (number of lines) = (number of full half-hours in the period), which is already being calculated.

Setting course elements to overflow:hidden allows the text to be horizontally cut off on the last line, so I doubt that it's an acceptable solution.

Schedule section deselection

The schedule page needs to have a separate list of courses that can be clicked to deselect the course. This will affect the cookie and force a re-generation of all schedules. There must also be reselection capabiities, so the entire page cannot be reloaded; accounting for this will require some restructuring of the schedule loading functions.

The proposed method of resolving this is as follows:

• loadSchedules will remain the function called when the user clicks "Schedules" in the navbar, to parallel loadCourses and loadHomePage.
• Move the code that reloads the schedule page out of loadSchedules() into a separate function.
• Have loadSchedules call this new function during its page load.
• Design the appearance and HTML of the section deselection list.
• Have loadSchedules populate this list during page load, and apply event listeners to each section on it that will add or remove the section from the cookie list of selected courses and call the schedule re-generation code for it.

API - Sections

create sections api views:

• index (on semester_course)
• show

Automated seat count updating (database level)

A key part of the application's function is automatic and timely updates to seat count information. The information will be parsed from the xml file found here https://sis.rpi.edu/reg/rocs/YACS_201601.xml

A suggested approach is to poll this file every minute or so and store it in memory. On each subsequent poll, diff the new file with the one previously stored, and update sections corresponding to changed lines. (obviously) then update the locally stored copy. The records corresponding to the changes seat counts should then be updated in the database.

Search - Mapping colloquial search terms to actual database results

Many things that people will search for are colloquial terms and therefore not represented in the database. For example, RPI offers a course named Programming Languages, but it is almost universally referred to as Proglang. We can expect people to search for Proglang and other informal names, though, so there should be some database representation of these that allows them to be searched.

This might be accomplished by having a separate table mapping these terms to their full names. Then, if a search term is unmatched in any other table, the search code can attempt to find it in this table.

Search with explicit parameters

There can be conflicts in the database between keywords of different types. For example, the department code "Biol" can also be a professor's name. Thus, with a un-parametrized search, searches for this keyword alone will always have the same result. This would cause problems when you search for Professor Biol and get your desired results buried under all the biology classes.

There needs to be a way to explicitly state that a search term should only be searched for in a certain table. We could make it inlined in the search string, like "professor:Biol" or "professor=Biol"; or making a different (non-default) header bar with multiple search fields.

Add arrow key navigation to schedule page

When on the schedule page, the user should be able to hit Left and Right on the arrow keys to navigate between schedules. This may require revising the auto-searchbar-focus functionality slightly.