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 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)?
• If this is a new addon, have wiki pages been added describing it? If they have not, wait to do the merge until they have been.
• 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.

Files included in addon distribution

The process to make the download compressed tar file automatically includes the following files:

   *.py
   *.glade
   *.xml
   *.txt
   locale/*/LC_MESSAGES/*.mo

Starting with Gramp 5.0, if you have additional files beyond those listed above, you should create a MANIFEST file in the root of your addon folder listing the files (or pattern) one per line, like this sample MANIFEST file:

README.md extra_dir/* help_files/docs/help.html

Addons should not be created on the master branch.

Note: Running the command make.py xxx build will increment the third number in your dotted version number of all addons in the *.gpr.py file. Consider this number to be a "build number".

This will leave your 'addons-source' with untracked changes according to git. The updated 'NewProjectName/NewProjectName.gpr.py ' is ready to add and commit.

Commit the updated gpr.py

 cd addons-source
 git add gramps60/download/NewProjectName.gpr.py
 git commit -m "Updated new plugin gpr: NewProjectName"

Commit the updated compressed tar file:

 cd ../addons
 git add gramps60/download/NewProjectName.addon.tgz
 git commit -m "Added new plugin: NewProjectName"

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"

List and document your addon on the wiki

List your addon

Add a short description of your addon to the Addons list by editing the current release listing eg: 6.0_Addons or if the addon is meant for a future release 6.1_Addons when available.

Example addon template

Examine the listing for other addons and refer to the Addon list legend for details of on the meaning of each columns.

|- <!-- Copy this section and list your Addon -->
|<!-- Plugin / Documentation -->
|<!-- Type -->
|<!-- Image -->
|<!-- Description -->
|<!-- Use -->
|<!-- Rating (out of 4) -->
|<!-- Contact -->
|<!-- Download -->
|-

Document your addon

Document the addon in the wiki using the page name format of Addon:NewProjectName examine the other addon support pages for the general format to use.

Hint on creating a new wiki page. To create a new wiki page use the search box to search for the name of your page that doesn't exist then on the search results page you will be provided with a link to create the new page, by selecting and you can add your content

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]]

Announce the addon

Join the Gramps Forum and announce it to the users with general information on why you created and how to use it.

Support it through issue tracker

Become a user on the Gramps MantisBT (Mantis BugTracker). and please check it regularly. There is no automated notification of issues (and possible feature requests) related to your addon when reported by users.

Users tend to not understand coding and they make assumptions. So be kind and guiding if a report is ambiguous or inaccurate. A negative remark from an addon developer or anyone can be very discouraging.

Maintain the code as Gramps continues to evolve

When submitting an update the patch part of the version number MAJOR.MINOR.PATCH is updated during the addon build process e.g. 1.1.3 to 1.1.4 You can find this step in addons-source/make.py.[1]

Remember that Gramps addons exist for many reasons and there are many Gramps developers that do support addons in various ways (translations, triage, keeping in sync with master, download infrastructure, etc).

Some reasons why the addons exist; they provide:

• A quick way for anyone to share their work; the Gramps-project has never denied adding a addon.
• A method to continuously update and develop a stand-alone component, often before being officially accepted.
• A place for controversial plugins that will never be accepted into core, but are loved by many users (eg, Data Entry Gramplet).
• A place for experimental components to live.

1. 1. Example code adding common enhancements

• Copy all the Gramplet's output to a system clipboard via context pop-up menu : Enhancement request 11573, example pull
• add a custom View Mode toolbar icon via the .gpr.py : Pull 1017 Discussion, example Pull

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).

Addon Development Tutorials and Samples

• [Develop an Addon Gramplet](https://gramps-project.org/wiki/index.php/Gramplets_development) (or add a [custom filtering option](https://gramps.discourse.group/t/looking-for-an-example-of-a-gramplet-with-a-custom-filter-configuration-option/5967))
• [Develop_an_Addon_Rule](https://gramps-project.org/wiki/index.php/Develop_an_Addon_Rule) for custom filters
• [Develop_an_Addon_Tool](https://gramps-project.org/wiki/index.php/Develop_an_Addon_Tool)
• [Develop an Addon Quick_View](https://gramps-project.org/wiki/index.php/Quick_Views)
• Develop an Addon Report ([tutorial](https://gramps-project.org/wiki/index.php/Report-writing_tutorial),

[samples](https://gramps.discourse.group/t/sample-report-for-new-developers/3046))

• [Adapt_a_builtin_Report](https://gramps-project.org/wiki/index.php/Adapt_a_builtin_Report)

Addons External to Github

To Be Written.