Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://github.com/pmd/pmd/issues/2492 below:

[doc] Promote wiki pages to standard doc pages · Issue #2492 · pmd/pmd · GitHub

Part of #1139

Is your feature request related to a problem? Please describe.

The documentation for new contributors is spread across several locations:

1. CONTRIBUTING.md
2. BUILDING.md
3. Some wiki pages
   1. https://github.com/pmd/pmd/wiki/Newcomers%27-Guide : originally targeted for prospective summer of code students, probably can be used as generic doc for new contributors
   2. https://github.com/pmd/pmd/wiki/Setup-IDE
4. Some website pages
   1. Developer resources: kind of overlaps (in scope) with CONTRIBUTING.md
   2. Building PMD from source: overlaps in scope with BUILDING.md

The website links back to CONTRIBUTING.md.

There's afaik no link pointing from outside of the wiki into the wiki, so those pages are less discoverable than others. The wiki pages are also marked with this notice:

Note: this is WIP - once this documentation is matured, it will be moved to the official documentation.

I think it's time we do that, especially since those wiki pages are IMO very comprehensive

So the problem statement is:

• the documentation is fragmented
• there's limited cross-linking between those fragments
• the github landing page (CONTRIBUTING.md) omits some important information (building and IDE setup) for newcomers

Describe the solution you'd like

• Keep CONTRIBUTING.md and improve it:
  • see https://help.github.com/en/github/building-a-strong-community/setting-guidelines-for-repository-contributors)
  • explain about the regression tester: when you create a PR, this is what happens:
    ci will build it, regression tester comments on it, the maintainer will have a look
    and provide feedback like requesting changes
  • define/refine guidelines for PR submission
  • keep CONTRIBUTING.md concise, more details can be added to
    Developer Resources.
• Move Setup IDE from wiki into the
  documentation and link from Contributing.
• Move Newcomers' Guide into
  the documentation
• Remove BUILDING.md - it overlaps with
  Building PMD from source.
  However, CONTRIBUTING should link to it.
• Describe how to build and test (= verify) a single module without
  rebuild whole PMD repository
• Document how to test SNAPSHOT version of PMD. Snapshots versions of PMD
  are also published in a public maven repository, that can be used in custom
  projects -> how to do this...

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4