User:Ahs3/Maintainers

MAINTAINERS

If you are just writing an addon to contribute, this document adds some context to what comprises an addon package However, these are not tasks you will need to do. The tasks described here apply to the addons repository primarily, and not so much to the addons-source repository, even though they are tightly connected to one another.

We assume you are familiar with Gramps addons, git, github, and gh, the gh github CLI.

Linux Mostly These instructions and the make.py script have been built to operate in a Linux development environment. They will work on macOS with a few adjustments (see examples below). They have not been tested to see if they work on Windows.

PR Review and Approval

PR (Pull Request) submissions in the addons-source repository drive the maintenance tasks in addons. The only PR submissions to addons should be the ones you make as the maintainer.

PRs to addons-source need to be reviewed periodically. The goal is to make sure that useful changes don't end up sitting too long before being merged. Pay close attention to changes that could impact security and quality. Make sure that the PR is only changing what it must, and has been submitted against the proper branch. Then, comment on the PR if necessary, or merge it if ready, having allowed sufficient time for it to be reviewed.

PRs that continue for a long time as draft or WIP may need to be closed at some point, or the submitter pinged for progress reports. When to do this is a judgement call since not everyone works at the same speed, but it will also not be done without consulting the author.

All of the above can be done via the github web interface, or via the command line using the gh tool. For example, to see the current list of open PRs:

$ gh pr list

Showing 13 of 13 open pull requests in gramps-project/addons-source

ID    TITLE                          BRANCH                   CREATED AT        
#733  Translations update from H...  weblate:weblate-gram...  about 6 days ago
#668  Gram.py Refinements            dsb/grampy-refinements   about 2 months ago
#614  created GraphView italian ...  SebastianoPistore:gr...  about 7 months ago
#558  small fix to name all data...  loisspitz:translate_...  about 2 years ago
#540  fix: recast list to tuple ...  cdhorn:maintenance/g...  about 2 years ago
#522  [MediaReport] Allow all ou...  Mattkmmr:media-repor...  about 3 years ago
#477  [GraphView] rewrite theme ...  vantu5z:graphview_pe...  about 4 years ago
#473  Introduce the new Geneanet...  bcornec:master           about 4 years ago
#285  [MediaReport]: New image D...  Mattkmmr:update-medi...  about 5 years ago
#267  Form Gramplet: per Form, p...  stevenyoungs:form_ac...  about 5 years ago
#232  [GraphView] Add drag and d...  vantu5z:graphview_dr...  about 5 years ago
#214  GEPS045 update addons for ...  places                   about 5 years ago
#140  [Uncollected Objects]Updat...  leakv2                   about 7 years ago

Or, to view the details of a PR:

$ gh pr view 668
Gram.py Refinements gramps-project/addons-source#668
Draft • dsblank wants to merge 1 commit into maintenance/gramps60 from dsb/grampy-refinements • about 2 months ago
+27 -1 • No checks
Assignees: dsblank


  WIP:                                                                        
                                                                              
  Updating some items based on feedback from discourse.                       
                                                                              
  1. Be able to iter over NoneData                                            
  2. added references                                                         
  3. added back_references                                                    
  4. added back_references_recursively                                        


View this pull request on GitHub: https://github.com/gramps-project/addons-source/pull/668

At some point, there will be sufficient review and testing to merge the PR -- again, a judgement call will need to be made. It is this merge that triggers most tasks in the addons repository. For each addon modified by the merge, the package for it will need to be rebuilt and submitted as a PR to the addons repository.

Please go through this brief checklist before merging PRs into the maintenance branch in addons-source:

• Has the PR been reviewed enough?
• Have the changes in the PR been tested?
• Is the PR targeting the proper maintenance branch?
• Will the merge succeed (github does check this for you)?
• For new addons:
  • Have wiki pages been added describing it? If they have not, wait to do the merge until they have been.
  • Review the .gpr.py carefully:
    • Is it a good AddOn name and description?
    • Is it in the right tool, report, rule, view or gramplet category?
    • Has the help_url been changed from the github repository to the wiki page?
  • Does it need translatable strings marked?
  • Does it need a different location for config files?
• For changes to existing addons, do they clearly state what they fix or add? Have changes been made to the wiki pages to document that?
• If this is a bug fix, does the PR state which bug?
• Which addons have changed and will need to be repackaged?

Addons Repository Maintenance

The following are steps that only the addons repository maintainer needs to complete once an addon has been submitted via PR, and the PR has been approved, and the PR has been merged into a maintenance branch. If you are not managing this repository, you do not need to perform any of these steps.

Prerequisites

We recommend you use the make.py command found in the addons-source repository to do these tasks. To do so, the command makes several assumptions:

• You have a work space set up on your system with a directory structure that looks like the following, with addons-source being where the addon sources are maintained, and make.py is kept, and addons are where we will be adding in the packaged form of the addons.

   .../my-workspace
          /gramps              => clone of your fork of the current upstream maintenance branch
          /addons              => clone of your fork of the current upstream maintenance branch
          /addons-source       => clone of your fork of the current upstream maintenance branch

