The other undocumented workflow will be how the developer advocates for an update if they do not have an addons-source clone.
I’m not clear on how that would work. Heck, I don’t understand how the Pull Request system works when using the GitHub Clones.
Doing everything manually is too much burden on the volunteer wrangling addon developers and their contributions. And, as we found out in the last couple years, this volunteer position is crucial. It is a “single point of failure” in publishing add-ons and updates to them. Unfortunately, volunteers can become overloaded and disengage without anyone becoming aware.
We had a couple people step forwards to help out. But they seem to be waiting for a Volunteer Coordinator to get them started. Happily, Gary is proactive and jumped in to re-start add-on publishing. Just like he jumped in to fix the long-broken offline wiki manuals… then expanded the workflow to cover translations and Addons.
I only recently made an addons-source clone. Let me talk about my process before I cloned it. It was pretty simple if I am proposing a change to a gramplet that I am not the author.
First, I create a bug report with the issue. If I am not a developer, that is the end of my process.
If I am a developer and feel competent to fix, I edit the source of the gramplet in the local gramps52/plugin folder until I like the changes. I do it in this file because it is easier to iteratively test. At this point, I still dont have to know anything about git.
Lastly, I go online to github in my browser and edit the file in a new branch with the changes I used locally. I tend to cut/paste the whole file to be sure I capture all changes. Then Preview the changes to make sure that they are correct. I create a PR from this, referencing the bug number. At this point, I have to know how to create a PR in git, but I dont have to have anything installed on my local machine relative to git/github.
Not sure I follow. What manual burden are you referring? I add Comments to PRs when I have questions. This is pretty straightforward. If the author doesn’t answer, then I don’t take it further. Even if I think it is in the wrong branch (gramps51 instead of gramps52, for instance), I ask the author to rebase. Occasionally I will rebase it, but that is the exception, not the rule.
In my case, I decided to build a local version of gramps on my Mac, just to see if I could do it. Then added the addons-source and addons clones to see if I could make the build/listing on a Mac. Once that was successful, it was a natural next step to publish addons.
2 Likes
Yes. Creating a pull request is probably the best way to encourage an addon author/maintainer to look at your bug fix or enhancement. However it is really up to the individual maintainers to decide how they accept feedback.
1 Like
Thanks for sharing the workflow.
The normal workflow is addon contributors submitting Pull Requests via a gramps-project/addons-source clone on the GitHub domain or the GitHub Desktop app. Then an authorized contributor validating their Pull Request and committing the change.
The manual processes (for publishing a NEW addon) have several different approaches:
- submitting by eMail or Discourse Private Messaging
- requesting help publishing an addon from a GitHub repository (that isn’t in a cloned)
- code shared in an MantisBT issue
There is a thread with a sampling of plug-ins that are not yet published. So it would good to establish workflows that enable some approaches … without making it onerous (or error prone) for either the contributor or the volunteer.
Does this wiki cover the process? If not, how could it be improved/simplified to achieve your intent? Addons development - Gramps
This, like many of the development workflows (and the original Download Gramps) page suffers from being way, way too wordy. (Falls afoul of the TL;DR prejudice.) It may need to be a simple outline so that it is digestible and doesn’t suppress enthusiasm.
My beta testing Windows machine is slated to be repeated reset to factory and set up as a GitHub Contributor box. After doing that about 2 to 3 times per day for the next week, I should be able to slim down those workflows.
As tests, I’ll try to contribute ‘.gpr.py’ harmonizations (for core and add-ons) to confirm they are functional.
The beta test of a gramplet I’m editing was last published by Gary. Through a series of eMails/PMs, Gary made a plug-in available from my GitHub repository. (Not a clone of the addons-source.) I think that process put too much burden on him. His time could have been spent more profitably elsewhere than helping my lame ass.
1 Like
I have been (trying to) use the wiki for writing the HistContext gramplet.
It was nor easy, but a lot of it was helpful.
An example of issue is when @GaryGriffin states that you dont need to use git, until the final stages, and the wiki tells you to use the make script.
Another is that you should have a pylint score above xx, and if you try to run pylint on existing scripts, it is clear that noone has cared about that.
What I would like is a simple checklist, where each bullet is a link to how you actually do it.
I still have my process (relatively) clear in the back head, if you would like me to write it down.
3 Likes
Yes, please!
Also, I’m not able to find a reference to pylint on the page. Could you share the link where you ran into it?
1 Like
Fair point. Maybe if we separate different user cases, it will be more understandable.
Case 1: The developer wants a minimal-git approach. They can develop their gramplet and only need git to create the PR. This is for people who have no experience with git. They can use github website to create the PR and push their changes. They did not need to install git on their local machine.
Case 2: The developer has git experience and can create their own addons-source branch in git and work there. When ready, they can create the PR and push their changes.
Case 3: The developer wants to create their own install site for gramplets for testing (using the Gramps Addon Manager) and will then publish in the Gramps Addons repo for others to use.
Case 4: The developer wants to create their own install site for their gramplets (using the Gramps Addon Manager).
Cases 2, 3, and 4 have identical development cycles, with only a change in the publishing. Typically they will use either git CLI or GitHub Desktop to interact with github.
For Cases 3 and 4, the developer needs to create a complete gramps build environment locally (cloning gramps, addons-source, and addons repos), make sure all of the libraries are installed, building gramps locally, … This has a lot more setup work.
Personally, I think Cases 1 and 2 are the typical cases. Case 4 is for people who want to manage their gramplets completely. Case 3 is what @kmikkels did.
1 Like
Thanks, Kaj.
Regarding Programming guidelines - Gramps - it’s not clear whether all guidelines apply to both Gramps (core) and addons source. For example, the section on Black right before PyLlnt applies only to Gramps (core) CI. But in any case, I don’t believe that Gramps CI runs Pylint either, so this is a good question for the development team so I’m tagging @Nick-Hall:
Are the expectations stated on the wiki about Pylint still applicable for Gramps (core, and addons-source)? If yes, should it be incorporated into CI?
To Kaj’s experience about no one really paying attention to it, does it make sense to clarify on the wiki that “running Black (and/or Pylint) on your source is strongly encouraged for code hygiene. Only Black formatting is enforced in the Gramps repository.”
Agreed that needs correction. I’ve had tweaked modules rejected for PyLint failures. (Which were in the original code and I was unqualified to read, let alone fix. I was just submitting typo corrections in tooltips that were too trivial for a real developer.)
1 Like
I think you have some bright ideas. Not sure how to implement this, but perhaps a couple of user cases like “I did it this way”
1 Like
Thanks. It is comforting to know that I am not the only one looking at it as if it was greek - which I don’t understand a word of
1 Like
@kmikkels I updated Programming guidelines - Gramps to indicate that pylint score is not enforced by the CI system, and added a note about code hygiene in the best practices section.
Although I had Black formatter integrated in my IDE I did not have pylint, so I followed Linting Python in Visual Studio Code to set it up and now it’s really easy to see the diagnostics without any extra effort. I will be keeping an eye on pylint messages when I code for Gramps.
2 Likes
We ask developers to write PEP8 compliant code. Pylint is a useful tool and we set a target score of 9.0 or above. However, this is not an absolute requirement particularly for small files.
Consider the pylint reports as guidance and not a requirement. Use some common sense.
For example, short variable names are generally not descriptive and should be avoided, but when coding graphical output the use of variables x, y and z for co-ordinates is acceptable. There is no need to rename them x-coord, y-coord and z-coord or to disable pylint warnings just to get a higher score. In fact disabling pylint warnings is discouraged.
We give addon developers much more latitude. Any contribution that doesn’t write to the database will generally be accepted as long as it doesn’t contain malicious code. Addons that write to the database are required to make it clear to the user what changes they are making.
Of course we would encourage contributions to adhere to the same standards as our core code. This is good practice and makes possible migration of the addon into core code in the future easier.
1 Like
Amen! Updated wiki to remove the language that previously indicated that submissions would not be accepted if a score of 9.0 was not met.
1 Like
Is it viable to script Black to update the format for every .py file in addons-source? And in the built-in gramps/plugins? And also grade them all with pylint?
The Plugins are the obvious starting points for new developers. So starting with code that already has a low score has a chilling effect on their enthusiasm and undermines self-confidence.
I doubt anyone STARTS with testing the base code with Pylint or cleaning the format with Black. Although maybe that should be in the recommended workflow?
There two different tools:
- Pylint - this this a linter and code analysis tool. It gives a score based on rules. This is optional as we know from this thread, but use is encouraged.
- Black formatter this does not give a score. This has already been run on Gramps (core) code, including the builtins you linked. It is part of CI so it will flag PRs that don’t meet the standard, but may not catch direct commits to the repo.
I hope Nick doesn’t mind me paraphrasing a private message from him a while ago - he was considering running Black on the addons-source repository, but wanted to give it some thought.
1 Like
Is it worthwhile to run black on all the Addons when we initially move them to the future gramps53?