Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update README.md #435

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Update README.md #435

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
636961c
Update README.md
Marco-9456 Nov 25, 2023
aa13d0f
Update README.md
Marco-9456 Nov 25, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
159 changes: 79 additions & 80 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,93 +1,92 @@
![App Icon](https://raw.githubusercontent.com/SapuSeven/BetterUntis/master/app/src/main/res/mipmap-xxxhdpi/ic_launcher.png)

# BetterUntis
An alternative mobile client for the Untis timetable system.

<a href="https://circleci.com/gh/SapuSeven/BetterUntis"><img src="https://img.shields.io/circleci/build/gh/SapuSeven/BetterUntis?style=for-the-badge" alt="CircleCI"></a>
<a href="https://hosted.weblate.org/engage/betteruntis/?utm_source=widget"><img src="https://img.shields.io/badge/dynamic/xml?color=green&label=localized&query=%2F%2F%2A%5Blocal-name%28%29%3D%27text%27%5D%5Blast%28%29%5D%2Ftext%28%29&url=https%3A%2F%2Fhosted.weblate.org%2Fwidgets%2Fbetteruntis%2F-%2Fsvg-badge.svg&style=for-the-badge" alt="Translation status" width=147.5 height=28/></a>
<a href="https://hosted.weblate.org/engage/betteruntis/?utm_source=widget"><img src="https://img.shields.io/badge/dynamic/xml?color=green&label=localized&query=%2F%2F%2A%5Blocal-name%28%29%3D%27text%27%5D%5Blast%28%29%5D%2Ftext%28%29&url=https%3A%2F%2Fhosted.weblate.org%2Fwidgets%2Fbetteruntis%2F-%2Fsvg-badge.svg&style=for-the-badge" alt="Translation status"></a>
<a href="https://matrix.to/#/#github-betteruntis:sapuseven.com"><img src="https://img.shields.io/badge/chat-on matrix-blueviolet?style=for-the-badge" alt="Matrix"></a>
<a href="https://ko-fi.com/sapuseven"><img src="https://img.shields.io/badge/Support-On Ko--fi-%2313C3FF?style=for-the-badge" alt="Support on Ko-fi"/></a>
<a href="https://ko-fi.com/sapuseven"><img src="https://img.shields.io/badge/Support-On Ko--fi-%2313C3FF?style=for-the-badge" alt="Support on Ko-fi"></a>

<a href="https://f-droid.org/packages/com.sapuseven.untis"><img src="https://fdroid.gitlab.io/artwork/badge/get-it-on.png" alt="Get it on F-Droid" height="80"></a>
<a href="https://play.google.com/store/apps/details?id=com.sapuseven.untis&utm_source=github&utm_campaign=badge"><img alt="Get it on Google Play" src="https://play.google.com/intl/en_us/badges/static/images/badges/en_badge_web_generic.png" height="80"/></a>

You can also download the latest automated build [from my website](https://sapuseven.com/app/BetterUntis).
Download the latest automated build [from the developer's website](https://sapuseven.com/app/BetterUntis).

## Screenshots

| <img src="https://raw.githubusercontent.com/SapuSeven/BetterUntis/master/fastlane/metadata/android/en-US/images/phoneScreenshots/1.png" alt="Screenshot 1" /> | <img src="https://raw.githubusercontent.com/SapuSeven/BetterUntis/master/fastlane/metadata/android/en-US/images/phoneScreenshots/2.png" alt="Screenshot 2" /> | <img src="https://raw.githubusercontent.com/SapuSeven/BetterUntis/master/fastlane/metadata/android/en-US/images/phoneScreenshots/3.png" alt="Screenshot 3" /> | <img src="https://raw.githubusercontent.com/SapuSeven/BetterUntis/master/fastlane/metadata/android/en-US/images/phoneScreenshots/4.png" alt="Screenshot 4" /> |
|---------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|

## Development notes (v3.x.x)
My [original version](https://github.com/SapuSeven/BetterUntis-Legacy) of BetterUntis had many design and performance flaws.
As a result, development became increasingly more difficult.
I came to the conclusion that it was best to scrap the project and start over from scratch.

Although I reused some parts of the original code, my plan was to entirely switch to Kotlin.
Kotlin has many features and libraries that immensely help to communicate with the Untis API and process the timetable data.

Another major change is the use of a custom WeekView (based on [Till Hellmund](https://github.com/thellmund)'s fork of [Android-Week-View](https://github.com/alamkanak/Android-Week-View)) for the timetable display. This also improved performance by a lot.

## New features
- Search for your school by name or ID, no URL needed
- Login by using your password or app key
- Zoomable timetable view
- Improved overall design
- Improved timetable selection dialog
- Faster RoomFinder
- Faster timetable loading
- Lag-free timetable scrolling
- Flexible timegrid allows to display hours outside the regular timetable (like consultation times with teachers)
- Support for multiple accounts/profiles
- Support for using a custom proxy server for increased privacy
- Info Center for viewing events, contact hours and own absences
- Class management features for teachers (Absence checking, lesson topic editing, ...)

## Available languages
- English
- German

_Since v3.3.0:_
- Chinese (Simplified)
- French
- Norwegian Bokmål

_This list may not be up-to-date. Please look at "Translating" below to check the current translation status._

## Project Git Structure
I established a simple system to manage this Git repository.
Basically, there are two main branches: **master** and **develop**. They both are permanent and cannot be deleted.

### Branch: master
This branch always and only contains the latest release version. This includes alpha/beta releases.

### Branch: develop
This branch contains the current development version. Small changes and fixes can be committed directly to this branch.

When it reaches a state ready to release, it can be merged into the **master**-branch and a new release can be published.

### Other branches
Especially bigger features which require multiple commits should branch off **develop** and merge back into it. These should be named in a way to describe the feature as clearly as possible.

These branches have a limited lifetime. After the last merge back into **develop**, they should be deleted if no longer needed.

## Contributing

Your help is greatly appreciated, but first please read the following sections to prevent common mistakes:

### Translating into another language

If you haven't already, sign up for an account at [weblate.org](https://hosted.weblate.org/accounts/register/) .
You can then navigate to the [BetterUntis translation project](https://hosted.weblate.org/projects/betteruntis/translations/).

Select your desired language (or click the “Start new translation“ button at the bottom) and look at "Strings status".
All categories marked in red are areas where translations are missing or potentially incorrect. Click on them to start translating.

Your translation will then be automatically included in the next release of BetterUntis.

### Implementing new features / Fixing bugs

Anything that requires you to perform code changes should be done on the **develop** branch.
Pull requests should always be based on this branch, except for larger, experimental or incomplete features.
These can be on their own, new feature branch.

_Please **do not** submit pull requests that merge into the master branch, except for changes that **only** affect the repository on GitHub (e.g. README.md changes)._
| ![Screenshot 1](https://raw.githubusercontent.com/SapuSeven/BetterUntis/master/fastlane/metadata/android/en-US/images/phoneScreenshots/1.png) | ![Screenshot 2](https://raw.githubusercontent.com/SapuSeven/BetterUntis/master/fastlane/metadata/android/en-US/images/phoneScreenshots/2.png) | ![Screenshot 3](https://raw.githubusercontent.com/SapuSeven/BetterUntis/master/fastlane/metadata/android/en-US/images/phoneScreenshots/3.png) | ![Screenshot 4](https://raw.githubusercontent.com/SapuSeven/BetterUntis/master/fastlane/metadata/android/en-US/images/phoneScreenshots/4.png) |
|---|---|---|---|

## Development Notes (v3.x.x)
The [original version](https://github.com/SapuSeven/BetterUntis-Legacy) of BetterUntis faced several design and performance challenges. These led to a decision to rebuild the project from the ground up.

Key Improvements:
- Transition to Kotlin, enhancing API communication and data processing.
- Adoption of a custom WeekView (based on [Till Hellmund](https://github.com/thellmund)'s fork of [Android-Week-View](https://github.com/alamkanak/Android-Week-View)), boosting performance.

## New Features
- Easy school search by name or ID.
- Password or app key login.
- Zoomable timetable view.
- Enhanced design and usability.
- Improved timetable selection dialog.
- Faster RoomFinder and loading times.
- Smooth timetable scrolling.
- Flexible timegrid for extended hour display.
- Multiple account/profile support.
- Custom proxy server option for privacy.
- Info Center for events, contact hours, and absences.
- Class management tools for teachers.

## Available Languages
[![Translation status](https://hosted.weblate.org/widget/betteruntis/translations/multi-auto.svg)](https://hosted.weblate.org/engage/betteruntis/)

### Project Git Structure
>[!Note]
The BetterUntis repository is managed with a clear and efficient branching strategy to ensure smooth development and release processes. Here's an overview:
>
> - **Branch: master**
The master branch is the backbone of the repository, representing the stable, public face of BetterUntis. It contains the latest released
version of the application, including all stable alpha and beta versions. Updates to this branch are typically the result of a culmination
of tested and approved changes from the development branch.
>
> - **Branch: develop**
This is where the magic happens. The develop branch serves as the primary workspace for ongoing development. It is the breeding ground for
new features, enhancements, and bug fixes. Small, incremental changes are directly committed to this branch. Once these changes are vetted
and ready for public release, they are merged into the master branch, marking the next step in BetterUntis' evolution.
>
> - **Feature-Specific Branches**
For larger updates, complex features, or experiments that require a series of commits and more significant development work, separate
branches are created from develop. These branches are named descriptively to reflect the feature or improvement they are intended to
address. Upon completion, they are merged back into the develop branch. Post-merge, these feature-specific branches are deleted if they
are no longer needed, keeping the repository clean and organized.

### Translating into Another Language
- Sign up at [weblate.org](https://hosted.weblate.org/accounts/register/).
- Visit the [BetterUntis translation project](https://hosted.weblate.org/projects/betteruntis/translations/).
- Select a language to start translating.
- Your contributions will be included in the next release.

### Implementing New Features / Fixing Bugs
>[!Important]
Your contributions in the form of new features and bug fixes are invaluable to the BetterUntis project. However, to ensure a smooth integration of your work, please adhere to the following guidelines:
>
> - **Development Focus**
All code changes, whether they are new features or bug fixes, should primarily be based on and made to the **develop** branch. This
ensures
that your contributions are incorporated into the ongoing development process and tested thoroughly before being included in a public
release.
>
> - **Pull Requests**
When you're ready to submit your work, create a pull request targeting the **develop** branch. This is crucial for maintaining the
integrity of the master branch as a stable, release-ready version of BetterUntis.
>
> - **Feature Branches for Major Changes**
If you are working on a larger feature or an experimental update that is not yet complete or requires extensive testing, it is advisable
to use a separate feature branch. This approach allows for isolated development and testing of major changes without affecting the overall
stability of the develop branch.
>
> - **Avoid Direct Master Branch PRs**
Please refrain from submitting pull requests that merge directly into the master branch. The only exception to this rule is for changes
that are exclusively related to the repository's documentation or non-code assets on GitHub, such as updates to the README.md file.