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, and github.

Linux Only These instructions and the make.py script have been built to operate in a Linux development environment. They will not work on Windows or macOS without modifications.

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 mark it reviewed, and add any labels that may be of use (Translations and Work-In-Progress (WIP) are often useful).

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.

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 Management

There are steps that only the ```addons``` repository manager needs to complete once an addon has been submitted via PR (Pull Request),

• • and** the PR has been approved. If you are not managing this repository,

you do not need to do any of these steps.

Prerequisites

• Gramps uses Python version 3.2 or higher. You must have at least that version installed. If you have installed Gramps 4.2 or higher on your Linux system already, then a sufficient version of Python will be present. If you have more than one version of Python installed, then 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 with python3 or python3.4 etc. You can test the version by python –version or python3 –version. If this is so, replace any usage of 'python' in the examples below with the appropriate invocation.
• 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;

sudo apt-get install intltool

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

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

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

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.