diff --git a/docs/_data/sidebars/pmd_sidebar.yml b/docs/_data/sidebars/pmd_sidebar.yml index 50cd117faf..c8242277e2 100644 --- a/docs/_data/sidebars/pmd_sidebar.yml +++ b/docs/_data/sidebars/pmd_sidebar.yml @@ -45,6 +45,9 @@ entries: - title: Tools / Integrations url: /pmd_userdocs_tools.html output: web, pdf + - title: FAQ + url: /pmd_userdocs_faq.html + output: web, pdf - title: Getting Help url: /pmd_userdocs_help.html output: web, pdf diff --git a/docs/images/devdocs/designer_screenshot.png b/docs/images/devdocs/designer_screenshot.png new file mode 100644 index 0000000000..64a59a62d1 Binary files /dev/null and b/docs/images/devdocs/designer_screenshot.png differ diff --git a/docs/images/userdocs/screenshot_cpd.png b/docs/images/userdocs/screenshot_cpd.png new file mode 100644 index 0000000000..349b1d0e48 Binary files /dev/null and b/docs/images/userdocs/screenshot_cpd.png differ diff --git a/docs/pages/pmd/devdocs/releasing.md b/docs/pages/pmd/devdocs/releasing.md index 5e497ba7cd..b62688c618 100644 --- a/docs/pages/pmd/devdocs/releasing.md +++ b/docs/pages/pmd/devdocs/releasing.md @@ -4,3 +4,188 @@ sidebar: pmd_sidebar permalink: pmd_devdocs_releasing.html folder: pmd/devdocs --- + +This page describes the current status of the release process. + +Since versions 5.4.5 / 5.5.4 there is an automated release process using [travis-ci](https://travis-ci.org) +in place. However, there are still a few steps, that need manual examination. + +Note: You can find a small shell script in the root of the repo: `do-release.sh`. This script guides you +through the release process. + + +## Preparations + +Make sure code is up to date and everything is committed and pushed with git: + + $ mvn clean + $ git pull + $ git status + + + +### The Release Notes + +At a very minimum, the current date must be noted in the release notes. Also, the version +must be adjusted. E.g. by removing "-SNAPSHOT". + +You can find the release notes here: `src/site/markdown/overview/changelog.md`. + +The release notes usual mention any new rules that have been added since the last release. +Please double check the file `pmd-core/src/main/resources/rulesets/releases/.xml`, so +that all new rules are listed. + +Check in all (version) changes to branch master or any other branch, from which the release takes place: + + $ git commit -a -m "Prepare pmd release " + $ git push + + +### The Homepage + +The github repo `pmd.github.io` hosts the homepage for [https://pmd.github.io](https://pmd.github.io). +The `index.html` page needes to be updated to display the new release. The new release is mentioned + +* on the start page +* in the announcements +* and in the previous releases section + + +Check in all (version) changes to branch master: + + $ git commit -a -m "Prepare pmd release " + $ git push + + + +## Creating the release + +The release is created using the **maven-release-plugin**. This plugin changes the version by basically +removing the "-SNAPSHOT" suffix, builds the changed project locally, commits the version change, creates +a new tag from this commit, changes the version of the project to the next snapshot, commits this change +and pushes everything. + +`RELEASE_VERSION` is the version of the release. It is reused for the tag. `DEVELOPMENT_VERSION` is the +next snapshot version after the release. + + mvn -B release:clean release:prepare \ + -Dtag=pmd_releases/${RELEASE_VERSION} \ + -DreleaseVersion=${RELEASE_VERSION} \ + -DdevelopmentVersion=${DEVELOPMENT_VERSION} + + +Once the maven plugin has pushed the tag, travis-ci will start and build a new version from this tag. Since +it is a tag build and a released version build, travis-ci will do a couple of additional stuff: + +* Deploy and release the build to maven central, so that it can be downloaded from + . This is done automatically, if + all unit tests pass on travis-ci. The plugin [nexus-staging-maven-plugin](https://github.com/sonatype/nexus-maven-plugins/tree/master/staging/maven-plugin) is used for that. +* Upload the new binaries to github releases under . It also uploads + the release notes. +* Upload the new binaries additionally to sourceforge, so that they can be downloaded from + , including the release notes. The new binaries are + selected as the new default downloads for PMD. +* Add the documentation of the new release to a subfolder on , also make + this folder available as `latest`. + + +## After the release + +The release on travis currently takes about 30 minutes. Once this is done, you can spread the news: + +### Submit a news on SF + +Submit news to SF on the [PMD Project News](https://sourceforge.net/p/pmd/news/) page. You can use +the following template: + + PMD released + + * Downloads: https://github.com/pmd/pmd/releases/tag/pmd_releases%2F + * Documentation: https://pmd.github.io/pmd-/ + + And Copy-Paste the release notes + +### Write an email to the mailing list + + To: PMD Developers List + Subject: [ANNOUNCE] PMD released + + + * Downloads: https://github.com/pmd/pmd/releases/tag/pmd_releases%2F + * Documentation: https://pmd.github.io/pmd-/ + + And Copy-Paste the release notes + + +## Prepare the next release + +### Prepare the new release notes + +* Move version/release info from **src/site/markdown/overview/changelog.md** to **src/site/markdown/overview/changelog-old.md**. +* Update version/release info in **src/site/markdown/overview/changelog.md**. Use the following template: + + + # PMD Release Notes + + ## ????? - ${DEVELOPMENT_VERSION} + + The PMD team is pleased to announce PMD ${DEVELOPMENT_VERSION%-SNAPSHOT}. + + This is a bug fixing release. + + ### Table Of Contents + + * [New and noteworthy](#New_and_noteworthy) + * [Fixed Issues](#Fixed_Issues) + * [API Changes](#API_Changes) + * [External Contributions](#External_Contributions) + + ### New and noteworthy + + ### Fixed Issues + + ### API Changes + + ### External Contributions + +Commit and push + + $ git commit -m "Prepare next development version" + $ git push origin master + + +### Close / Create new milestones + +Manage the milestones under . +Maybe there are some milestones on sourceforge, too: . + + + +## Branches + +### Merging + +If the release was done on a maintenance branch, such as `pmd/5.4.x`, then this branch should be +merge into the next "higher" branches, such as `pmd/5.5.x` and `master`. + +This ensures, that all fixes done on the maintenance branch, finally end up in the other branches. +In theory, the fixes should already be there, but you never now. + + +### Multiple releases + +If releases from multiple branches are being done, the order matters. You should start from the "oldes" branch, +e.g. `pmd/5.4.x`, release from there. Then merge (see above) into the next branch, e.g. `pmd/5.5.x` and release +from there. Then merge into the `master` branch and release from there. This way, the last release done, becomes +automatically the latest release on and on sourceforge. + + +### (Optional) Create a new release branch + +At some point, it might be time for a new maintenance branch. Such a branch is usually created from +the `master` branch. Here are the steps: + +* Create a new branch: `git branch pmd/5.6.x master` +* Update the version in both the new branch and master, e.g. `mvn versions:set -Dversion=5.6.0-SNAPSHOT` + and `mvn versions:set -Dversion=5.7.0-SNAPSHOT`. +* Update the release notes on both the new branch and master diff --git a/docs/pages/pmd/devdocs/writing_pmd_rules.md b/docs/pages/pmd/devdocs/writing_pmd_rules.md index 6462741dc4..bf75a8c2f7 100644 --- a/docs/pages/pmd/devdocs/writing_pmd_rules.md +++ b/docs/pages/pmd/devdocs/writing_pmd_rules.md @@ -76,7 +76,7 @@ You can generate this yourself by: * Run the batch file bin/designer.bat * Paste the code into the left text area and click the “Go” button * Note that there’s another panel and a textfield to test out XPath expressions; more on that later. -* Here’s a screenshot: ![designer screenshot](images/designer_screenshot.png) +* Here’s a screenshot: ![designer screenshot](/images/devdocs/designer_screenshot.png) So you can see in the example above that the AST for a `WhileStatement` looks kind of like this (excluding that expression gibberish for clarity): diff --git a/docs/pages/pmd/userdocs/cpd.md b/docs/pages/pmd/userdocs/cpd.md index bfc38dcc9b..9555ec3bf9 100644 --- a/docs/pages/pmd/userdocs/cpd.md +++ b/docs/pages/pmd/userdocs/cpd.md @@ -1,19 +1,11 @@ --- title: Finding duplicated code +summary: Or how to find copied and pasted code sidebar: pmd_sidebar permalink: pmd_userdocs_cpd.html folder: pmd/userdocs --- -Or how to find copied and pasted code - -* [Overview](#Overview) -* [Command line usage](#Command_line_usage) -* [Ant task](#Ant_task) -* [GUI](#GUI) -* [Suppression](#Suppression) - - ## Overview Duplicate code can be hard to find, especially in a large project. @@ -443,9 +435,9 @@ For Linux: ./run.sh cpdgui -Here's a [screenshot](../images/screenshot_cpd.png) of CPD after running on the JDK 8 java.lang package: +Here's a screenshot of CPD after running on the JDK 8 java.lang package: -![CPD Screenshot after running on the JDK 8 java.lang package](../images/screenshot_cpd.png) +![CPD Screenshot after running on the JDK 8 java.lang package](/images/userdocs/screenshot_cpd.png) ## Suppression diff --git a/docs/pages/pmd/userdocs/faq.md b/docs/pages/pmd/userdocs/faq.md new file mode 100644 index 0000000000..3290de321d --- /dev/null +++ b/docs/pages/pmd/userdocs/faq.md @@ -0,0 +1,55 @@ +--- +title: FAQ +sidebar: pmd_sidebar +permalink: pmd_userdocs_faq.html +folder: pmd/userdocs +--- + +## Rules + +### How useful are the rules? + +Have this clear: having a projects with no pmd violations does not mean at all, I repeat, +it does not mean at all, not at the minimum expected, that the project has any quality. +For illustrating this I'll tell a little story taken from my work (a sadly real story). +Some classes had fields that were reported as unused, (unused code ruleset) as developers +saw this, they wanted to remove the violation, (not fix the code, fix the violation) so +the action took was to add useless log sentences with something like: +'unused variable '+unusedVariable. Believe it or not, the code was worse than the original +and reported less pmd violations. + +In a more positive way: use the rules as you see them fix, don't try to remove violations +per-se, try to review the code and see if the particular cases you are using are correct or not. + + +## Development + +### In which order are nodes visited? + +The parser performs a depth-first traversal. +Consider the given source: + + public class Foo { + String name; + private class Bar { + String x; + } + int total; + } + +The visiting order here will be: + +1. Class Foo +2. Field name +3. Class Bar +4. Field x +5. Field total + +Note that the total field of Foo will be visited after visiting the fields in Bar. +You must take this into account for certain rules. + +### Is there a simple way of getting fields from a given class? + +Yes, the symbol table can supply that information. + +FIXME: add code example