Lekcja 7. Publikowanie Dodatku: Od Folderu do GitHub i Menedżera Dodatków – Code 1001

Cel Lekcji: Przygotowanie dodatku do dystrybucji, stworzenie metadanych i opublikowanie go na GitHub, aby każdy użytkownik FreeCAD mógł go zainstalować jednym kliknięciem.

Część 1. Czym jest Menedżer Dodatków?

Menedżer Dodatków ($\text{Tools} \to \text{Addon Manager}$) to wbudowane narzędzie FreeCAD, które:

• Pokazuje katalog ponad 300 oficjalnych dodatków.
• Pozwala instalować, aktualizować i usuwać dodatki bez ręcznego kopiowania plików.
• Współpracuje z repozytoriami GitHub.

Aby Twój dodatek się tam pojawił, musisz:

1. Przesłać go na GitHub.
2. Dodać plik $\text{package.xml}$.
3. (Opcjonalnie) Wysłać $\text{PR}$ (Pull Request) do $\text{FreeCAD-addons}$.

---

Część 2. Przygotowanie Struktury Repozytorium

Twój folder powinien wyglądać następująco:

BoxBuilderAddon/  <-- katalog główny repozytorium
├── Resources/
│   └── icons/
│       ├── box_builder.svg
│       └── create_box.svg
├── InitGui.py
├── box_builder_workbench.py
├── package.xml    <-- WYMAGANE!
├── README.md      <-- zalecane
└── LICENSE        <-- wymagane do publikacji

Ważne: Nazwa folderu głównego musi być zgodna z nazwą dodatku i taka sama jak w $\text{InitGui.py}$.

---

Część 3. Tworzenie package.xml

Ten plik opisuje Twój dodatek dla Menedżera Dodatków. Utwórz plik $\text{package.xml}$ w katalogu głównym:

XML

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<package format="1"
         xmlns="https://wiki.freecad.org/Package_Metadata">
    <name>BoxBuilderAddon</name>
    <description>
        A simple tool to create parametric boxes with custom dimensions
        and GUI. Saves last used values between sessions.
    </description>
    <version>1.0.0</version>
    <date>2025-04-05</date>
    <maintainer email="your.email@example.com">Your Name</maintainer>
    <license file="LICENSE">LGPL-2.1-or-later</license>
    <url type="repository"
         branch="main">https://github.com/yourname/BoxBuilderAddon</url>
    <url type="bugtracker">https://github.com/yourname/BoxBuilderAddon/issues</url>
    <icon>Resources/icons/box_builder.svg</icon>
    <content>
        <workbench>BoxBuilderAddon</workbench>
    </content>
    <dependencies>
        <freecad>0.20</freecad>
    </dependencies>
</package>

Wymagane pola:

• <name> musi być zgodne z nazwą folderu.
• <version> w formacie $\text{X.Y.Z}$.
• <license> określa plik $\text{LICENSE}$ i typ licencji.
• <url type="repository"> – link do Twojego GitHub.
• <icon> ścieżka do ikony (względem katalogu głównego).
• <content><workbench>...</workbench></content> wskazuje, że jest to środowisko pracy ($\text{workbench}$).

Licencja jest obowiązkowa. Zalecana jest $\text{LGPL-2.1-or-later}$ (jak sam FreeCAD).

---

Część 4. Plik LICENSE

Utwórz plik $\text{LICENSE}$ z tekstem licencji.

Przykład dla LGPL-2.1:

1. Przejdź do: https://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt.
2. Skopiuj cały tekst.
3. Wklej go do pliku $\text{LICENSE}$.

Możesz też użyć GitHub: podczas tworzenia repozytorium możesz automatycznie wybrać licencję.

---

Część 5. Plik README.md

Stwórz prosty plik $\text{README.md}$:

Markdown

# Box Builder Addon for FreeCAD

A simple tool to create parametric boxes with custom dimensions.

## Features
* GUI dialog for entering length, width, height
* Saves last used values between sessions
* Unique object naming
* Optional centering on origin

## Installation
1. Open FreeCAD
2. Go to <strong>**Tools → Addon Manager**</strong>
3. Search for "BoxBuilderAddon"
4. Click <strong>**Install**</strong>

Or install manually by copying the folder to your Mod directory.

## Requirements
* FreeCAD 0.20 or newer

---

Część 6. Publikowanie na GitHub

Kroki:

1. Zarejestruj się na GitHub.
2. Kliknij New repository.
3. Nazwa: $\text{BoxBuilderAddon}$.
4. Zainicjuj bez $\text{README}$ (już go utworzyłeś).
5. Kliknij Create repository.
6. Postępuj zgodnie z instrukcjami, aby przesłać swój lokalny folder:

Bash

git init
git add .
git commit -m "Initial release"
git branch -M main
git remote add origin https://github.com/yourname/BoxBuilderAddon.git
git push -u origin main

Zastąp yourname swoją nazwą użytkownika GitHub.

---

Część 7. Testowanie Instalacji

Teraz każdy użytkownik może:

1. Otworzyć FreeCAD.
2. Przejść do $\text{Tools} \to \text{Addon Manager}$.
3. Kliknąć $\text{Check for updates}$.
4. Znaleźć $\text{BoxBuilderAddon}$ i kliknąć $\text{Install}$.

Aby dodatek pojawił się na oficjalnej liście, musisz przesłać Pull Request do: https://github.com/FreeCAD/FreeCAD-addons.

Nawet bez tego, użytkownicy mogą go zainstalować za pomocą bezpośredniego linku:

• W Menedżerze Dodatków: $\text{Tools} \to \text{Addon Manager} \to \dots \to \text{Install custom addon}$
• Wklej URL: $\text{[https://github.com/yourname/BoxBuilderAddon](https://github.com/yourname/BoxBuilderAddon)}$

---

Zadanie Praktyczne

1. Załóż konto GitHub (jeśli go nie masz).
2. Przygotuj pełną strukturę dodatku z $\text{package.xml}$, $\text{LICENSE}$, $\text{README.md}$.
3. Prześlij repozytorium na GitHub.
4. Zainstaluj swój dodatek za pośrednictwem Menedżera Dodatków na czystej kopii FreeCAD (lub usuń folder z $\text{Mod}$ przed instalacją).

---

Podsumowanie

Teraz wiesz, jak:

• Tworzyć pełnoprawne dodatki z GUI i ustawieniami.
• Dodawać ikony.
• Przygotować metadane.
• Publikować na GitHub.
• Udostępnić swój dodatek światu.

---

Co dalej?

Ukończyłeś cały kurs! Jesteś teraz programistą dodatków do FreeCAD.

Możliwe kolejne kroki:

• Dodanie obsługi centrowania (z zadania z Lekcji 5).
• Implementacja wielokrotnego wprowadzania (tworzenie siatki prostopadłościanów).
• Integracja z $\text{PartDesign}$ w celu tworzenia brył obrotowych.
• Napisanie dodatku dla własnego zadania: śruby, ramy, obliczenia itp..