Part 1 Tasks ============== These tasks give you a real repository to practice the workflow from :doc:`index` on. Work through them in order — each one builds on the previous task's result, and each one should be done as its own full cycle of the recipe above (update, branch, commit, push, merge request, merge). .. note:: Make sure you've worked through :doc:`../prerequisites` first — in particular that ``python --version``, ``git --version`` and ``cookiecutter --version`` all work, that you've set your git identity, and that your SSH key is uploaded to GitLab. If any command below fails with an error, check :doc:`../troubleshooting`. Task 1: Create a repo ------------------------ Create the empty project on GitLab ____________________________________ #. Go to `git.tu-berlin.de `_ and sign in. #. Click the **+** button in the top navigation bar → **New project/repository**. #. Choose **Create blank project**. #. Fill in: * **Project name**: something like ``git-workshop-basics`` (this also fills in the URL automatically). * **Project URL**: pick the `kiwi-git-workshops `_ group if you have access to it, otherwise your own username. * **Visibility**: Private is fine for now. .. warning:: **Untick "Initialize repository with a README".** GitLab ticks this by default, which creates a first commit on the server. If you leave it on, the push in the next section fails with ``! [rejected] main -> main (fetch first)``, because your local history and the server's history have nothing in common. You want a completely empty project here. #. Click **Create project**. You'll land on a page showing setup instructions — keep this tab open, you need the repository address from it shortly. Generate your practice package ________________________________ Cookiecutter creates the new project folder **inside whatever directory your terminal is currently in**, so move somewhere sensible first: .. code-block:: none cd %USERPROFILE%\projects # Windows (create the folder first if needed) .. code-block:: none cd ~/projects # macOS/Linux Then run: .. code-block:: none cookiecutter https://github.com/spirousschuh/cookiecutter-git-workshop-basics It asks you a series of questions, showing the default answer in square brackets — press Enter to accept a default, or type your own: .. code-block:: none author_name [Josephine Doe]: Your Name author_email [your@address.eu]: your.name@campus.tu-berlin.de package_name [git_workshop_basic]: package_description [A lightweight python package to practise some git]: package_url [https://git.tu-berlin.de/you/your_repo_name]: The answer to **package_name** becomes the name of the folder your package is generated into. Use lowercase letters and underscores, no spaces or hyphens — it has to be a valid Python name. .. note:: If you run cookiecutter a second time it asks *"You've downloaded ... before. Is it okay to delete and re-download it? [y/n]"* — answer ``y``. It's just re-fetching the template. **How do you know it worked?** You now have a folder structure like this (assuming you kept the default name): .. code-block:: none git_workshop_basic/ <- the project folder ("outer") git_workshop_basic/ <- the Python package itself ("inner") __init__.py cli.py tests/ test_cli.py pyproject.toml tox.ini README.md LICENSE .gitignore sample_picture.jpg .. important:: Note the two folders with the same name. The **outer** one is your project — that's the one you open in PyCharm, run ``git`` commands in, and run ``pip install -e .`` in. The **inner** one is the Python package containing the actual code. Whenever these tasks say "your project folder", they mean the outer one. Connect it to GitLab ______________________ Move into the outer project folder and turn it into a git repository: .. code-block:: none cd git_workshop_basic git init git add . git commit -m "Initial commit from template" Now connect it to the empty GitLab project you created and push. Copy the SSH address from your GitLab project page (the **Clone** button → *Clone with SSH*); it looks like ``git@git.tu-berlin.de:kiwi-git-workshops/git-workshop-basics.git``: .. code-block:: none git remote add origin git@git.tu-berlin.de:kiwi-git-workshops/your-project.git git branch -M main git push -u origin main You should see output ending in something like:: To git.tu-berlin.de:kiwi-git-workshops/your-project.git * [new branch] main -> main If you instead get ``Permission denied (publickey)`` or a rejected push, see :doc:`../troubleshooting` — both are covered there. **How do you know it worked?** Refresh your project's page in the browser. You should now see the package's files and a rendered ``README.md``. Task 2: Improve the README ----------------------------- #. Create and activate a virtual environment inside your project folder (see :doc:`../prerequisites` for the full explanation), then install your package into it in editable mode, so changes you make take effect immediately without reinstalling: .. code-block:: none python -m venv .venv .venv\Scripts\Activate.ps1 pip install -e . .. code-block:: none python3 -m venv .venv # macOS/Linux source .venv/bin/activate pip install -e . **How do you know it worked?** The last lines of the output say ``Successfully installed git_workshop_basic-0.0.1``, and your prompt shows the ``(.venv)`` prefix. #. Open the **outer** project folder in PyCharm (**File → Open**, select the folder, and accept "Trust project"). Point PyCharm at the ``.venv`` you just created, as described in :doc:`../prerequisites`. #. Using the full workflow from :doc:`index` (update → branch → commit → push → merge request → merge), edit ``README.md`` to describe what the package does. The generated file contains ``TODO(Task2)`` markers showing where to write. ``README.md`` is written in **Markdown**, a simple formatting syntax: ``#`` at the start of a line makes a heading, ``##`` a sub-heading, ``-`` starts a bullet point, and text between backticks renders as ``code``. GitLab renders it automatically on your project page. **How do you know it worked?** After merging, your project's landing page on GitLab shows your new text. Task 3: Document the thumbnail command ------------------------------------------ Your generated package ships with a small command line program called ``image_magic``. It exists because ``pyproject.toml`` declares it as an *entry point*, and ``pip install -e .`` wired it up — which also means it only works while your virtual environment is active. #. Explore it, running these from your project folder: .. code-block:: none image_magic --help which prints the available sub-commands:: Usage: image_magic [OPTIONS] COMMAND [ARGS]... Options: --help Show this message and exit. Commands: rotate thumbnail Creates a small thumbnail image #. Now actually run one. The project folder contains ``sample_picture.jpg`` to practice on: .. code-block:: none image_magic thumbnail --input-path=sample_picture.jpg --output-path=thumb.jpg On success it prints ``Successfully saved image at thumb.jpg``, and a new ``thumb.jpg`` appears in your project folder — open it (double-click it in PyCharm's file tree) and you'll see a much smaller version of the original. .. note:: Both paths are relative to your current directory, so this only works if you're *in* the project folder. The output filename must end in ``.jpg``, since that's the format it saves as. #. Using the full workflow again, document how to create a thumbnail from the command line in ``README.md``. Task 4: Change the thumbnail size ------------------------------------- Your first real code change. From here on, always use the full workflow for every change, however small. #. Open ``git_workshop_basic/cli.py`` — that's the **inner** folder — and find the ``thumbnail`` function. The line that sets the size is: .. code-block:: python size = (128, 128) The two numbers are the maximum width and height in pixels. #. Change them to something noticeably different (e.g. ``(32, 32)``). #. Test that it works: re-run the ``image_magic thumbnail`` command from Task 3 and open the resulting image — it should now be visibly smaller. You do **not** need to reinstall; that's what editable mode buys you. #. Merge your feature branch. Task 5: Change the rotation direction, and commit hygiene -------------------------------------------------------------- This task introduces an important habit: keeping documentation changes and code changes in **separate commits**, even within the same branch/merge request. It makes the history much easier to read later ("this commit changed behavior, that one just documented it") and makes it possible to revert one without the other. #. Try the rotate command first, so you can see what changes. It needs an ``--angle`` in degrees: .. code-block:: none image_magic rotate --input-path=sample_picture.jpg --output-path=turned.jpg --angle=90 #. Document that functionality in ``README.md`` — and commit *just this change*, on its own. #. Now find the ``rotate`` function in ``cli.py``. It calls Pillow's ``im.rotate(angle)``, which by convention turns the image **counter-clockwise**. Make it turn clockwise instead — rotating by the negative of the given angle achieves this. #. Commit that code change as a **second, separate commit**. To keep commits separate in PyCharm, use the **Commit** tool window (left sidebar). It lists your changed files with a checkbox each: tick only ``README.md``, write a message, commit — then tick only ``cli.py``, write a different message, and commit again. Both commits go onto the same branch and into the same merge request. #. Merge your feature branch. Task 6 (optional, harder): Color to black-and-white ---------------------------------------------------------- More open-ended — you'll need to look things up, which is itself a skill worth practicing. #. Add a new CLI sub-command so that this works: .. code-block:: none image_magic color-to-bw --input-path=sample_picture.jpg --output-path=bw.jpg Copy the structure of the existing ``thumbnail`` command in ``cli.py`` (the ``@cli_group.command()`` and ``@click.option(...)`` lines above the function are what turn a plain Python function into a sub-command). For the conversion itself, look at Pillow's `Image.convert `_ — mode ``"L"`` means greyscale. #. Document the new feature (as its own commit). #. Merge your feature branch. Wrapping up ------------- After merging on the server, your **local** ``main`` is now behind the remote — the merge happened on GitLab, not on your machine. Switch back to ``main`` and pull, which is exactly step 1 of the cycle: .. code-block:: none git checkout main git pull You can also delete a merged branch (GitLab offers a button for this in the merge request, and PyCharm can delete the local copy) — once merged, it has served its purpose. Once you're comfortable with this cycle, move on to :doc:`../part2-testing/index`.