Policy on wrapping new GMT modules step by step from initial implementation to gallery example

[weiji14]

Description of the desired feature

Wrapping a new GMT module in PyGMT is usually a big task (as we've learned the hard way from #804), so it's better on both the contributor and reviewer(s) if small, manageable chunks are done (as per https://github.com/GenericMappingTools/pygmt/blob/v0.5.0/doc/contributing.md#general-guidelines-for-making-a-pull-request-pr).

This step-by-step process seems to have worked well for @willschlitzer and others in the past few months, and for the sake of new contributors, we should probably 1) document the step-by-step policy and 2) track the status of each GMT module being wrapped.

Documenting how new GMT modules should be wrapped

Easiest way would be to modify the 'Reminders' in the Pull Request template at https://github.com/GenericMappingTools/pygmt/blame/v0.5.0/.github/PULL_REQUEST_TEMPLATE.md#L11-L17. Specifically, the - [ ] If adding new functionality, add an example to docstrings or tutorials. line should be made optional or something.

Other than that, we could put a note in https://github.com/GenericMappingTools/pygmt/blob/v0.5.0/doc/contributing.md that these are the general stages on wrapping a GMT module:

0. Wishlist
1. 'Wrapper for XXX' feature request issue
2. 'Wrap XXX' initial feature implementation PR
3. 'Add missing aliases to XXX' documentation PR / 'Support some functionality in XXX' enhancement PR
4. 'Add gallery example for XXX' documentation PR
5. 'Add tutorial for XXX' documentation PR (optional)

Note that step 3 and 4 can be done in parallel in some cases.

Tracking the status (feature completeness) of a PyGMT module

Ideally we would have an issue to track a PyGMT module from its initial implementation to the final gallery example/tutorial, but that's a bit of a hassle. So let's track it using cards instead. See https://github.com/GenericMappingTools/pygmt/projects/9

If any of you have a new wishlist item, or find an incomplete module that's not added, please add it to the project board!

Originally posted by @weiji14 in #1072 (comment)

