diff --git a/build-aux/debian/changelog b/build-aux/debian/changelog new file mode 100644 index 0000000..e98cf30 --- /dev/null +++ b/build-aux/debian/changelog @@ -0,0 +1,5 @@ +gknowledge (0.2.2-1) unstable; urgency=medium + + * Initial release. (Closes: #XXXXXX) + + -- Francesco Bianco Tue, 13 Oct 2026 14:00:00 +0000 diff --git a/build-aux/debian/control b/build-aux/debian/control new file mode 100644 index 0000000..322e644 --- /dev/null +++ b/build-aux/debian/control @@ -0,0 +1,33 @@ +Source: gknowledge +Section: utils +Maintainer: Francesco Bianco +Build-Depends: debhelper-compat (= 14), + dh-python, + python3, + python3-pypdf , +Standards-Version: 4.7.4 +Homepage: https://github.com/openapi/gknowledge +Vcs-Browser: https://github.com/openapi/gknowledge +Vcs-Git: https://github.com/openapi/gknowledge.git + +Package: gknowledge +Architecture: all +Depends: gir1.2-adw-1, + gir1.2-gtk-4.0, + python3-gi, + ${misc:Depends}, + ${python3:Depends}, +Recommends: python3-pypdf, +Description: native GNOME app that turns documents into a cited wiki + gknowledge collects documents, notes and links (Markdown, text, PDF, + HTML, EPUB) and turns them into a linked Markdown wiki in which every + page records its sources. Questions are answered from the wiki with + numbered citations that link back to the pages they came from. + . + The knowledge base is a plain folder of Markdown files with wikilinks + and front matter, so it can be opened in other editors or kept in git. + . + It works fully offline with a built-in heuristic engine. Optionally it + can use a local model through Ollama or LM Studio, any OpenAI-compatible + endpoint, or the user's own ChatGPT plan. The gknowledge-mcp command + exposes the wiki to MCP clients such as coding agents. diff --git a/build-aux/debian/copyright b/build-aux/debian/copyright new file mode 100644 index 0000000..39f6ca7 --- /dev/null +++ b/build-aux/debian/copyright @@ -0,0 +1,43 @@ +Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ +Upstream-Name: gknowledge +Upstream-Contact: https://github.com/openapi/gknowledge/issues +Source: https://github.com/openapi/gknowledge + +Files: * +Copyright: 2026 Openapi® +License: Expat + +Files: data/io.gknowledge.Gknowledge.metainfo.xml +Copyright: 2026 Openapi® +License: CC0-1.0 + +Files: debian/* +Copyright: 2026 Francesco Bianco +License: Expat + +License: Expat + Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated documentation files (the "Software"), to deal + in the Software without restriction, including without limitation the rights + to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + copies of the Software, and to permit persons to whom the Software is + furnished to do so, subject to the following conditions: + . + The above copyright notice and this permission notice shall be included in all + copies or substantial portions of the Software. + . + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE. + +License: CC0-1.0 + To the extent possible under law, the author(s) have dedicated all copyright + and related and neighboring rights to this software to the public domain + worldwide. This software is distributed without any warranty. + . + On Debian systems, the complete text of the CC0 1.0 Universal license can be + found in "/usr/share/common-licenses/CC0-1.0". diff --git a/build-aux/debian/docs b/build-aux/debian/docs new file mode 100644 index 0000000..b43bf86 --- /dev/null +++ b/build-aux/debian/docs @@ -0,0 +1 @@ +README.md diff --git a/build-aux/debian/gknowledge-mcp.1 b/build-aux/debian/gknowledge-mcp.1 new file mode 100644 index 0000000..79d0758 --- /dev/null +++ b/build-aux/debian/gknowledge-mcp.1 @@ -0,0 +1,34 @@ +.TH GKNOWLEDGE-MCP 1 "October 2026" "gknowledge 0.2.2" "User Commands" +.SH NAME +gknowledge-mcp \- Model Context Protocol server for a gknowledge wiki +.SH SYNOPSIS +.B gknowledge-mcp +.I PROJECT +.SH DESCRIPTION +.B gknowledge-mcp +lets Model Context Protocol clients, such as coding agents, use a +gknowledge project. It speaks JSON-RPC 2.0 over standard input and +output and offers the tools search_wiki, read_page, list_pages, ask, +add_source and recent_activity. +.PP +It is normally started by the MCP client, not by hand. +.SH ARGUMENTS +.TP +.I PROJECT +Path to a gknowledge project folder. +.SH ENVIRONMENT +.TP +.B GKNOWLEDGE_PROJECT +Project path, used when +.I PROJECT +is not given. +.SH EXAMPLES +Register the server with Claude Code: +.PP +.nf +.RS +claude mcp add gknowledge \-\- gknowledge\-mcp ~/Knowledge/my\-project +.RE +.fi +.SH SEE ALSO +.BR gknowledge (1) diff --git a/build-aux/debian/gknowledge.1 b/build-aux/debian/gknowledge.1 new file mode 100644 index 0000000..d2d77bc --- /dev/null +++ b/build-aux/debian/gknowledge.1 @@ -0,0 +1,31 @@ +.TH GKNOWLEDGE 1 "October 2026" "gknowledge 0.2.2" "User Commands" +.SH NAME +gknowledge \- native GNOME app that turns documents into a cited wiki +.SH SYNOPSIS +.B gknowledge +[\fIGTK-OPTIONS\fR] +.SH DESCRIPTION +.B gknowledge +collects documents, notes and links and turns them into a linked +Markdown wiki in which every page records its sources. Questions are +answered from the wiki with numbered citations. +.PP +A project is a plain folder of Markdown files with wikilinks and front +matter, plus an SQLite index. It can be opened in other Markdown editors +or kept under version control. +.PP +The app works offline with a built-in engine. A model provider (Ollama, +LM Studio, any OpenAI-compatible endpoint, or a ChatGPT plan) can be +chosen in Preferences. +.SH OPTIONS +Standard GTK and GApplication options are accepted, for example +.BR \-\-help . +.SH FILES +.TP +.I $XDG_CONFIG_HOME/gknowledge/ +Recent projects and provider settings (defaults to +.IR ~/.config/gknowledge/ ). +.SH SEE ALSO +.BR gknowledge\-mcp (1) +.PP +https://github.com/openapi/gknowledge diff --git a/build-aux/debian/gknowledge.manpages b/build-aux/debian/gknowledge.manpages new file mode 100644 index 0000000..e0b7653 --- /dev/null +++ b/build-aux/debian/gknowledge.manpages @@ -0,0 +1,2 @@ +debian/gknowledge.1 +debian/gknowledge-mcp.1 diff --git a/build-aux/debian/rules b/build-aux/debian/rules new file mode 100755 index 0000000..decfee9 --- /dev/null +++ b/build-aux/debian/rules @@ -0,0 +1,20 @@ +#!/usr/bin/make -f + +%: + dh $@ --with python3 + +# The upstream Makefile has no build step; its default target only prints help. +override_dh_auto_build: + +override_dh_auto_install: + $(MAKE) install DESTDIR=$(CURDIR)/debian/gknowledge PREFIX=/usr PYTHON=/usr/bin/python3 + find debian/gknowledge -name __pycache__ -type d -prune -exec rm -rf {} + + +override_dh_auto_test: +ifeq (,$(filter nocheck,$(DEB_BUILD_OPTIONS))) + python3 tests/test_core.py +endif + +# The package lives in a private directory, not in dist-packages. +override_dh_python3: + dh_python3 /usr/share/gknowledge diff --git a/build-aux/debian/source/format b/build-aux/debian/source/format new file mode 100644 index 0000000..163aaf8 --- /dev/null +++ b/build-aux/debian/source/format @@ -0,0 +1 @@ +3.0 (quilt) diff --git a/build-aux/debian/upstream/metadata b/build-aux/debian/upstream/metadata new file mode 100644 index 0000000..e0a5b53 --- /dev/null +++ b/build-aux/debian/upstream/metadata @@ -0,0 +1,4 @@ +Bug-Database: https://github.com/openapi/gknowledge/issues +Bug-Submit: https://github.com/openapi/gknowledge/issues/new +Repository: https://github.com/openapi/gknowledge.git +Repository-Browse: https://github.com/openapi/gknowledge diff --git a/build-aux/debian/watch b/build-aux/debian/watch new file mode 100644 index 0000000..b4a5c9d --- /dev/null +++ b/build-aux/debian/watch @@ -0,0 +1,4 @@ +version=4 +opts="filenamemangle=s%(?:.*?)?v?(\d[\d.]*)\.tar\.gz%gknowledge-$1.tar.gz%" \ + https://github.com/openapi/gknowledge/tags \ + (?:.*?/)?v?(\d[\d.]*)\.tar\.gz diff --git a/docs/packaging/debian.md b/docs/packaging/debian.md new file mode 100644 index 0000000..f214e05 --- /dev/null +++ b/docs/packaging/debian.md @@ -0,0 +1,92 @@ +# Getting gknowledge into Debian and Ubuntu + +The goal is `sudo apt install gknowledge` on stock Debian and Ubuntu. Ubuntu imports new packages from Debian unstable automatically, so a package accepted in Debian lands in Ubuntu **universe** at the next sync. This is the route other GTK Python apps have taken: Apostrophe, for example, is maintained by the Debian GNOME team and reaches Ubuntu the same way. + +The source packaging lives in [`build-aux/debian/`](../../build-aux/debian). It is the `debian/` directory to copy into a packaging repository on Salsa (Debian's GitLab); it is not used by our own `.deb` script. + +## Build and check it locally + +```sh +git archive --format=tar.gz --prefix=gknowledge-0.2.2/ v0.2.2 > ../gknowledge_0.2.2.orig.tar.gz +tar -C .. -xzf ../gknowledge_0.2.2.orig.tar.gz +cp -r build-aux/debian ../gknowledge-0.2.2/debian +cd ../gknowledge-0.2.2 && dpkg-buildpackage -us -uc +lintian -I --pedantic ../gknowledge_0.2.2-1_*.changes +``` + +On a host without debhelper, run the same steps in a `debian:sid` container with `build-essential devscripts debhelper dh-python python3 python3-pypdf lintian` installed. + +Last checked on 2026-10-13 in `debian:sid`: builds, the core tests run during the build and pass, the package installs and the GTK 4 and Libadwaita modules import. Lintian only reports the placeholder ITP bug number, which is filled in after step 1, and informational notes. + +## Steps + +1. **File the ITP** (Intent To Package) against the `wnpp` pseudo-package, with the text below. Use `reportbug wnpp` or email `submit@bugs.debian.org`. The bug number replaces `#XXXXXX` in `debian/changelog`. +2. **Ask the Debian GNOME team** whether they will co-maintain it (message below). If they accept, `Maintainer:` becomes `Debian GNOME Maintainers ` and we go in `Uploaders:`, and the repository moves under `salsa.debian.org/gnome-team/`. +3. **Find a sponsor.** Uploading to Debian needs a Debian Developer. Upload the source package to [mentors.debian.net](https://mentors.debian.net) and file an RFS (Request For Sponsorship) bug against `sponsorship-requests`, or ask the GNOME team directly. +4. **Wait for NEW.** New packages go through the ftp-masters' NEW queue, which typically takes days to weeks. +5. **Ubuntu.** Once in unstable, the package syncs into the current Ubuntu development release automatically. Older Ubuntu releases keep using our `.deb` or the Snap. + +Each new upstream release then needs a new `debian/changelog` entry and an upload; `debian/watch` lets `uscan` find new tags. + +## ITP text + +``` +Subject: ITP: gknowledge -- native GNOME app that turns documents into a cited wiki +Package: wnpp +Severity: wishlist +Owner: Francesco Bianco +X-Debbugs-Cc: debian-devel@lists.debian.org, debian-gtk-gnome@lists.debian.org + +* Package name : gknowledge + Version : 0.2.2 + Upstream Contact: https://github.com/openapi/gknowledge/issues +* URL : https://github.com/openapi/gknowledge +* License : Expat (code), CC0-1.0 (AppStream metadata) + Programming Lang: Python + Description : native GNOME app that turns documents into a cited wiki + +gknowledge collects documents, notes and links (Markdown, text, PDF, +HTML, EPUB) and turns them into a linked Markdown wiki in which every +page records its sources. Questions are answered from the wiki with +numbered citations. It works fully offline with a built-in engine and +can optionally use a local model (Ollama, LM Studio), any +OpenAI-compatible endpoint, or the user's own ChatGPT plan. It also +ships an MCP server so coding agents can use the same wiki. + +It is a GTK 4 / Libadwaita app with no dependencies outside the archive +(python3-gi, gir1.2-gtk-4.0, gir1.2-adw-1, optionally python3-pypdf). +Similar apps in Debian are general note editors such as Apostrophe; +none builds a cited knowledge base from source documents. + +I am upstream and will maintain the package, ideally within the Debian +GNOME team. Packaging is ready and lintian-clean apart from this bug +number: https://github.com/openapi/gknowledge/tree/main/build-aux/debian +I need a sponsor. +``` + +## Message to the Debian GNOME team + +To: `debian-gtk-gnome@lists.debian.org` + +``` +Subject: Team maintenance for gknowledge (GTK 4/Libadwaita, ITP #XXXXXX) + +Hello, + +I'm the upstream developer of gknowledge, a GTK 4 and Libadwaita app +written in Python that turns documents into a linked Markdown wiki with +sources and cited answers. It works offline and only depends on +python3-gi, gir1.2-gtk-4.0 and gir1.2-adw-1 (python3-pypdf optional). + +I've filed ITP #XXXXXX and prepared the packaging (debhelper 14, +dh-python, private module directory, man pages, lintian-clean apart +from the ITP number): +https://github.com/openapi/gknowledge/tree/main/build-aux/debian + +Would the team be willing to host it on Salsa under gnome-team, with me +as an uploader, and could someone sponsor the first upload? I'm happy +to follow the team's packaging conventions and to take care of updates. + +Thanks, +Francesco Bianco +```