Prepare winter term 24 25

.github/ISSUE_TEMPLATE/assignment-submission.md

@@ -4,7 +4,6 @@ about: Template to submit assignments
 title: Submission for assignment(s) X,Y,Z
 labels: assignments
 assignees: pkeilbach
-
 ---
 
 I would like to submit the following assignments:

.github/ISSUE_TEMPLATE/presentation-topic.md

@@ -0,0 +1,17 @@
+---
+name: Presentation Topic Suggestion
+about: Template to suggest presentation topics
+title: Presentation about X
+labels: presentations
+assignees: pkeilbach
+---
+
+I would like to suggest the following presentation topic:
+
+**Title**
+
+_Provide the title of your suggested topic_
+
+**Abstract**
+
+_Add a few sentences to describe your topic_

CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing Guide
+
+In thise course, we follow an open source development approach, and highly encourage and appreciate any kind of contributions. 👐
+
+For example, you can help by improving the documentation, setup guides, the lecture notes, provide bug fixes for the assignments, work on open issues (watch out for the [good first issue label](https://github.com/pkeilbach/htwg-practical-nlp/labels/good%20first%20issue)) or just fix some typos.
+However small it is, every contribution is welcome - and will probably be rewarded (TBD)! 🏆
+
+This guide will help you to get started with your first contribution! 🚀
+
+## Forking the Course Repository
+
+The recommended way to work with this course is to [fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks) the course repository.
+
+While cloning, as described in the [getting started guide](./docs/getting_started.md#clone-the-repository), lets you _participate_ in the course and work on the assignments, only forking the course repository allows you to contribute back bug fixes, enhancements, etc.
+
+To fork this repository, you can follow the official GitHub documentation on how to [fork a repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo).
+
+If you fork a repository, a copy of the repository will then be created in your user space.
+Besides the contributing aspect, you can also work independently on your assignments and push your changes to your remote repository.
+
+Cloning and setting up the environment works as described in the [getting started guide](./docs/getting_started.md#clone-the-repository), besides that you need to clone your fork to your local machine (instead of the course repository):
+
+```sh
+git clone https://github.com/<your-username>/htwg-practical-nlp.git
+```
+
+> 💡 Forking is a very common practice in open source developlment.
+> If you are new to open source development and have not forked a repository before, this may be a good learning opportunity for you! 🤓
+
+## Syncing you Fork
+
+During the semester, it is very likely that the course repository will be updated.
+To pull those updates from the course repository (aka the `upstream`), you need to do the following:
+
+```sh
+git fetch upstream
+git checkout main
+git merge upstream/main
+```
+
+You can also sync your fork in the web UI or GitHub CLI.
+Find more details in the official [GitHub docs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork).
+
+> 💡 Syncing your fork only updates your local copy of the repository. To update your fork on github.com, you must [push your changes](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository).

Makefile

@@ -24,15 +24,15 @@ docs: project
 pytest:
 	.venv/bin/pytest
 
-assignment_1:
+assignment-1:
 	.venv/bin/pytest tests/htwgnlp/test_preprocessing.py
 
-assignment_2:
+assignment-2:
 	.venv/bin/pytest tests/htwgnlp/test_features.py
 	.venv/bin/pytest tests/htwgnlp/test_logistic_regression.py
 
-assignment_3:
+assignment-3:
 	.venv/bin/pytest tests/htwgnlp/test_naive_bayes.py
 
-assignment_4:
+assignment-4:
 	.venv/bin/pytest tests/htwgnlp/test_embeddings.py

docs/assignments.md

@@ -10,11 +10,14 @@ The package is located in the `src` directory and is a fully functional and inst
 The core sturcture will be provided, and the assignments will be about implementing the missing functionality.
 
 To work on an assignment, you will need to locate the `TODO ASSIGNMENT-*` items in the code.
-For example, to work on the first assignment, use the search functionality of your IDE to find all relevant items:
 
-```txt
-TODO ASSIGNMENT-1
-```
+!!! example
+
+    For example, to work on the first assignment, use the search functionality of your IDE to find all relevant items:
+
+    ```txt
+    TODO ASSIGNMENT-1
+    ```
 
 !!! tip
 
@@ -24,13 +27,16 @@ TODO ASSIGNMENT-1
 
 Once you implemented everything, you can run the tests to check if everything works as expected.
 
-You can run the tests using the `make` commands, for example:
+You can run the tests using the provided `make assignment-*` commands.
+If all your tests pass, you successfully completed the assignment! 🚀
 
-```sh
-make assignment_1
-```
+!!! example
 
-If all your tests pass, you successfully completed the assignment! 🚀
+    For example, to test your implementation for the first assignment, you can run:
+
+    ```sh
+    make assignment-1
+    ```
 
 !!! tip
 
@@ -45,34 +51,50 @@ If all your tests pass, you successfully completed the assignment! 🚀
     pytest tests/htwgnlp/test_preprocessing.py
     ```
 
-!!! info
-
     Pytest is a very powerful testing framework and the de-facto standard for testing in Python.
-    You will not need to know all the details, but if you want to learn more, check out the [official documentation](https://docs.pytest.org/en/latest/contents.html).
+    You will not need to know all the details, but if you want to learn more, check out the [official Pytest documentation](https://docs.pytest.org/en/latest/contents.html).
+
+## Jupyter Notebooks
+
+Some of the assignments are accompanied by Jupyter notebooks.
+
+If you successfully complete an assignment, you can run the accompanying notebook and see your code in action.
+
+See the [Getting Started](./getting_started.md) guide for instructions on how to start the Jupyter server.
 
 ## Submitting Assignments
 
-To submit an assignment, you will need to demonstrate a successful test run.
+To submit an assignment, you will need to provide screenshots of a successful test run.
 
-Also we may walk through your code together to check if you understood the most important concepts.
+<!-- TODO issue-121 provide example screenshot -->
 
-## Jupyter Notebooks
+You can submit the screenshots via GitHub issue using the issue template for [Assignment Submission](https://github.com/pkeilbach/htwg-practical-nlp/issues/new/choose).
 
-Some of the assignments are accompanied by Jupyter notebooks.
+!!! note
 
-See the [Getting Started](./getting_started.md) guide for instructions on how to start the Jupyter server.
+    Submission via GitHub issue is preferred, but it is also accpeted if submit the screenshots via [email](mailto:[email protected]).
 
-## Working on your Assignments locally
+## Working on your Assignments
 
-There are a few strategies on how to work on your assignments locally.
+How you work on your assignments on your local machine is completely up to you.
+But following a consistent branching strategy will probably make you life easier.
 
-What you end up using is up to your personal preference.
+!!! info
 
-### Using a single branch
+    This is regardless of whether you use the recommended approach to fork the repository, or just clone it locally.
 
-This is probably the easiest way to work on your assignments and **generally the recommended way**.
+!!! note
+
+    Feel free to skip this section if you have basic familiarity with git and branching workflows.
 
-You can create a new branch for your assignments:
+!!! tip
+
+    If you are new to git or not very experienced, this is a great learing opportunity for you, as git is a very important tool in nowadays software development.
+    You can work on the assignments without getting too much into git, but this is a great way to gain some experience with git.
+
+### Using a single branch
+
+Generally, it is recommended to work on your assignments in a separte branch:
 
 ```sh
 git checkout -b my-assigments
@@ -85,45 +107,47 @@ git add .
 git commit -m "solution for assignment 1"
 ```
 
-Whenever updates are available, you can switch back to the `main` branch, pull the latest changes, and merge them into your branch:
-
-```sh
-git checkout main
-git pull
-git checkout my-assigments
-git merge main
-```
-
-!!! warning
+!!! tip
 
-    You should **not push** your branch to the remote repository.
-    It should not be visible to others.
-    Your implementation is only valid for yourself, in your local repository, and will not be merged into the `main` branch.
+    If you work on a fork, you can also push your changes to your remote repository.
+    This is not possible if you just clone the course repository.
 
 ### Using multiple branches
 
-Similarly, you could create a new branch for each assignment:
+Similarly, you could create a new branch for each assignment. This can help you to keep your work separated.
 
 ```sh
 git checkout -b my-assigments-1
 git add .
 git commit -m "solution for assignment 1"
 ```
 
-But note that you would need to merge updates from the `main` branch into each of your assignment branches.
+### Using your local working tree
 
-Also keep in mind that some assignments build upon each other.
+If you don't want to deal with git, you could also work purely locally without committing anything.
 
-### Using stashing
+!!! warning
 
-You could also work on your assignments directly in the `main` branch, and whenever you need to pull the latest changes, you can stash your changes, pull the latest changes, and then pop your changes back:
+    This is not recommended, as this bears the risk of losing your progress, or dealing with lots of merge conflicts.
+    When pulling updates, you probably need to [stash](https://git-scm.com/docs/git-stash) your changes.
+    But be careful: if not done properly, you may lose your progress! 😱
+
+## Pulling Updates
+
+As described in the getting started guide, there will be [updates](getting_started.md#pulling-updates) from time to time.
+It can happen that these updates affect the assignments (just in case you are wondering why your tests suddenly fail 😅).
+
+Given that you work on a separate branch on your assignments, you can merge the latest version of the `main` branch into your assignment branch as follows:
 
 ```sh
-git stash
-git pull
-git stash pop
+# Fetch the latest changes from the remote main branch
+git fetch origin main
+
+# Merge the main branch into your current feature branch, e.g. my-assignments
+git merge origin/main
 ```
 
-Note that this way, you may lose your changes if you do not stash them properly.
+!!! info
 
-See the [git stash documentation](https://git-scm.com/docs/git-stash) for more details.
+    In case you work on a fork (which is awesome 🙌), the process is similar, but you need to fetch from the `upstream` remote repository.
+    This is described in the [contributing guide](https://github.com/pkeilbach/htwg-practical-nlp/blob/main/CONTRIBUTING.md#syncing-you-fork) in more detail.

docs/getting_started.md

@@ -52,21 +52,23 @@ The recommended Python version for this course is 3.12. in a virtual environment
     You are free to use another Python version if you wish, but be aware that this may cause problems with the provided code.
     Also if you are using Python outside a virtual environment or with a distribution like Anaconda, the described setup may not work.
 
-## Fork and clone the repository
+## Clone the Repository
 
 Make sure you have [Git](https://git-scm.com/) installed on your system.
+Now you can clone the course repository:
 
-Then, create a fork using the GitHub WebUI, and clone the repository to your local machine.
-
-<!-- TODO issue-123 reference contribution guide-->
+```sh
+git clone https://github.com/pkeilbach/htwg-practical-nlp.git
+```
 
-!!! info
+!!! tip
 
-    If you are new to this, you can follow the official GitHub documentation on how to [fork a repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo).
+    While cloning the course repository, as described here, lets you _participate_ in the course,
+    it is generally recommended to [fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks) the course repository.
 
-!!! note
+    That way you can _contribute_ back bug fixes, enhancements, etc., which is highly encouraged and appreciated 🚀
 
-    You can also clone the course repository directly, but then you cannot contribute back bug fixes or enhancements (which would be highly appreciated! 👐). You can find more details about this in the contributing guide.
+    You can find more details about contributing and forking the course repository in the [contributing guide](https://github.com/pkeilbach/htwg-practical-nlp/blob/main/CONTRIBUTING.md).
 
 ## Execute the Setup Script
 
@@ -83,12 +85,24 @@ This may take a few minutes. ☕
 
 If everything went well, you should be good to go.
 
+From now, make sure that you have the virtual environment activated.
+Usually, the IDE should automatically suggest you to activate it (e.g. VSCode).
+If that is not the case, you can activate the virtual environment with the following command
+
+```sh
+# activate the virtual environment manually
+source .venv/bin/activate
+
+# in case you need to deactivate it
+deactivate
+```
+
 ## Test your Installation
 
 You can test your installation by running the tests for the first assignment.
 
 ```sh
-make assignment_1
+make assignment-1
 ```
 
 In your terminal, you should see lots of failed tests. 😨
@@ -99,13 +113,17 @@ But this is exactly what we want to see, since we haven't implemented anything y
 
     You can find more details on how we handle assignments on the [corresponding page](./assignments.md).
 
+If you came this far, your initial setup was successful and you are ready to go! 🚀
+
+Now we can take a look at some other components of the repository.
+
 ## Jupyter
 
 Some of the assignments are accompanied by Jupyter notebooks.
 
 If your IDE supports it, you can execute the Jupyter notebooks natively in your IDE (e.g. using the [VSCode Jupyter extension](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.jupyter)).
 
-IF you prefer the WebUI, you can start the Jupyter server with the following command.
+If you prefer the web UI, you can start the Jupyter server with the following command.
 
 ```sh
 make jupyter
@@ -127,6 +145,23 @@ make docs
 
 The lecture notes are now accessible at <http://localhost:8000/>.
 
----
+## Pulling Updates
 
-If you came this far, your initial setup was successful and you are ready to go! 🚀
+Every now and then, the course repository will be updated.
+To incorporate these updates, you will need to pull from the `main` branch:
+
+```sh
+# make sure you are on to the main branch
+git checkout main
+
+# pull the updates from the remote repository
+git pull
+```
+
+!!! note
+
+    For a fork, the process is a little different, and described in detail in the [contributing guide](https://github.com/pkeilbach/htwg-practical-nlp/blob/main/CONTRIBUTING.md#syncing-you-fork)
+
+!!! tip
+
+    It is good practice to pull the latest changes from `main` every now and then (just in case you are wondering why your assignment tests suddenly fail 😅). However, important updates will be announced in the lecture.