Just on this point (and as I've mentioned to Jiayuan at #1145 (review)), I'd recommend wrapping as few aliases as you can get away with in this PR. We can open up separate PRs to wrap any complicated parameter like inquire=I, or transparency=t, and the gallery example/tutorial can be left for another day too.

To be clear, that means you just have to alias the required arguments (https://docs.generic-mapping-tools.org/dev/histogram.html#required-arguments), and the common aliases (-R, -J, -c, -p, -t, etc) to pass. Maybe add one minimal unit test to hit the code coverage target. I see you've done a few aliases already (and you can leave them in if you want), but don't feel like you have to complete all of them.

Example workflow would be to do: Minimal PR (this one) -> Gallery Example PR -> Complete documentation/aliases PR -> Full Tutorial PR

P.S. Yes, we should document this 'policy' about wrapping modules chunk by chunk somewhere, but thought I'd mention it to you first.

Are you willing to help implement and maintain this feature? Yes/No

[maxrjones]

Thanks for the great write-up! I agree with both points about issues being ideal for tracking and also a bit of a hassle. Maybe it's just that I am not used to it yet, but I find it a bit difficult to determine where on the path to completeness a module is based on the project board. What do you think about having a separate Feature request: wrap new GMT module issue template that includes a checklist for these steps? This could be in addition to your points about modifying the contributing guide and pull request template.

[willschlitzer]

Thanks for the great write-up! I agree with both points about issues being ideal for tracking and also a bit of a hassle. Maybe it's just that I am not used to it yet, but I find it a bit difficult to determine where on the path to completeness a module is based on the project board. What do you think about having a separate Feature request: wrap new GMT module issue template that includes a checklist for these steps? This could be in addition to your points about modifying the contributing guide and pull request template.

I think this is a good idea. It's easy to say we want to wrap something in small, manageable chunks, but that's not specific and someone new to the project (or not new at all) may be confused on what the expectations are for wrapping a function.

[willschlitzer]

@weiji14 Are you envisioning this as an addition to CONTRIBUTING.md or should it be somewhere else in the documentation?

[weiji14]

@weiji14 Are you envisioning this as an addition to CONTRIBUTING.md or should it be somewhere else in the documentation?

Yes, I think it should be in CONTRIBUTING.md somewhere, but the Pull Request template's checklist also needs some modification.

[maxrjones]

I'm starting to get a bit more used to the project board and think this could be really helpful. I have a couple suggestions:

1. Include a checklist on the cards that gives context to the referenced issues/PRs(e.g., https://github.com/GenericMappingTools/pygmt/projects/9#card-71936074) This might be redundant with the feature request issues, so it could be only applied to the modules that aren't being tracked by an issue.
2. Combine panels 4 (gallery) and 5 (tutorial) since not all modules will need both.

[willschlitzer]

I'm a fan of the project board as well; I think it makes it easier to look at the big picture and see what tasks need to be done, rather than look to find issues for specific modules to see if they need additional features.

This might be redundant with the feature request issues, so it could be only applied to the modules that aren't being tracked by an issue.

I don't think we have many new modules being tracked by an issue. I think it would be easiest to transition existing feature request issues to the project board, rather than leave issues open for potentially a long time while we wait for the later stages of a module getting wrapped.

2. Combine panels 4 (gallery) and 5 (tutorial) since not all modules will need both.

Agreed.

[maxrjones]

What do you think about modifying the project board so that the modules are placed in the column that requires completion rather than the column that has been completed? I think this would be more clear for finding out what needs to be done and would better account for the fact that not all steps are always completed in order. For example, wiggle is currently in the column 'Added gallery|tutorial example', which is true but not that helpful because it still has missing aliases.

My suggested columns are:

1. Feature request issue (where module cards live when there's only an issue open for discussion)
2. Initial implementation (modules that are being implemented for the first time)
3. Complete aliases (modules that have an initial implementation but are missing aliases, which may be in progress)
4. Gallery|tutorial example (modules that need a gallery or tutorial, which may be in progress)
5. Ongoing maintenance (modules that have steps 1-4 completed)

[seisman]

Sounds good to me. Should we start to use the Projects (beta) instead?

[willschlitzer]

I think it is a good idea for modules to be in the column with work to be done instead of work last completed.

I'm not opposed to Projects (beta), but looking at the GitHub page for it, I'm not sure what it will enable us to do that isn't already covered on the current module wrapping project.

[maxrjones]

I don't know of a way to transfer projects from Projects to Projects (beta) anyways. Maybe they will add this feature when it's out of beta. For now, I think we could start try out Projects (beta) for new projects.

[seisman]

The Projects (classic) has been sunset on August 23, 2024 and now we're using the new Projects at https://github.com/orgs/GenericMappingTools/projects/3.

There are many differences between the classic and new Projects. To me, the most significant difference is that, in Projects (classic), items can be linked to issues, PRs, or notes, while in new Projects, notes are drafts that can be converted to issues with one click. This change is important since we can comment on issues but can't comment on notes.

Projects (classic)	Projects (new)

When wrapping GMT modules, the most complicated thing is that each module usually have several options and many different features. So the stages previously proposed (quoted below) won't help much, because the "Add missing aliases" step will take years to complete and it's difficult to track whether an option or a feature is implemented or not.

• Wishlist
• 'Wrapper for XXX' feature request issue
• 'Wrap XXX' initial feature implementation PR
• 'Add missing aliases to XXX' documentation PR / 'Support some functionality in XXX' enhancement PR
• 'Add gallery example for XXX' documentation PR
• 'Add tutorial for XXX' documentation PR (optional)

Since in new Projects, each item should be linked to an issue or a PR, I think we can combine the functionality of both issues and project cards.

Here are the steps in my mind:

1. Someone opens an issue to request wrapping a module, e.g., Wrapper for polar #2311 [optional]
2. Discuss if we want to wrap the module [optional]
3. Start by creating a new central issue to track the progress. The issue should be add to the Projects. Figure.paragraph: Typeset one or multiple paragraphs #3710 is a sample issue, but we can further improve it and create an issue template based on it.
4. Close the issue opened in step 1
5. After an initial implementation is done, I think we can close issue 3, to avoid having too many long-term issues. Further progress can be tracked in the Projects board instead.

For the Projects board, currently it has 6 columns, from "wishlist" to "On going maintenance". I feel we can simplify it to 3 columns,

• 0. Wishlist [Link to feature request created in step 1]
• 1. WIP [Link to the central issue created in step 3]
• 2. On maintenance [When all functionality are implemented and there is at least one gallery/tutorial]

[seisman]

I just realized the sub-issue feature (currently beta) as announced in https://github.blog/changelog/2024-10-01-evolving-github-issues-public-beta/. I haven't had the opportunity to try it yet, but it looks promising. With the sub-issue feature, I feel it makes more sense to have a "central" issue for each module and have sub-issues for related detailed issues.

I've signed up the waiting list for the GMT organization and hopefully, we don't have to wait too long to try it.