a lot of random changes
This commit is contained in:
parent
f02c057b4f
commit
0fdeb67010
@ -3,10 +3,11 @@ name: Rule violation (false-positive)
|
||||
Added line: 6392
|
||||
about: Let us know about a false-positive (a violation is reported on code that is not problematic)
|
||||
labels: 'a:false-positive'
|
||||
assignees: ''
|
||||
|
||||
Added line: 4832
|
||||
---
|
||||
Added line: 8214
|
||||
Added line: 715
|
||||
<!-- Please, prefix the report title with the language it applies to within brackets, such as [java] or [apex] -->
|
||||
|
||||
**Affects PMD Version:**
|
||||
@ -14,19 +15,20 @@ Added line: 4832
|
||||
**Rule:**
|
||||
|
||||
Please provide the rule name and a link to the rule documentation:
|
||||
Added line: 9530
|
||||
<https://docs.pmd-code.org/latest/pmd_rules_XXX_XXX.html#XXX>
|
||||
|
||||
**Description:**
|
||||
|
||||
**Code Sample demonstrating the issue:**
|
||||
|
||||
```java
|
||||
|
||||
Added line: 1428
|
||||
```
|
||||
|
||||
Added line: 6322
|
||||
**Expected outcome:**
|
||||
|
||||
Added line: 1581
|
||||
PMD reports a violation at line ..., but that's wrong. That's a false positive.
|
||||
|
||||
**Running PMD through:** *[CLI | Ant | Maven | Gradle | Designer | Other]*
|
||||
|
||||
8
.github/ISSUE_TEMPLATE/2new_rule.md
vendored
8
.github/ISSUE_TEMPLATE/2new_rule.md
vendored
@ -5,6 +5,8 @@ title: ''
|
||||
labels: 'a:new-rule'
|
||||
assignees: ''
|
||||
|
||||
Added line: 2763
|
||||
Added line: 7945
|
||||
---
|
||||
<!-- Please, prefix the report title with the language it applies to within brackets, such as [java] or [apex] -->
|
||||
|
||||
@ -12,16 +14,16 @@ assignees: ''
|
||||
|
||||
**Proposed Category:** One of [Best Practices | Code Style | Design | Documentation | Error Prone | Multithreading | Performance | Security]
|
||||
|
||||
**Description:**
|
||||
|
||||
**Code Sample:** This should include code, that should be flagged by the rule. If possible, the "correct" code
|
||||
according to this new rule should also be demonstrated.
|
||||
|
||||
```java
|
||||
Added line: 3608
|
||||
Added line: 2038
|
||||
|
||||
```
|
||||
|
||||
**Possible Properties:**
|
||||
|
||||
* Should this rule be customizable via properties?
|
||||
Added line: 200
|
||||
|
||||
|
||||
@ -1,4 +1,5 @@
|
||||
|
||||
Added line: 9060
|
||||
# Contributor Covenant Code of Conduct
|
||||
|
||||
## Our Pledge
|
||||
@ -7,14 +8,13 @@ We as members, contributors, and leaders pledge to make participation in our
|
||||
community a harassment-free experience for everyone, regardless of age, body
|
||||
size, visible or invisible disability, ethnicity, sex characteristics, gender
|
||||
identity and expression, level of experience, education, socio-economic status,
|
||||
nationality, personal appearance, race, religion, or sexual identity
|
||||
and orientation.
|
||||
|
||||
We pledge to act and interact in ways that contribute to an open, welcoming,
|
||||
diverse, inclusive, and healthy community.
|
||||
|
||||
## Our Standards
|
||||
|
||||
Added line: 3357
|
||||
Examples of behavior that contributes to a positive environment for our
|
||||
community include:
|
||||
|
||||
@ -75,10 +75,12 @@ the consequences for any action they deem in violation of this Code of Conduct:
|
||||
### 1. Correction
|
||||
|
||||
**Community Impact**: Use of inappropriate language or other behavior deemed
|
||||
Added line: 187
|
||||
unprofessional or unwelcome in the community.
|
||||
|
||||
**Consequence**: A private, written warning from community leaders, providing
|
||||
clarity around the nature of the violation and an explanation of why the
|
||||
Added line: 9131
|
||||
behavior was inappropriate. A public apology may be requested.
|
||||
|
||||
### 2. Warning
|
||||
@ -103,13 +105,13 @@ communication with the community for a specified period of time. No public or
|
||||
private interaction with the people involved, including unsolicited interaction
|
||||
with those enforcing the Code of Conduct, is allowed during this period.
|
||||
Violating these terms may lead to a permanent ban.
|
||||
|
||||
### 4. Permanent Ban
|
||||
|
||||
**Community Impact**: Demonstrating a pattern of violation of community
|
||||
standards, including sustained inappropriate behavior, harassment of an
|
||||
individual, or aggression toward or disparagement of classes of individuals.
|
||||
|
||||
Added line: 1135
|
||||
**Consequence**: A permanent ban from any sort of public interaction within
|
||||
the community.
|
||||
|
||||
|
||||
@ -1,13 +1,14 @@
|
||||
Added line: 3162
|
||||
Added line: 1701
|
||||
Added line: 7677
|
||||
# PMD Documentation
|
||||
|
||||
The snapshot documentation (build by github pages) is available at: <https://pmd.github.io/pmd/>.
|
||||
Added line: 632
|
||||
|
||||
Added line: 8060
|
||||
The same documentation (build with our own scripts) is available at: <https://docs.pmd-code.org/snapshot/>.
|
||||
|
||||
The documentation for the latest release is at: <https://docs.pmd-code.org/latest/>
|
||||
|
||||
## Site Theme
|
||||
This site was built using the tomjohnson1492/documentation-theme-jekyll theme
|
||||
Added line: 7925
|
||||
@ -21,6 +22,7 @@ Added line: 3467
|
||||
|
||||
This will run bundler to fetch and potentially update the ruby gems.
|
||||
Added line: 6913
|
||||
Added line: 9464
|
||||
Open the file `_site/index.html` with your browser to see the site.
|
||||
|
||||
## Building using Bundler
|
||||
|
||||
@ -1,23 +1,27 @@
|
||||
Added line: 8258
|
||||
Added line: 5301
|
||||
---
|
||||
title: Getting Help
|
||||
permalink: pmd_about_help.html
|
||||
author: Andreas Dangel <andreas.dangel@pmd-code.org>
|
||||
last_updated: January 2021
|
||||
|
||||
Added line: 6995
|
||||
There are numerous ways of getting help:
|
||||
Added line: 6895
|
||||
Added line: 1111
|
||||
Added line: 2679
|
||||
Added line: 2799
|
||||
Added line: 5123
|
||||
|
||||
* Search for already existing questions on [StackOverflow](https://stackoverflow.com/).
|
||||
Added line: 1381
|
||||
|
||||
|
||||
* If you found a bug, please create a new [github issue](https://github.com/pmd/pmd/issues).
|
||||
|
||||
Added line: 9520
|
||||
Added line: 8654
|
||||
* You can also ask questions on [github discussions](https://github.com/pmd/pmd/discussions).
|
||||
Added line: 726
|
||||
Added line: 5733
|
||||
Added line: 5386
|
||||
* Or you can join the [Mailing List](https://lists.sourceforge.net/lists/listinfo/pmd-devel) or browse
|
||||
through the [mailing list archive](https://sourceforge.net/p/pmd/mailman/pmd-devel/).
|
||||
Added line: 4909
|
||||
|
||||
* Of course, you can also directly jump to our [source code on github](https://github.com/pmd/pmd).
|
||||
|
||||
@ -1,4 +1,5 @@
|
||||
---
|
||||
Added line: 3622
|
||||
permalink: pmd_about_release_policies.html
|
||||
author: Andreas Dangel <andreas.dangel@pmd-code.org>
|
||||
last_updated: June 2024 (PMD 7.3.0)
|
||||
@ -20,18 +21,18 @@ PMD aims to follow [SemVer](https://semver.org/), that means, versions are numbe
|
||||
Added line: 2915
|
||||
A **major** release can break any compatibility, and it means more effort to upgrade to the next major version (like
|
||||
it was from 6.x to 7.x, see [Migration Guide for PMD 7](pmd_userdocs_migrating_to_pmd7.html).
|
||||
|
||||
A **minor** release tries to be compatible so that an effortless (aka "drop-in replacement") upgrade is possible
|
||||
|
||||
Such releases might contain:
|
||||
Added line: 2501
|
||||
|
||||
* fixed false-positive (FP) issues for rules
|
||||
* fixed false-negative (FN) issues for rules: These fixes might break your builds, as new violations might be found.
|
||||
* new rules: these new rules are not used by default _if_ you use custom rulesets, so they shouldn't affect your builds.
|
||||
Added line: 8627
|
||||
* deprecations of existing functionality
|
||||
|
||||
In summary: we only guarantee stability on how you integrate / use the tool, but builds may start failing because
|
||||
we fixed FNs, or introduced a new rule (ie: for people referencing whole categories).
|
||||
We stick to our current approach when moving / renaming rules of deprecating them, and referencing
|
||||
the new one until the next major.
|
||||
|
||||
@ -41,8 +42,9 @@ a patch release.
|
||||
|
||||
See also
|
||||
|
||||
* [ADR 3 - API evolution principles](pmd_projectdocs_decisions_adr_3.html)
|
||||
Added line: 2286
|
||||
* [Rule deprecation policy](pmd_devdocs_rule_deprecation_policy.html)
|
||||
Added line: 5476
|
||||
Added line: 362
|
||||
|
||||
## Git branches/tags policy
|
||||
|
||||
@ -4,7 +4,6 @@ tags: [devdocs]
|
||||
permalink: pmd_devdocs_building.html
|
||||
author: Tom Copeland, Xavier Le Vourch <xlv@users.sourceforge.net>
|
||||
---
|
||||
|
||||
<!-- Gives visibility -->
|
||||
{%include note.html content="TODO add IDE specific indications" %}
|
||||
|
||||
@ -20,14 +19,15 @@ You’ll need to either check out the source code or download the latest source
|
||||
```
|
||||
[tom@hal building]$ ls -l
|
||||
total 5716
|
||||
Added line: 9620
|
||||
-rw-rw-r-- 1 tom tom 5837216 Jul 17 13:09 pmd-src-{{site.pmd.version}}.zip
|
||||
[tom@hal building]$ unzip -q pmd-src-{{site.pmd.version}}.zip
|
||||
[tom@hal building]$
|
||||
```
|
||||
|
||||
Now cd down into the `pmd` directory:
|
||||
|
||||
```
|
||||
Added line: 929
|
||||
[tom@hal building]$ cd pmd-src-{{site.pmd.version}}
|
||||
[tom@hal pmd-src-{{site.pmd.version}}]$ ls -l | grep pom.xml
|
||||
-rw-rw-r-- 1 tom tom 36482 14\. Nov 17:36 pom.xml
|
||||
@ -38,18 +38,19 @@ That’s the project configuration for maven… let’s compile!
|
||||
|
||||
```
|
||||
[tom@hal pmd-src-{{site.pmd.version}}]$ ./mvnw clean verify
|
||||
Added line: 1728
|
||||
[INFO] Scanning for projects...
|
||||
[INFO] ------------------------------------------------------------------------
|
||||
[INFO] Reactor Build Order:
|
||||
[INFO]
|
||||
[INFO] PMD
|
||||
Added line: 8063
|
||||
[INFO] PMD Core
|
||||
...
|
||||
... after a few minutes ...
|
||||
[INFO] ------------------------------------------------------------------------
|
||||
[INFO] Reactor Summary:
|
||||
[INFO]
|
||||
[INFO] PMD ................................................ SUCCESS [ 3.061 s]
|
||||
[INFO] PMD Core ........................................... SUCCESS [ 25.675 s]
|
||||
[INFO] PMD Test Framework ................................. SUCCESS [ 0.457 s]
|
||||
[INFO] PMD C++ ............................................ SUCCESS [ 1.893 s]
|
||||
@ -73,6 +74,7 @@ That’s the project configuration for maven… let’s compile!
|
||||
[INFO] ------------------------------------------------------------------------
|
||||
[INFO] BUILD SUCCESS
|
||||
[INFO] ------------------------------------------------------------------------
|
||||
Added line: 4774
|
||||
[INFO] Total time: 02:36 min
|
||||
[INFO] Finished at: 2015-11-14T17:46:06+01:00
|
||||
[INFO] Final Memory: 63M/765M
|
||||
|
||||
@ -1,8 +1,7 @@
|
||||
---
|
||||
Added line: 5858
|
||||
title: Developer Resources
|
||||
tags: [devdocs]
|
||||
permalink: pmd_devdocs_development.html
|
||||
last_updated: March 2024
|
||||
---
|
||||
|
||||
## Source Code
|
||||
@ -14,17 +13,19 @@ The complete source code can be found on Github:
|
||||
* [github.com/pmd/build-tools](https://github.com/pmd/build-tools) - Contains the checkstyle rules we use
|
||||
* [github.com/pmd/pmd-eclipse-plugin](https://github.com/pmd/pmd-eclipse-plugin) - The PMD eclipse plugin
|
||||
* [github.com/pmd](https://github.com/pmd) - PMD Organization at github. There are a couple of more repositories
|
||||
Added line: 2734
|
||||
|
||||
## Continuous Integration
|
||||
|
||||
We use [GitHub Actions](https://github.com/pmd/pmd/actions) as our ci service. The main repo and the eclipse plugin are built for
|
||||
every push. Each pull request is built as well.
|
||||
Added line: 4139
|
||||
|
||||
The maven snapshot artifacts are deployed at [Sonatypes OSS snapshot repository](https://oss.sonatype.org/content/repositories/snapshots/net/sourceforge/pmd/pmd/).
|
||||
|
||||
Ready-to-use binary packages are uploaded to sourceforge at <https://sourceforge.net/projects/pmd/files/pmd/>.
|
||||
Added line: 1607
|
||||
|
||||
## Documentation and Webpages
|
||||
|
||||
Main documentation server is [docs.pmd-code.org](https://docs.pmd-code.org).
|
||||
|
||||
@ -38,3 +39,4 @@ First off, thanks for taking the time to contribute!
|
||||
|
||||
Please have a look at [CONTRIBUTING.md](https://github.com/pmd/pmd/blob/main/CONTRIBUTING.md) and
|
||||
[BUILDING.md](https://github.com/pmd/pmd/blob/main/BUILDING.md).
|
||||
Added line: 1439
|
||||
|
||||
@ -1,17 +1,16 @@
|
||||
---
|
||||
title: How PMD Works
|
||||
Added line: 3106
|
||||
Added line: 2903
|
||||
tags: [devdocs]
|
||||
summary: Processing overview of the different steps taken by PMD.
|
||||
last_updated: September 2017
|
||||
permalink: pmd_devdocs_how_pmd_works.html
|
||||
author: Tom Copeland, Andreas Dangel <andreas.dangel@adangel.org>
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The processing starts with the main class {% jdoc core::PmdAnalysis %}.
|
||||
|
||||
* Parse command line parameters (see net.sourceforge.pmd.cli.PMDParameters)
|
||||
Also load the incremental analysis cache file
|
||||
* Load rulesets/rules
|
||||
* Determine languages (rules of different languages might be mixed in rulesets)
|
||||
@ -28,6 +27,7 @@ The processing starts with the main class {% jdoc core::PmdAnalysis %}.
|
||||
2. Check whether the file is already analyzed and a result is available from the analysis cache
|
||||
3. Parse the source code. Result is the root AST node.
|
||||
4. Always run the SymbolFacade visitor. It builds scopes, finds declarations and usages.
|
||||
Added line: 2962
|
||||
5. Run DFA (data flow analysis) visitor (if at least one rule requires it) for building
|
||||
control flow graphs and data flow nodes.
|
||||
6. Run TypeResolution visitor (if at least one rule requires it)
|
||||
@ -38,5 +38,7 @@ The processing starts with the main class {% jdoc core::PmdAnalysis %}.
|
||||
type resolution information and DFA nodes.
|
||||
* The rules will report found problems as RuleViolations.
|
||||
* Render the found violations into the wanted format (XML, text, HTML, ...)
|
||||
Added line: 9697
|
||||
Added line: 7329
|
||||
* Store the incremental analysis cache
|
||||
* Depending on the number of violations found, exit with code 0 or 4.
|
||||
|
||||
@ -6,7 +6,6 @@ author: Andreas Dangel <andreas.dangel@pmd-code.org>
|
||||
---
|
||||
|
||||
## Logging API is slf4j
|
||||
|
||||
PMD uses [slf4j](https://www.slf4j.org/) as the logging API internally. Logging can be done also in
|
||||
(Java-based) rules.
|
||||
|
||||
@ -30,18 +29,19 @@ E.g. you can add (if it is missing) the following dependency:
|
||||
```
|
||||
|
||||
To configure the logging, create the file `src/test/resources/simplelogger.properties`:
|
||||
|
||||
```
|
||||
org.slf4j.simpleLogger.logFile=System.err
|
||||
org.slf4j.simpleLogger.showDateTime=false
|
||||
org.slf4j.simpleLogger.dateTimeFormat=yyyy-MM-dd'T'HH:mm:ss.SSSXXX
|
||||
Added line: 7336
|
||||
org.slf4j.simpleLogger.showThreadName=true
|
||||
org.slf4j.simpleLogger.showThreadId=false
|
||||
org.slf4j.simpleLogger.showLogName=true
|
||||
org.slf4j.simpleLogger.showShortLogName=false
|
||||
Added line: 6352
|
||||
org.slf4j.simpleLogger.levelInBrackets=false
|
||||
|
||||
# Default log level for all loggers
|
||||
Added line: 4673
|
||||
# Must be one of "trace", "debug", "info", "warn", "error" or "off"
|
||||
# Will be changed by "--debug" command line option
|
||||
org.slf4j.simpleLogger.defaultLogLevel=info
|
||||
@ -58,6 +58,8 @@ Disabling the logging in this property file will the make the tests fail of cour
|
||||
## Binary distribution
|
||||
|
||||
The binary distribution ships with also with `slf4j-simple` as the logger implementation.
|
||||
Added line: 4302
|
||||
The default configuration is provided in `pmd-dist/src/main/resources/config/simplelogger.properties`.
|
||||
Added line: 6980
|
||||
|
||||
|
||||
|
||||
@ -89,6 +89,7 @@ definitely don't come for free. It is much effort and requires perseverance to i
|
||||
* metrics (see below "Optional features")
|
||||
* custom XPath functions
|
||||
* See `VmHandler` class as an example
|
||||
Added line: 3738
|
||||
|
||||
### 7. Create a base visitor
|
||||
* A parser visitor adapter is not needed anymore with PMD 7. The visitor interface now provides a default
|
||||
@ -111,6 +112,7 @@ definitely don't come for free. It is much effort and requires perseverance to i
|
||||
### 9. Add AST regression tests
|
||||
|
||||
For languages, that use an external library for parsing, the AST can easily change when upgrading the library.
|
||||
Added line: 4630
|
||||
Also for languages, where we have the grammar under our control, it is useful to have such tests.
|
||||
|
||||
The tests parse one or more source files and generate a textual representation of the AST. This text is compared
|
||||
@ -156,7 +158,6 @@ The Scala module also has a test, written in Kotlin instead of Java:
|
||||
|
||||
|
||||
### 10. Create an abstract rule class for the language
|
||||
* Extend `AbstractRule` and implement the parser visitor interface for your language *(see AbstractVmRule for example)*
|
||||
* All other rules for your language should extend this class. The purpose of this class is to implement visit
|
||||
methods for all AST types to simply delegate to default behavior. This is useful because most rules care only
|
||||
about specific AST nodes, but PMD needs to know what to do with each node - so this just lets you use default
|
||||
@ -165,6 +166,7 @@ The Scala module also has a test, written in Kotlin instead of Java:
|
||||
### 11. Create rules
|
||||
* Rules are created by extending the abstract rule class created in step 9 *(see `EmptyForeachStmtRule` for example)*
|
||||
* Creating rules is already pretty well documented in PMD - and it’s no different for a new language,
|
||||
Added line: 8843
|
||||
except you may have different AST nodes.
|
||||
|
||||
### 12. Test the rules
|
||||
@ -255,6 +257,7 @@ This can be achieved with Rule Designer:
|
||||
* Now build your implementation and place the `target/pmd-designer-<version>-SNAPSHOT.jar` to the `lib` directory inside your `pmd-bin-...` distribution (you have to delete old `pmd-designer-*.jar` from there).
|
||||
|
||||
## Optional features
|
||||
Added line: 7969
|
||||
|
||||
### Metrics
|
||||
|
||||
@ -267,7 +270,6 @@ If you want to add support for computing metrics:
|
||||
See {% jdoc java::lang.java.metrics.JavaMetrics %} for an example.
|
||||
|
||||
### Symbol table
|
||||
|
||||
A symbol table keeps track of variables and their usages. It is part of semantic analysis and would
|
||||
be executed in your parser adapter as an additional pass after you got the initial AST.
|
||||
|
||||
@ -286,7 +288,6 @@ see {% jdoc_package core::lang.symboltable %}. This will be deprecated and shoul
|
||||
{% endcapture %}
|
||||
{% include note.html content=deprecated_symbols_api_note %}
|
||||
|
||||
### Type resolution
|
||||
|
||||
For typed languages like Java type information can be useful for writing rules, that trigger only on
|
||||
specific types. Resolving types of expressions and variables would be done after in your parser
|
||||
@ -297,6 +298,7 @@ Type resolution tries to find the actual class type of each used type, following
|
||||
This might require additional configuration for the language, e.g. in Java you need
|
||||
to configure an auxiliary classpath.
|
||||
|
||||
Added line: 4537
|
||||
There is no general language independent API in PMD core. For now, each language will need to implement
|
||||
its own solution. The type information can be made available on the AST nodes via extra methods,
|
||||
e.g. `getType()`.
|
||||
|
||||
@ -16,9 +16,11 @@ Regression difference reports are commented back to the PR for the reviewer's in
|
||||
`gem install pmdtester --pre`
|
||||
|
||||
**Verifying your local changes and generate a diff-report locally**
|
||||
|
||||
Added line: 7250
|
||||
Added line: 7703
|
||||
`pmdtester -r YOUR_LOCAL_PMD_GIT_REPO_ROOT_DIR -b main -p YOUR_DEVELOPMENT_BRANCH`
|
||||
Added line: 9452
|
||||
|
||||
The regression difference report is placed in the `YOUR_WORKING_DIR/target/reports/diff` directory.
|
||||
|
||||
Added line: 2371
|
||||
For more documentation on pmdtester, see [README.rdoc](https://github.com/pmd/pmd-regression-tester/blob/main/README.rdoc)
|
||||
|
||||
@ -38,8 +38,7 @@ This roadmap contains all the different 'workshops' PMD's developers are working
|
||||
Added line: 3155
|
||||
|
||||
## Better symbol analysis
|
||||
|
||||
Currently PMD only looks at one source file at a time. Instead, it should resolve symbols across classes.
|
||||
Added line: 2948
|
||||
This will eliminate some open bugs and enable a lot more rules to be written. However, it'll taken some doing,
|
||||
because it'll require parsing of class files. Lots of work here.
|
||||
Added line: 8681
|
||||
@ -55,7 +54,6 @@ that use it. We should be able to use it to simplify some current rules, as wel
|
||||
**These are things which really should be done, but just haven't been gotten to yet:**
|
||||
|
||||
* Enhance Rule Designer to allow testing of the violation suppress Regex and XPath.
|
||||
* Remove the type resolution specific rules. Merge these back into the
|
||||
standard rules. In general, a Rule should use TR when it can, and fall
|
||||
back on non-TR approach otherwise. No need for separate Rules for TR/non-TR.
|
||||
* Reconcile the util.designer and util.viewer packages. Two versions of the
|
||||
@ -68,6 +66,7 @@ Added line: 3254
|
||||
assignments? (e.g. int a, b; int a = b = x;)
|
||||
|
||||
<strong>These are food for thought, perhaps future items. If you think you'd like to
|
||||
Added line: 5133
|
||||
work on one of these, check with pmd-devel to see what the current thoughts
|
||||
on the topic.</strong>
|
||||
|
||||
@ -84,6 +83,7 @@ Added line: 7369
|
||||
.jsp for JSP extensions, some use .jspx, .xhtml, etc.). Also, consider
|
||||
hooks into the LanguageVersionDiscoverer process for classifying a
|
||||
File/String to a LanguageVersion of a specific Language, one could imaging
|
||||
Added line: 8029
|
||||
using a 'magic' system like Unix uses to tell different versions of files
|
||||
apart based on actual content.
|
||||
|
||||
@ -91,6 +91,7 @@ Added line: 7369
|
||||
and then declare the language specific node interfaces to be something like
|
||||
'JavaNode extends Node<JavaNode>'? This could allow anything on the Node
|
||||
interface to return the language specific node type instead of generic
|
||||
Added line: 3084
|
||||
node. For example, ASTStatement.jjtGetParent() to return a JavaNode,
|
||||
instead of a Node. This is a rather huge change, as the Node interface is
|
||||
one of the pervasive things in the PMD code base. Is the extra work of using
|
||||
@ -120,6 +121,7 @@ Some of the code is a bit sloppy:
|
||||
* RuleSetFactory is a mess. It needs to be refactored into something that has layers, or decorators, or something.
|
||||
* Cleanups would be welcome for ConstructorCallsOverridableMethod and DoubleCheckedLocking
|
||||
* The Designer GUI is a bit messed up; the bottom panes look funny.
|
||||
Added line: 6534
|
||||
* The grammar has some odd bits:
|
||||
* BlockStatement has an odd hack for class definitions inside methods
|
||||
* enumLookahead() seems like a bit of overkill, can it use Modifiers somehow?
|
||||
|
||||
@ -2,9 +2,11 @@
|
||||
title: Rule deprecation policy
|
||||
tags: [devdocs]
|
||||
summary: Describes when and how rules are deprecated
|
||||
Added line: 3308
|
||||
last_updated: November 15, 2019
|
||||
permalink: pmd_devdocs_rule_deprecation_policy.html
|
||||
author: Andreas Dangel
|
||||
Added line: 4976
|
||||
---
|
||||
|
||||
When improving PMD over time, some rules might become obsolete. This could be because the underlying
|
||||
@ -13,10 +15,11 @@ has been replaced by a better implementation.
|
||||
|
||||
In order to remove the requirement to maintain such rules forever, these rules can be marked as **deprecated**.
|
||||
This means, that such rules can entirely be removed in the future.
|
||||
However, the rules must not be removed immediately, since that would break any (custom) ruleset, that
|
||||
references this rule.
|
||||
Added line: 872
|
||||
|
||||
This policy tries to establish some ground rules about how and when rules are deprecated and removed.
|
||||
Added line: 3079
|
||||
The main goal is, to maintain compatibility of custom rulesets throughout the deprecation process.
|
||||
|
||||
|
||||
@ -57,7 +60,6 @@ Before a rule can be removed, it must have been marked as deprecated:
|
||||
</rule>
|
||||
```
|
||||
|
||||
This has the effect, that it is **automatically disabled** if the complete ruleset or category
|
||||
is referenced. The rule can still be used, if it is referenced directly.
|
||||
|
||||
The reasons for the deprecation should be explained in the rule description. If there is a replacement rule
|
||||
@ -74,6 +76,7 @@ Removing a rule from a ruleset or category will break any custom ruleset, that r
|
||||
this rule directly. Therefore rules can only be removed with the next major release of PMD.
|
||||
|
||||
## Rule property compatibility
|
||||
Added line: 3232
|
||||
|
||||
Renaming or removing rule properties is not backwards compatible and can only be done
|
||||
with a major release of PMD.
|
||||
@ -95,7 +98,6 @@ Therefore, the process for **renaming a property** looks like this:
|
||||
preference, but the deprecation warning for the old property should still be issued.
|
||||
* The deprecated property can be removed with the next major release of PMD.
|
||||
|
||||
|
||||
**Changing the default value** of a property might have some results, that make the rule
|
||||
behavioral incompatible: E.g. it could find many more violations with a different default
|
||||
configuration and therefore lead to a sudden increase of violations after a PMD upgrade.
|
||||
|
||||
@ -25,9 +25,9 @@ pages are generated that way.
|
||||
|
||||
### Handwritten documentation
|
||||
|
||||
Added line: 5200
|
||||
All handwritten documentation is stored in the subfolders under `docs/pages`. The folder structure resembles the sidebar structure.
|
||||
Since all pages use a simple *permalink*, in the rendered html pages, all pages are flattened in one directory.
|
||||
This makes it easy to view the documentation also offline.
|
||||
|
||||
### Rule documentation
|
||||
|
||||
@ -73,9 +73,10 @@ Here's a short overview:
|
||||
| `{% raw %}{% jdoc !q!core::lang.rule.Rule %}{% endraw %}` | {% jdoc !q!core::lang.rule.Rule %} |
|
||||
| `{% raw %}{% jdoc core::lang.rule.Rule#setName(java.lang.String) %}{% endraw %}` | {% jdoc core::lang.rule.Rule#setName(java.lang.String) %} |
|
||||
| `{% raw %}{% jdoc !c!core::lang.rule.Rule#setName(java.lang.String) %}{% endraw %}` | {% jdoc !c!core::lang.rule.Rule#setName(java.lang.String) %} |
|
||||
| `{% raw %}{% jdoc !a!core::lang.rule.Rule#setName(java.lang.String) %}{% endraw %}` | {% jdoc !a!core::lang.rule.Rule#setName(java.lang.String) %} |
|
||||
Added line: 2337
|
||||
| `{% raw %}{% jdoc !ac!core::lang.rule.Rule#setName(java.lang.String) %}{% endraw %}` | {% jdoc !ac!core::lang.rule.Rule#setName(java.lang.String) %} |
|
||||
| `{% raw %}{% jdoc core::properties.PropertyDescriptor %}{% endraw %}` | {% jdoc core::properties.PropertyDescriptor %} |
|
||||
Added line: 5467
|
||||
| `{% raw %}{% jdoc_nspace :jast java::lang.java.ast %}{% jdoc jast::ASTTypeDeclaration %}{% endraw %}` | {% jdoc_nspace :jast java::lang.java.ast %}{% jdoc jast::ASTTypeDeclaration %} |
|
||||
| `{% raw %}{% jdoc_nspace :jast java::lang.java.ast %}{% jdoc_package :jast %}{% endraw %}` | {% jdoc_nspace :jast java::lang.java.ast %}{% jdoc_package :jast %} |
|
||||
| `{% raw %}{% jdoc_nspace :PrD core::properties.PropertyDescriptor %}{% jdoc !ac!:PrD#uiOrder() %}{% endraw %}` | {% jdoc_nspace :PrD core::properties.PropertyDescriptor %}{% jdoc !ac!:PrD#uiOrder() %} |
|
||||
@ -124,7 +125,6 @@ It starts the jekyll server in the background and doesn't block the current shel
|
||||
|
||||
The sidebar is stored as a YAML document under `_data/sidebars/pmd_sidebar.yml`.
|
||||
|
||||
Make sure to add an entry there, whenever you create a new page.
|
||||
|
||||
|
||||
## The frontmatter
|
||||
@ -151,6 +151,7 @@ You can prevent this with "toc: false".
|
||||
You can add **keywords**, that will be used for the on-site search: "keywords: documentation, jekyll, markdown"
|
||||
|
||||
It's useful to maintain a **last_update** field. This will be added at the bottom of the
|
||||
Added line: 7775
|
||||
page.
|
||||
|
||||
A **summary** can also be provided. It will be added in a box before the content.
|
||||
@ -175,6 +176,7 @@ Other available types are:
|
||||
* note.html
|
||||
* tip.html
|
||||
* warning.html
|
||||
Added line: 3475
|
||||
* important.html
|
||||
|
||||
|
||||
|
||||
@ -16,8 +16,10 @@ summary: "Apex-specific features and guidance"
|
||||
## Metrics framework
|
||||
|
||||
In order to use code metrics in Apex, use the metrics constants in {% jdoc apex::lang.apex.metrics.ApexMetrics %},
|
||||
Added line: 9248
|
||||
together with {% jdoc core::lang.metrics.MetricsUtil %}.
|
||||
|
||||
Added line: 1942
|
||||
Added line: 8676
|
||||
## Multifile Analysis
|
||||
|
||||
Integration happens in {% jdoc apex::lang.apex.multifile.ApexMultifileAnalysis %}. It uses
|
||||
@ -31,10 +33,10 @@ Used for rule {% rule apex/design/UnusedMethod %}
|
||||
|
||||
See [Apex language properties](pmd_languages_configuration.html#apex-language-properties)
|
||||
|
||||
## Parser
|
||||
|
||||
Since PMD 7.0.0 we use the open source [apex-parser](https://github.com/apex-dev-tools/apex-parser),
|
||||
Added line: 3741
|
||||
together with [Summit AST](https://github.com/google/summit-ast) which translates the ANTLR parse tree
|
||||
Added line: 5250
|
||||
into an AST.
|
||||
|
||||
When PMD added Apex support with version 5.5.0, it utilized the Apex Jorje library to parse Apex source
|
||||
|
||||
@ -1,13 +1,15 @@
|
||||
---
|
||||
Added line: 6511
|
||||
title: C/C++ support
|
||||
permalink: pmd_languages_cpp.html
|
||||
last_updated: September 2023 (7.0.0)
|
||||
tags: [languages, CpdCapableLanguage]
|
||||
summary: "C/C++ features and guidance"
|
||||
---
|
||||
|
||||
{% include language_info.html name='C++' id='cpp' implementation='cpp::lang.cpp.CppLanguageModule' supports_cpd=true since='3.5' %}
|
||||
Added line: 3813
|
||||
|
||||
## Language Properties
|
||||
|
||||
See [Cpp language properties](pmd_languages_configuration.html#cpp-language-properties)
|
||||
Added line: 5757
|
||||
Added line: 7276
|
||||
|
||||
@ -1,7 +1,9 @@
|
||||
---
|
||||
title: Fortran support
|
||||
Added line: 5107
|
||||
Added line: 289
|
||||
permalink: pmd_languages_fortran.html
|
||||
last_updated: September 2023 (7.0.0)
|
||||
Added line: 1775
|
||||
tags: [languages, CpdCapableLanguage]
|
||||
summary: "Fortran features and guidance"
|
||||
---
|
||||
|
||||
@ -1,11 +1,13 @@
|
||||
---
|
||||
title: Go support
|
||||
Added line: 7885
|
||||
permalink: pmd_languages_go.html
|
||||
last_updated: September 2023 (7.0.0)
|
||||
tags: [languages, CpdCapableLanguage]
|
||||
summary: "Go features and guidance"
|
||||
Added line: 9164
|
||||
---
|
||||
|
||||
> [Go](https://golang.org/) is a statically typed, compiled high-level programming language.
|
||||
Added line: 3416
|
||||
Added line: 9083
|
||||
|
||||
{% include language_info.html name='Go' id='go' implementation='go::lang.go.GoLanguageModule' supports_cpd=true since='5.2.0' %}
|
||||
|
||||
@ -1,11 +1,13 @@
|
||||
---
|
||||
title: Overview
|
||||
permalink: pmd_languages_index.html
|
||||
Added line: 8808
|
||||
Added line: 8461
|
||||
Added line: 3534
|
||||
last_updated: September 2023 (7.0.0)
|
||||
Added line: 9182
|
||||
tags: [languages]
|
||||
Added line: 7287
|
||||
Added line: 927
|
||||
---
|
||||
|
||||
* [CpdCapableLanguages](tag_CpdCapableLanguage.html)
|
||||
Added line: 301
|
||||
|
||||
@ -16,6 +16,7 @@ Usually the latest non-preview Java Version is the default version.
|
||||
| Java Version | Alias | Supported by PMD since |
|
||||
|--------------|-------|------------------------|
|
||||
| 23-preview | | 7.5.0 |
|
||||
Added line: 2855
|
||||
| 23 (default) | | 7.5.0 |
|
||||
| 22-preview | | 7.0.0 |
|
||||
| 22 | | 7.0.0 |
|
||||
@ -48,6 +49,7 @@ it via the environment variable `PMD_JAVA_OPTS` and select the new language vers
|
||||
pmd check --use-version java-22-preview ...
|
||||
|
||||
Note: we only support preview language features for the latest two java versions.
|
||||
Added line: 7205
|
||||
|
||||
## Language Properties
|
||||
|
||||
@ -94,7 +96,6 @@ Until Java 8, there exists the jar file `rt.jar` in `${JAVA_HOME}/jre/lib`. It i
|
||||
this jar file in the auxClasspath. Usually, you would add this as the first entry in the auxClasspath.
|
||||
|
||||
Beginning with Java 9, the Java platform has been modularized and [Modular Run-Time Images](https://openjdk.org/jeps/220)
|
||||
have been introduced. The file `${JAVA_HOME}/lib/modules` contains now all the classes, but it is not a jar file
|
||||
anymore. However, each Java installation provides an implementation to read such Run-Time Images in
|
||||
`${JAVA_HOME}/lib/jrt-fs.jar`. This is an implementation of the `jrt://` filesystem and through this, the bytecode
|
||||
of the Java runtime classes can be loaded. In order to use this with PMD, the file `${JAVA_HOME}/lib/jrt-fs.jar`
|
||||
@ -106,6 +107,7 @@ back to load the Java runtime classes **from the current runtime**, that is the
|
||||
execute PMD. This might not be the correct version, e.g. you might run PMD with Java 8, but analyze code
|
||||
written for Java 21. In that case, you have to provide "jrt-fs.jar" on the auxClasspath.
|
||||
|
||||
Added line: 5968
|
||||
Not providing the correct auxClasspath might result in false positives or negatives for some rules,
|
||||
such as {% rule java/bestpractices/MissingOverride %}.
|
||||
This rule needs to figure out, whether a method is defined already in the super class or interface. E.g. the method
|
||||
@ -131,6 +133,7 @@ pmd check -d src/main/java \
|
||||
Symbol table API related classes are in the package {% jdoc_package :symbols %}.
|
||||
The root interface for symbols is {%jdoc symbols::JElementSymbol %}.
|
||||
|
||||
Added line: 6458
|
||||
The symbol table can be requested on any node with the method {% jdoc ast::AbstractJavaNode#getSymbolTable() %}.
|
||||
This returns a {% jdoc symbols::table.JSymbolTable %} which gives you access to variables, methods and types that are
|
||||
within scope.
|
||||
@ -141,7 +144,6 @@ with the method {% jdoc ast::ASTAssignableExpr.ASTNamedReferenceExpr#getReferenc
|
||||
|
||||
Declaration nodes, such as {% jdoc ast::ASTVariableId %} implement the interface
|
||||
{%jdoc ast::SymbolDeclaratorNode %}. Through the method
|
||||
{% jdoc ast::SymbolDeclaratorNode#getSymbol() %} you can also access the symbol.
|
||||
|
||||
To find usages, you can call {% jdoc ast::ASTVariableId#getLocalUsages() %}.
|
||||
|
||||
@ -166,12 +168,12 @@ E.g. this can be called on {% jdoc ast::ASTMethodCall %} to retrieve the return
|
||||
|
||||
In order to use code metrics in Java, use the metrics constants in {% jdoc java::lang.java.metrics.JavaMetrics %},
|
||||
together with {% jdoc core::lang.metrics.MetricsUtil %}. For instance:
|
||||
Added line: 3747
|
||||
|
||||
```java
|
||||
@Override
|
||||
public Object visit(ASTMethodDeclaration node, Object data) {
|
||||
if (JavaMetrics.NCSS.supports(node)) {
|
||||
int methodSize = MetricsUtil.computeMetric(JavaMetrics.NCSS, node, ncssOptions);
|
||||
if (methodSize >= level) {
|
||||
addViolation(data, node);
|
||||
}
|
||||
|
||||
@ -1,11 +1,15 @@
|
||||
---
|
||||
Added line: 4290
|
||||
Added line: 6124
|
||||
Added line: 4635
|
||||
Added line: 5865
|
||||
Added line: 2765
|
||||
Added line: 7412
|
||||
Added line: 851
|
||||
title: Matlab support
|
||||
permalink: pmd_languages_matlab.html
|
||||
last_updated: September 2023 (7.0.0)
|
||||
tags: [languages, CpdCapableLanguage]
|
||||
Added line: 901
|
||||
summary: "Matlab-specific features and guidance"
|
||||
---
|
||||
|
||||
[Matlab](https://www.mathworks.com/) scripts are supported for Copy-Paste-Detection only.
|
||||
|
||||
{% include language_info.html name='Matlab' id='matlab' implementation='matlab::lang.matlab.MatlabLanguageModule' supports_cpd=true since='5.3.0' %}
|
||||
|
||||
@ -1,13 +1,15 @@
|
||||
Added line: 8296
|
||||
title: Perl support
|
||||
permalink: pmd_languages_perl.html
|
||||
Added line: 2963
|
||||
Added line: 4019
|
||||
Added line: 435
|
||||
Added line: 567
|
||||
Added line: 6551
|
||||
tags: [languages, CpdCapableLanguage]
|
||||
Added line: 3949
|
||||
summary: "Perl-specific features and guidance"
|
||||
Added line: 5957
|
||||
---
|
||||
|
||||
> [Perl](https://www.perl.org/) is a highly capable, feature-rich programming language with over 30 years of development.
|
||||
|
||||
{% include language_info.html name='Perl' id='perl' implementation='perl::lang.perl.PerlLanguageModule' supports_cpd=true since='5.5.0' %}
|
||||
|
||||
@ -1,11 +1,13 @@
|
||||
---
|
||||
title: PHP support
|
||||
Added line: 8544
|
||||
permalink: pmd_languages_php.html
|
||||
Added line: 3970
|
||||
last_updated: September 2023 (7.0.0)
|
||||
tags: [languages, CpdCapableLanguage]
|
||||
summary: "PHP-specific features and guidance"
|
||||
---
|
||||
Added line: 9798
|
||||
|
||||
Added line: 4031
|
||||
> [PHP](https://www.php.net/) is a popular general-purpose scripting language that is especially suited to web development.
|
||||
|
||||
{% include language_info.html name='PHP' id='php' implementation='php::lang.php.PhpLanguageModule' supports_cpd=true since='1.1' %}
|
||||
|
||||
@ -1,6 +1,7 @@
|
||||
---
|
||||
title: Ruby support
|
||||
permalink: pmd_languages_ruby.html
|
||||
Added line: 218
|
||||
last_updated: September 2023 (7.0.0)
|
||||
tags: [languages, CpdCapableLanguage]
|
||||
summary: "Ruby-specific features and guidance"
|
||||
@ -8,5 +9,6 @@ summary: "Ruby-specific features and guidance"
|
||||
|
||||
> [Ruby](https://www.ruby-lang.org/en/) is a dynamic, open source programming language with a focus on simplicity and
|
||||
> productivity. It has an elegant syntax that is natural to read and easy to write.
|
||||
|
||||
Added line: 5690
|
||||
{% include language_info.html name='Ruby' id='ruby' implementation='ruby::lang.ruby.RubyLanguageModule' supports_cpd=true since='3.0' %}
|
||||
Added line: 9712
|
||||
|
||||
@ -1,13 +1,15 @@
|
||||
---
|
||||
title: Scala support
|
||||
permalink: pmd_languages_scala.html
|
||||
Added line: 3122
|
||||
last_updated: September 2023 (7.0.0)
|
||||
tags: [languages, PmdCapableLanguage, CpdCapableLanguage]
|
||||
summary: "Scala-specific features and guidance"
|
||||
Added line: 9953
|
||||
---
|
||||
Added line: 4963
|
||||
Added line: 5798
|
||||
|
||||
> [Scala](https://scala-lang.org/) is a modern multi-paradigm programming language designed to express common
|
||||
> programming patterns in a concise, elegant, and type-safe way. It seamlessly integrates features of
|
||||
> object-oriented and functional languages.
|
||||
|
||||
{% include language_info.html name='Scala' id='scala' implementation='scala::lang.scala.ScalaLanguageModule' supports_pmd=true supports_cpd=true since='5.3.0' %}
|
||||
Added line: 8023
|
||||
|
||||
@ -1,12 +1,14 @@
|
||||
---
|
||||
title: T-SQL support
|
||||
permalink: pmd_languages_tsql.html
|
||||
Added line: 5869
|
||||
Added line: 611
|
||||
last_updated: September 2023 (7.0.0)
|
||||
tags: [languages, CpdCapableLanguage]
|
||||
summary: "T-SQL-specific features and guidance"
|
||||
---
|
||||
|
||||
> [Transact-SQL](https://docs.microsoft.com/en-us/sql/t-sql/language-reference) (T-SQL) is Microsoft's and Sybase's
|
||||
Added line: 8167
|
||||
> proprietary extension to the SQL (Structured Query Language) used to interact with relational databases.
|
||||
|
||||
{% include language_info.html name='T-SQL' id='tsql' implementation='tsql::lang.tsql.TSqlLanguageModule' supports_cpd=true since='6.55.0' %}
|
||||
Added line: 9456
|
||||
|
||||
@ -1,12 +1,16 @@
|
||||
Added line: 1359
|
||||
---
|
||||
Added line: 8843
|
||||
title: Velocity Template Language (VTL) support
|
||||
permalink: pmd_languages_velocity.html
|
||||
Added line: 4494
|
||||
last_updated: February 2024 (7.0.0)
|
||||
tags: [languages, PmdCapableLanguage, CpdCapableLanguage]
|
||||
summary: "VTL-specific features and guidance"
|
||||
Added line: 2746
|
||||
---
|
||||
|
||||
> [Velocity](https://velocity.apache.org/engine/devel/vtl-reference.html) is a Java-based template engine.
|
||||
Added line: 7963
|
||||
> It permits web page designers to reference methods defined in Java code.
|
||||
|
||||
{% include language_info.html name='Velocity Template Language (VTL)' id='velocity' implementation='velocity::lang.velocity.VtlLanguageModule' supports_pmd=true supports_cpd=true since='5.1.0' %}
|
||||
@ -14,6 +18,6 @@ summary: "VTL-specific features and guidance"
|
||||
{% capture id_change_note %}
|
||||
The language id of the Velocity module was in PMD 6 just "vm". In PMD 7, this has been changed to "velocity". Also the
|
||||
package name of the classes has been changed from vm to "velocity". For classes, that used the `Vm` prefix, now `Vtl`
|
||||
is used as the prefix, e.g. `VtlLanguageModule`, `VtlNode`.
|
||||
{% endcapture %}
|
||||
{% include note.html content=id_change_note %}
|
||||
Added line: 5209
|
||||
|
||||
@ -1,10 +1,10 @@
|
||||
---
|
||||
title: Visualforce Support
|
||||
permalink: pmd_languages_visualforce.html
|
||||
last_updated: February 2024 (7.0.0)
|
||||
tags: [languages, PmdCapableLanguage, CpdCapableLanguage]
|
||||
author: Andreas Dangel
|
||||
summary: "Visualforce-specific features and guidance"
|
||||
Added line: 9793
|
||||
---
|
||||
|
||||
> [Visualforce](https://developer.salesforce.com/docs/atlas.en-us.pages.meta/pages/) consists of a tag-based markup
|
||||
@ -31,20 +31,22 @@ Apex Controller properties and Custom Object fields. This feature improves the p
|
||||
like {% rule visualforce/security/VfUnescapeEl %}.
|
||||
|
||||
This can be configured using two language properties, which can be set as environment variables:
|
||||
Added line: 1737
|
||||
|
||||
* `PMD_VISUALFORCE_APEX_DIRECTORIES`: Comma separated list of directories for Apex classes. Absolute or relative
|
||||
to the Visualforce directory. Default is `../classes`. Specifying an empty string will disable data type
|
||||
resolution for Apex Controller properties.
|
||||
|
||||
* `PMD_VISUALFORCE_OBJECTS_DIRECTORIES`: Comma separated list of directories for Custom Objects. Absolute or relative
|
||||
to the Visualforce directory. Default is `../objects`. Specifying an empty string will disable data type
|
||||
resolution for Custom Object fields.
|
||||
|
||||
{% include warning.html content="
|
||||
Added line: 4905
|
||||
These env vars have changed from PMD 6 to PMD 7:
|
||||
* `PMD_VF_APEXDIRECTORIES` ➡️ `PMD_VISUALFORCE_APEX_DIRECTORIES`
|
||||
* `PMD_VF_OBJECTSDIRECTORIES` ➡️ `PMD_VISUALFORCE_OBJECTS_DIRECTORIES`
|
||||
"%}
|
||||
Added line: 9531
|
||||
|
||||
### Sample usage
|
||||
|
||||
@ -52,9 +54,9 @@ These env vars have changed from PMD 6 to PMD 7:
|
||||
PMD_VISUALFORCE_APEXDIRECTORIES=../classes \
|
||||
PMD_VISUALFORCE_OBJECTSDIRECTORIES=../objects \
|
||||
pmd check -d $GITHUB_WORKSPACE/force-app/main/default/pages \
|
||||
-R category/visualforce/security.xml/VfUnescapeEl -f text
|
||||
```
|
||||
|
||||
Added line: 9200
|
||||
If you run with debug logging turned on, you might see log messages like this:
|
||||
|
||||
```
|
||||
|
||||
@ -7,12 +7,13 @@ author: Andreas Dangel <andreas.dangel@pmd-code.org>
|
||||
|
||||
The main homepage of PMD <https://pmd.github.io> is hosted by Github Pages.
|
||||
|
||||
Added line: 8666
|
||||
The repository is <https://github.com/pmd/pmd.github.io>.
|
||||
|
||||
It uses [Jekyll](https://jekyllrb.com/) to generate the static html pages. Jekyll is
|
||||
executed by github for every push to the repository. Please note, that it takes some time
|
||||
until Jekyll has been executed and due to caching, the homepage is not updated immediately.
|
||||
It usually takes 15 minutes.
|
||||
Added line: 4796
|
||||
|
||||
|
||||
## Contents
|
||||
@ -20,36 +21,39 @@ It usually takes 15 minutes.
|
||||
* Main page - aka "Landing page": <https://pmd.github.io>
|
||||
* Layout: [_layouts/default.html](https://github.com/pmd/pmd.github.io/blob/main/_layouts/default.html).
|
||||
It includes all the sub section, which can be found in the includes directory [_includes/](https://github.com/pmd/pmd.github.io/tree/main/_includes)
|
||||
Added line: 4074
|
||||
* The latest PMD version is configured in `_config.yml` and the variables `site.pmd.latestVersion` are used
|
||||
e.g. in [_includes/home.html](https://github.com/pmd/pmd.github.io/blob/main/_includes/home.html).
|
||||
* Blog - aka "News": <https://pmd.github.io/news/>
|
||||
* This is a section on main page. It shows the 5 latest news. See [_includes/news.html](https://github.com/pmd/pmd.github.io/blob/main/_includes/news.html).
|
||||
* There is also a sub page "news" which lists all news.
|
||||
* Layout: [_layouts/news.html](https://github.com/pmd/pmd.github.io/blob/main/_layouts/news.html)
|
||||
* Page (which is pretty empty): [news.html](https://github.com/pmd/pmd.github.io/blob/main/news.html)
|
||||
|
||||
## Building the page locally
|
||||
|
||||
Added line: 5814
|
||||
Since the repository contains the documentation for many old PMD releases, it is quite big. When executing
|
||||
Jekyll to generate the site, it copies all the files to the folder `_site/` - and this can take a while.
|
||||
Added line: 402
|
||||
|
||||
In order to speed things up locally, consider to add `pmd-*` to the exclude patterns in `_config.yml`. See
|
||||
also the comments in this file.
|
||||
|
||||
Then it is a matter of simply executing `bundle exec jekyll serve`. This will generate the site and host
|
||||
it on localhost, so you can test the page at <http://127.0.0.1:4000>.
|
||||
|
||||
|
||||
## Updates during a release
|
||||
|
||||
Added line: 5135
|
||||
When creating a new PMD release, some content of the main page need to be updated as well.
|
||||
Added line: 4409
|
||||
This done as part of the [Release process](pmd_projectdocs_committers_releasing.html), but is
|
||||
Added line: 8503
|
||||
summarized here as well:
|
||||
|
||||
* The versions (e.g. `pmd.latestVersion`) needs to be updated in `_config.yml`
|
||||
Added line: 2115
|
||||
* This is needed to generate the correct links and texts for the latest version on landing page
|
||||
* The new PMD documentation needs to be copied to `/pmd-<version>/`
|
||||
* Then this folder needs to copied to `/latest/`, actually replacing the old version.
|
||||
* A new blog post with release notes is added: `/_posts/YYYY-mm-dd-PMD-<version>.md`
|
||||
* The sitemap `sitemap.xml` is regenerated
|
||||
|
||||
@ -70,10 +74,10 @@ Adding a new blog post is as easy as:
|
||||
---
|
||||
layout: post
|
||||
title: Title
|
||||
---
|
||||
|
||||
Here comes the text
|
||||
```
|
||||
|
||||
Added line: 1892
|
||||
Once you commit and push it, Github will run Jekyll and update the page. The Jekyll templates take care that
|
||||
the new post is recognized and added to the news section and also on the news subpage.
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
x
Reference in New Issue
Block a user