• Gramps requires Python 3.2 or higher be installed. If you have installed Gramps 4.2 or higher on your system already, then a sufficient version of Python should be present.
• The make.py used in construction of the addons requires that the LANGUAGE environment variable be set to en_US.UTF-8.
• The make.py used in construction of the addons requires that the GRAMPSPATH environment variable be set to your path to the Gramps source tree.
• intltool must be installed
  • for Debian-based systems: sudo apt-get install intltool
  • for Fedora-based systems: sudo dnf install intltool

For example, if your home directory is /home/user and you use the suggested path names, use:

GRAMPSPATH=/home/user/gramps LANGUAGE='en_US.UTF-8' python3 make.py ...

to replace the ./make.py in the examples below.

Multiple Python Versions Installed If you have more than one version of Python installed, you must use the correct version for these scripts. On some systems, both Python 2.x and 3.x are installed. It is possible that the normal invocation of python starts up Python 2.x, and that to start up Python 3.x requires invoking python3 or python3.4, etc. You can test the version by python -–version or python3 -–version. If the command python invokes Python 2.x, you will have to replace any usage of 'python' in the examples below with the appropriate invocation.

Basic Steps

In general, for each addon that a PR merge has changed, these are the basic steps needed:

1. Create (or update) translation information.
2. Create (or update) the addon manifest.
3. Create (or update) a tarball of the addon.
4. Create (or update) the listing information needed by the Gramps Addon Manager.
5. These steps will have created changes to the local addons repository. Commit them to the repository.
6. Push all the committed changes to your fork of the addons repository.
7. Create a PR for the commit just pushed to update the upstream tree.
8. Merge the PR to the upstream addons tree.

Commands to compile translations using make.py

You need the gramps.pot file that is currently being used for the Weblate translations in your local gramps 6.0 tree. It is used to exclude strings from the Addons translation component that have already been translated in the core Program component. This is:

https://github.com/gramps-project/gramps/blob/maintenance/gramps60/po/gramps.pot

Translation workflow with make.py:

1. Run the command init to add any new strings to the template.pot file.
2. The command aggregate-pot is run to aggregate all the addon template.pot files into a single po/addons.pot file which is then used by Weblate for translations. Note: The GRAMPSPATH environment variable must be set to a current gramps60 repository for this step. If run with no updates in any template.pot, the resulting addons.pot file will only have a timestamp update. In this case, it does not need merged back.

On macOS, the command looks like this:

 DYLD_LIBRARY_PATH=path_to_local_gramps_install python3 make.py gramps60 extract-po

The Weblate translators can now translate the strings. Weblate generates a pull request. This can be merged on a regular basis. You can do this from the GitHub GUI, but don’t squash the commits.

The local.po files (which were updated by Weblate) are updated for publishing using the extract-po command. These updates should be merged back to the gramps60 branch.

At this point, the translations are committed but not published. Since publishing updates every addon, the timing for this action is TBD.

Package your addon

To create a downloadable package:

./make.py gramps60 build NewProjectName or

./make.py gramps52 build NewProjectName for the older 5.2 branch.

List your addon in the Gramps Plugin Manager

Gramps needs to have been built Make sure you have already built gramps60 or master. Change to the appropriate git branch in your gramps directory, and run python3 setup.py build See Linux:Build_from_source

To create a listing:

cd '~/gramps-addons' or wherever you have built your addon

GRAMPSPATH=path/to/your/gramps/install ./make.py gramps60 listing NewProjectName

That will create a series of files in the ../listings/ directory.

Then commit the updated listing to GitHub:

 cd addons
 git add gramps60/listings/*
 git commit -m "Added new plugin to listings: NewProjectName"

Example addon article

Consider including the following information:

<!-- Copy this section to your Addon support page-->
{{Third-party plugin}}<!-- This is a mediawiki template that expands out to display the standard addon message you see at the top of each addon page-->

<!--sections only add if needed-->
== Usage ==

=== Configure Options ===

==Features==

== Prerequisites ==

== Issues ==

<!--default categories-->
[[Category:Addons]]
[[Category:Plugins]]
[[Category:Developers/General]]

Resources

• [Brief introduction to Git](https://gramps-project.org/wiki/index.php/Brief_introduction_to_git)
• [Getting started with Gramps development](https://gramps-project.org/wiki/index.php/Getting_started_with_Gramps_development)
• [Portal:Developers](https://gramps-project.org/wiki/index.php/Portal:Developers)
• [Registration module (Python source)](https://gramps-project.org/docs/gen/gen_plug.html?highlight=include_in_listing#module-gramps.gen.plug._pluginreg gramps.gen.plug._pluginreg)
• [PluginData in _pluginreg.py](https://github.com/gramps-project/gramps/blob/master/gramps/gen/plug/_pluginreg.py#L55)
• Gramps Addons site for Gramps 4.2 and newer

   * <https://github.com/gramps-project/addons-source>  - Source code (Git)
   * <https://github.com/gramps-project/addons> - downloadable .tgz files

• Gramps Addons site for Gramps 4.1 and older

   * For 4.1.x and earlier, see [Addons development old](https://gramps-project.org/wiki/index.php/Addons_development_old).

Addons External to Github

To Be Written.