~ser/forageproject

#forage

A shopping list front-end for your (self-hosted) Mealie v1 instance.

This project contains repositories for both the v0 Android app and v1 libraries and tools (for which there are several repositories). This document contains instructions mainly for working with the v1 repositories, as the project has been broken out to reduce coupling.

Releases remain in the same place.

#About the project, briefly

Mealie is self-hosted recipe manager, meal planner, and shopping list web app. Forage is an application aimed to improve the shopping list experience of Mealie by providing a native (non-web) interface via the Mealie API.

#Getting it

Forage v1 (for Mealie v0 - that's not at all confusing, is it?) is in F-Droid. apk releases are also on the releases server. You can also build it yourself by checking everything out; instructions for each version and variety of client is in the README of each client repository.

#About the project, longly

There is a public chat available at #forage:matrix.org.

The project consists of several independent applications:

forage (v1.x). This is a Fyne-based app, so it should work for multiple platforms, but it was built with Android in mind. This works with Mealie v0.x, and is not actively developed. Neither is Mealie v0.x, so there you go.
foragegui (v2.x). This is a Gioui-based app and should also work on multiple platforms but again is designed for mobile. This app works with Mealie v1.x instances, and is the supported mobile app.
foragecli. This is a CLI client that works against both v0.x and v1.x Mealie instances.
forageserver. This is a server application that exposes a Mealie v1.x API, or at least the shopping list parts. It's backed by a persistent store and could be used in place of a full Mealie instance, if all you wanted was a shopping list manager; however, it was built to be a dummy back-end for testing Forage clients against.
foragepush. Mealie's API is a polling API; it has no capability for pushing notifications to clients. This makes all Mealie clients polling clients. foragepush is a service that can be run that does the polling and pushes significant change notifications to clients. If a Forage client is configured against foragepush, then polling will be automatically disabled, battery will be saved, and everything will be rainbows and unicorns.

These tools use various libraries: foragelib_v1, foragelib, and foragedb. Not all clients use all libraries.

#The repositories

Forage v1.x is a self-contained project; nothing is separated.

Forage v2.x is broken out into separate projects: T/GUI clients, and libraries for Mealie APIs and local storage for caches. The best way to set this up is with Go workspaces. Briefly:

Create a workspace directory, e.g., mkdir forage-ws
Initialize it as a Go workspace, e.g. cd forage-ws && go work init
Check out the various repos & add them to the workspace with go work use <clone>. foragecli supports both v0 and v1, so two versions of foragelib need to be checked out and registered to build it:

hg clone -r v2.0.0 https://hg.sr.ht/~ser/foragelib  
go work use ./foragelib
hg clone -r v1.1.4 https://hg.sr.ht/~ser/foragelib foragelib_v1
go work use ./foragelib_v1
hg clone https://hg.sr.ht/~ser/foragecli
go work use ./foragecli

Build the client in which you're interested, e.g. cd foragecli && go build .

Here's a little video tutorial with all of the above steps, in case you like watching movies:

#Contributing

#Issues

There is a ticket tracker on the project site. Feel free to use that. However, I tend to store FIXMEs and TODOs in comments in the code. There are several tools out there that make working with these distributed, localized tickets easier, but I recommend legume. Because I wrote it. But it's not necessary, which is the beauty of inline ticket management.

#Sending contributions

With the monoculture of github, it may seem as if I've chosen all of the hardest tools that you've never used. However, contributing patches with Mercurial is super easy, and you don't have to deal with any web interfaces to create PRs or MRs or whatever.

The easiest way is to first enable the patchbomb extension, which is distributed with Mercurial. However, it's not necessary.

I don't require collapsing patches, but it makes it nicer for everyone. Assume your changes are in commits 500-506 (local IDs):

hg squash --from 500

Squashing commits that have children is harder, but not impossible -- you'll have to read the docs for that.

Once you've made your changes, send a patch set to the forage mailing list with a subject that looks like:

[PATCH foragegui] Add a thing to the bobber

#Via patchbomb

Assume you've squashed your commits down to rev 507, and you've enabled and configured patchbomb. You'd send it with:

hg email -r 507 -s "[PATCH foragegui] Add a thing to the bobber" -t ~ser/public-inbox@lists.sr.ht

#Via sendmail

It's almost as easy to just use sendmail (or similar, like msmtp):

{
  echo "From: you@email.com"
  echo "To: ~ser/public-inbox@lists.sr.ht"
  echo
  hg export -r 507
} | sendmail

I'll also accept bundles, which preserve copies, renames, and all that stuff diffs don't.

#Getting help

If all else fails, send an email to the mailing list (please start the subject with [FORGE]), or check the #forage:matrix.org chat room.

heads

clone