Do we have a good document to introduce Aunt Martha to patching their Gramps installation?
The topic has come up before, both in an overly ambitious thread by me and in a basic inquiry by others. But here (in french, followed by a translation) is what is driving this new thread:
Non, c’est plus que cela.
Gramps fonctionne à partir du code source. Ainsi, si un développeur corrige la branche “Maître”, vous pouvez remplacer les mêmes “fichiers modifiés” sur votre machine et bénéficier des nouvelles fonctionnalités.
Tu dois être très prudent. Et soyez prêt à inverser les changements. Il est préférable que vous puissiez utiliser les correctifs qui ont été appliqués à la branche “maintenance” pour la version que vous avez installée.
Mais c’est une compétence qui mérite d’être apprise.
Parce que lorsqu’un développeur crée un correctif, vous pouvez le tester et donner votre avis pendant qu’il est encore familier avec le problème. Cela peut prendre des années si vous attendez une nouvelle version. D’ici là, ils auront oublié.
Translation:
I suppose a “Patch” is an addition of code to add functionality. For those that you have developed, will they be integrated into a new version of Graphview? Just to know ?
No, it’s more than that.
Gramps works from source code. So, if a developer fixes the “Master” branch, you can replace the same “modified files” on your machine and benefit from the new features.
You have to be very careful. And be prepared to reverse the changes. It is best if you can use the fixes that have been applied to the “maintenance” branch for the version you have installed.
But it’s a skill worth learning.
Because when a developer creates a fix, you can test it and provide feedback while they are still familiar with the issue. It can take years if you wait for a new version. By then, they will have forgotten.
What is needed is a core document explaining both the data architecture and the structure of the application, notably data flow between the plugins (because every function is Gramps is a plugin). This design decision is very interesting in that it allows extension without needing general redesign of the application.
Data architecture is abstracted by the Python object system. But it still strongly smells its initial design with BSDDB which prevents neat usage of today DB engines. And this architecture is too monolithic: to “simplify” genealogical data handling, an object contains all related data. I’d prefer sub-components not being agglutinated in the primary object so that updates are more independent from each other (and this would allow an easir use of today DB engines), though roll-backs could become more difficult.
Application structure is difficult to understand. There are too many object derivations from the primary types before you reach the genealogical representations. The useful methods are not obvious. IMHO there is a flaw in object definition but Gramps is not the culprit. This comes from Python where object inheritance is a mix between true object derivation and grouping of several struct sub-parts. This forces to use dirty twists in many circumstances, e.g. when initialising objects.
And I feel that some “core” functions have been implemented several times by different persons with slightly different APIs.
Also, architecture is too close to GTK+. I understand this simplified initial design where Don only had to focus on genealogy not on GUI but it now creates problems because control flow is not independent enough from the GUI. You must coerce some features into GTK+ primitives to implement them (I met this problem when I implemented custom presets for my reports).
So, such a guidance document is welcome but writing it from the code requires to master Gramps internals. It has grown so much that the task is difficult. Who has such a knowledge?
We could target two documents: one for already enlightened users who want to customise their installation and another much more comprehensive one for those not afraid of diving into the code. The latter one can (must?) be more technical and address the most “mysterious” aspects of control flow, because use of “signals” hides the relationship between blocks of codes in different modules/directories. It works very fine but makes difficult to predict why some function in a remote directory suddenly triggers to life.
The former document can be more lightweight if it targets only “local installation”: where to store add-ons, how to “protect” and backup the DBs independently from Gramps, what to do when swapping computer or fully reinitialising it, what is “installation-wide” and “family tree-only”, …
Here’s a Perplexity composed description (after several revisions and tweaking):
To patch the Gramps application on a desktop system using the changed module from a pull request for the Master branch of the Gramps application in the GitHub repository at https://github.com/gramps-project/gramps, follow these steps:
Locate the Gramps Core Modules: The core modules of the Gramps application can be found in the installation directory of Gramps on your desktop system.
Access the Pull Request: Go to the specific pull request mentioned by the volunteer developer on the Gramps GitHub repository. The Conversation tab will help you understand the changes proposed by the developer. The Files Changed tab will list the affected modules.
Download the Changed Module: From the pull request, identify the specific core module that has been modified. Download the changed module by clicking on it and then selecting “Raw” to view the raw code. Save this code to a new file on your local machine.
Quit the Gramps Application: If the Gramps application is running, quit the application to ensure that the core modules are not in use.
Rename the Local Module and Delete pycache: Navigate to the subdirectory where the original core module is located on your operating system. Rename the original module by appending the current date (YYYYMMDD) to its name to create a backup. Additionally, if there is a __pycache__ folder in the directory, delete it to ensure that the cache is cleared.
Copy the Downloaded Module to the Local Machine: Copy the file containing the changed code that you downloaded from the pull request to the directory where the original core module is located on your system.
Start the Gramps Application Again: After completing the replacement of the module, start the Gramps application again to ensure that it functions correctly with the patched core module.
Testing and Validation: After starting the Gramps application, test the functionality that relies on this module to ensure that the patch works as intended.
Security and Best Practices: Consider security best practices when applying patches to system components. Verify the source of the patch and understand its implications.
These steps allow you to patch your Gramps desktop application by replacing the original core module with the changed module from the pull request, while also preserving a backup of the original module and ensuring a clean cache.
Good points have been made about the complexity of such a document, and the benefit as well. It would be good to have the steps documented for sure.
Taking a step back and thinking about what’s driving this, I wonder if patching should be necessary for everyday Gramps users at all? Could we consider an alternate world in which addons and Gramps itself are update and released more frequently?
There’s always going to be a need for beta testers. While we’re undoubtedly going to fall short of boosting Aunt Martha into becoming a hacker, it’s a good documentation target for which to aim.
Or how about a way for users to “build from source” remotely, meaning that some automated process on a server somewhere creates a fresh install file on demand, rather than users having to download the latest source files and build it themselves?
Gramps is written in Python and there is nothing like compiling, linking and installing with Python. You just load the full source tree in some directory of yours and that’s it.
The only point to care for is the internal Gramps directory to avoid messing up your “production” data. You can either change the location with the command line or modify the value of “constant variable” HOME_DIR in gramps/const.py. It is initially set to .gramps in the user home directory. Use a different location to avoid corrupting your databases and profile.
Yes, I understand that, but that’s not what I meant. In that case, Aunt Martha would still have to install all of the necessary prerequisites.
Rather, I was asking whether there could be a way that she could trigger the creation of a new Windows AIO or Mac dmg install (or even a deb file, though I doubt she’s running Linux) containing the latest code (beyond the last official maintenance release).
But the more I think about this, it doesn’t seem like a good idea – it would make it harder to support any issues that are raised.
Also, I suspect Aunt Martha is not actually the one who is clamoring for more frequent releases.
One is not enough for this! So… (There are a couple flutters in there.)
But weekly would probably overwhelm. A Quarterly build would probably be as frequently as people could digest. Even that might even be too much. I know wikicontributors could not keep up at that rate of release. And we might lose PortableApps… although the sudden supersaturation of adverts on their service makes you wonder where they are headed.
Then there’s generating the Flatpaks (or .deb ) and .dmg files for Intel and Silicon. The Linux distros might decide redoing the work every 3 months is too big of an investment.
Building a Windows AIO based on the master branch would not be an official release. Using it would be for the adventurous only subject to the usual warnings.
AIO build process is so much easier now which is amazing! Can we do that with addons as well?
The rest of this reply is not directed only at Nick’s response, but to all the excellent points raised by everyone in this thread.
The question we should ask ourselves is, how many versions of Gramps are we, as maintainers, willing to support? And customized installs increase risk of data corruption which can erode trust in the software. Are we ready to receive and triage bug reports against weekly builds or customized installations of Gramps?
If the answer is no, then we should focus our limited contributor resources on official releases for all platforms at the same time, not just the AIO build.
Still, no question about the usefulness of a wiki describing how to build and test with code from from PRs. Let’s consider what Aunt Martha really needs - would she be happier getting a build she could upgrade to, or a document that tells her how to customize and then remembering to undo/carry-over that change with the next official release?
So, realistically, what would it take to increase cadence for minor Gramps releases with bug fixes and perhaps smaller enhancements? As for a master build, could we consider having a bleeding edge build generated, say every quarter for those who wish to test and give feedback on the latest developments? As Nick suggested, but make it official…
I just want to leave here that if you want any chance of Gramps users, that arent quite above average interested in computers/software to test some version of Gramps, it Must be very easy to install/get. An many step guide, on video or text, just wont do it. Being a big fan of using gramps itself isnt enough on its own.
(I average is general population, I dont know what the average of Gramps users.)
There is probably a direct correlation between how easy it is to install a beta version, and how many is willing to test it, tho, there is probably some factor of the less interested/skills in tech/software you have, the less likely you are to to beta test.
So the correct priority to increase number of beta testers would be to make it easier to do, not making a guide for something that arent that easy.
In the 1980s schooling, I was was taught that US newspaper jounalists and technical writers should target the 5th grade reading level. This was for 2 reasons:
news comes in high volume and technical information is hard enough to absorb. They should not be made more complex because of jargon or complex writing styles.
At that time, a significant portion of the elders had suffered through the Depression or WWII and may have had to drop-out of school to join the workforce. (Secondary schooling … 6th through 12th grades… was not even compulsory in the US until WWI.)
So I try to extend that philosophy into other areas.
Beta testing is hard enough that it would be better if setting up a test system didn’t make things harder.
As an “average non techy user” I would be willing to wait for a release every 6 months. That time period should also limit the number of changes that would keep the pre-release testing simple.
is not enough for this! So…