search

GenericMappingTools / gmt

The Generic Mapping Tools
https://www.generic-mapping-tools.org
Other
860 stars 359 forks source link

Streamline steps for building and maintaining GMT #4840

Closed weiji14 closed 3 years ago

weiji14 commented 3 years ago

Description of the desired feature

The steps to build and run tests in GMT to produce new postscript (*.ps) files is not very intuitive for first timers. In particular, it's a little confusing having to jump between the BUILDING.md and MAINTENANCE.md documents.

Yes, I think from this it's clear from this PR that some revisions are needed to the building and maintaining (and possible contributing) documentation. When I started, I also found that I needed to bounce back and forth between building and maintaining documents a bunch. Perhaps some redundancy is needed for improved clarity. Would you want to open an issue for this?

Originally posted by @meghanrjones in https://github.com/GenericMappingTools/gmt/issues/4838#issuecomment-783445471

See also https://github.com/GenericMappingTools/gmt/pull/4838#issuecomment-782954781 and https://github.com/GenericMappingTools/gmt/pull/4838#issuecomment-782964119

Suggested changes:

Are you willing to help implement and maintain this feature? Happy to review the Pull Request!

maxrjones commented 3 years ago

The downside of keeping BUILDING.md and MAINTENANCE.md separate is that there will need to be more redundancy to make setup easier for new developers. But, I think it is necessary to keep them separate because the GMT website links to BUILDING.md for instructions on how to build from source and there are likely many people who want to build from source without needing debugging flags, testing instructions, etc.

PaulWessel commented 3 years ago

Might it be an option to add a DEVELOPER.md that links to the two others but helps in describing the overall workflow?

maxrjones commented 3 years ago

Might it be an option to add a DEVELOPER.md that links to the two others but helps in describing the overall workflow?

Rather than adding a new document, we could add a 'setting up your environment' section (similar to PyGMT's section in their contributing guide) and a more complete description of the overall workflow to CONTRIBUTING.md.

maxrjones commented 3 years ago

Related issue: #364