New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add since version to Checkstyle documentation #4475

Closed
rnveach opened this Issue Jun 20, 2017 · 9 comments

Comments

Projects
None yet
3 participants
@rnveach
Member

rnveach commented Jun 20, 2017

Taken from #4467 (comment) ,

Users are always trying to add new modules/properties before they are even released or with older versions of Checkstyle.
We should add a new column in our xdocs, since and display what version of checkstyle the property was added.

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-checkstyle-plugin:2.17:check (checkstyle) on project [PROJECT_NAME]: Failed during checkstyle configuration: cannot initialize module TreeWalker - Property 'illegalClasses' in module IllegalImport does not exist, please check the documentation -> [Help 1]

This message and any similar message should also be expanded to tell the user to check/compare their version they are using.

@rnveach rnveach added the approved label Jun 20, 2017

@rnveach rnveach self-assigned this Jun 20, 2017

@MEZk

This comment has been minimized.

Show comment
Hide comment
@MEZk

MEZk Jun 21, 2017

Contributor

@rnveach

  1. The new column in xdoc should be verified by the UT. I think that we should also require to put the version to Javadoc. For example, as Spring does. For this purpose we can use @since tag.
  2. Existing xdoc and javadoc should be updated as well, I guess.
Contributor

MEZk commented Jun 21, 2017

@rnveach

  1. The new column in xdoc should be verified by the UT. I think that we should also require to put the version to Javadoc. For example, as Spring does. For this purpose we can use @since tag.
  2. Existing xdoc and javadoc should be updated as well, I guess.
@rnveach

This comment has been minimized.

Show comment
Hide comment
@rnveach

rnveach Jun 21, 2017

Member

Here is the little utility I made to find the versions of CS that support a specific module/property.
https://github.com/rnveach/checkstyle/commits/version_regression

Here is the results of the run with debug on: http://rveach.no-ip.org/checkstyle/version_output_with_debug.zip
Here is the results without debug: http://rveach.no-ip.org/checkstyle/version_output.zip
They show all modules, their properties, and what versions they were found in (sorted).

It scanned versions between 5.7 and 7.8.2 (47 versions in total).
I had to drop version 6.7 from the scan, because it had a bug with exceptions. It never displayed them, so it was impossible to tell the cause of any failures.
Oddly the versions between 6.12 and 6.14.1 kept getting random, unexplained timeout issues. This happened 174 times, out of 73k+ runs.
severity properties aren't reliable for testing if the module exists because an exception happens first in ConfigurationLoader before we can even get to trying to instantiate the module and populate the property. Assigning a true value for severity could alleviate this issue in the program. It seems to be the only property that has this behavior this.

Let me know if you think we should expand more before 5.7 and I will try to create all JARs for them to run on. 134 modules, out of 162, were found to have started in 5.7 .

The new column in xdoc should be verified by the UT.

I plan this.

I think that we should also require to put the version to Javadoc.

I think we should create a new check for this if one doesn't exist. It will probably be made for GSoC.

Member

rnveach commented Jun 21, 2017

Here is the little utility I made to find the versions of CS that support a specific module/property.
https://github.com/rnveach/checkstyle/commits/version_regression

Here is the results of the run with debug on: http://rveach.no-ip.org/checkstyle/version_output_with_debug.zip
Here is the results without debug: http://rveach.no-ip.org/checkstyle/version_output.zip
They show all modules, their properties, and what versions they were found in (sorted).

It scanned versions between 5.7 and 7.8.2 (47 versions in total).
I had to drop version 6.7 from the scan, because it had a bug with exceptions. It never displayed them, so it was impossible to tell the cause of any failures.
Oddly the versions between 6.12 and 6.14.1 kept getting random, unexplained timeout issues. This happened 174 times, out of 73k+ runs.
severity properties aren't reliable for testing if the module exists because an exception happens first in ConfigurationLoader before we can even get to trying to instantiate the module and populate the property. Assigning a true value for severity could alleviate this issue in the program. It seems to be the only property that has this behavior this.

Let me know if you think we should expand more before 5.7 and I will try to create all JARs for them to run on. 134 modules, out of 162, were found to have started in 5.7 .

The new column in xdoc should be verified by the UT.

I plan this.

I think that we should also require to put the version to Javadoc.

I think we should create a new check for this if one doesn't exist. It will probably be made for GSoC.

@MEZk

This comment has been minimized.

Show comment
Hide comment
@MEZk

MEZk Jun 21, 2017

Contributor

@rnveach

I think we should create a new check for this if one doesn't exist. It will probably be made for GSoC.

Probably we could use WriteTag, but it does not support class fields and getters, setters.

Contributor

MEZk commented Jun 21, 2017

@rnveach

I think we should create a new check for this if one doesn't exist. It will probably be made for GSoC.

Probably we could use WriteTag, but it does not support class fields and getters, setters.

@romani

This comment has been minimized.

Show comment
Hide comment
@romani

romani Jun 21, 2017

Member

Please avoid usage of WriteTag, it is badly designed and will be reimplemented or even completely removed, we should have an issue on it already

Member

romani commented Jun 21, 2017

Please avoid usage of WriteTag, it is badly designed and will be reimplemented or even completely removed, we should have an issue on it already

@romani

This comment has been minimized.

Show comment
Hide comment
@romani

romani Jun 21, 2017

Member

Let me know if you think we should expand more before 5.7

I would be ideal, but I do not think it is reasonable.
the most recent updates are at http://checkstyle.sourceforge.net/releasenotes.html [5.8-.....)
in since we can define "5.8 or early"

FYI. I keep in web hosting all previous web sites, for all recent versions [5.8-.....) , I had a dream to make some update in web site and allow users to look at previous version websites for documentation.
If smb want to help with this and know how to make it conveniently for users and for us to support, let me know and probably we can make issue on this.

Member

romani commented Jun 21, 2017

Let me know if you think we should expand more before 5.7

I would be ideal, but I do not think it is reasonable.
the most recent updates are at http://checkstyle.sourceforge.net/releasenotes.html [5.8-.....)
in since we can define "5.8 or early"

FYI. I keep in web hosting all previous web sites, for all recent versions [5.8-.....) , I had a dream to make some update in web site and allow users to look at previous version websites for documentation.
If smb want to help with this and know how to make it conveniently for users and for us to support, let me know and probably we can make issue on this.

@rnveach

This comment has been minimized.

Show comment
Hide comment
@rnveach

rnveach Jun 22, 2017

Member

Let me know if you think we should expand more before 5.7

It would be ideal

Currently the process needs all jars. Running with non-all JAR would be a little complicated right now to manually include all dependencies.

5.2 and 5.3 was built from source with minor changes. I will examine for differences.

5.4 to 5.6 can't be built from source. I get the following error:
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-site-plugin:3.0-beta-3:site (gen-site) on project checkstyle: Execution gen-site of goal org.apache.maven.plugins:maven-site-plugin:3.0-beta-3:site failed: A required class was missing while executing org.apache.maven.plugins:maven-site-plugin:3.0-beta-3:site: org/sonatype/aether/graph/DependencyFilter
I hacked the POMs a little and generated jars for these versions.

5.0 to 5.2 don't exist as a tag.
4.3 to 4.4 doesn't do normal package correctly from source as is. Empty jar is created.
4.2 has no POM.

Edit:
I identified commits for the missing tags, but 5.0 and 5.1 can't package normal either.
5.2 was successfully created.

Edit 2:
I see 5.2 and older use an ANT build script, so I am creating the JARs using that.

Member

rnveach commented Jun 22, 2017

Let me know if you think we should expand more before 5.7

It would be ideal

Currently the process needs all jars. Running with non-all JAR would be a little complicated right now to manually include all dependencies.

5.2 and 5.3 was built from source with minor changes. I will examine for differences.

5.4 to 5.6 can't be built from source. I get the following error:
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-site-plugin:3.0-beta-3:site (gen-site) on project checkstyle: Execution gen-site of goal org.apache.maven.plugins:maven-site-plugin:3.0-beta-3:site failed: A required class was missing while executing org.apache.maven.plugins:maven-site-plugin:3.0-beta-3:site: org/sonatype/aether/graph/DependencyFilter
I hacked the POMs a little and generated jars for these versions.

5.0 to 5.2 don't exist as a tag.
4.3 to 4.4 doesn't do normal package correctly from source as is. Empty jar is created.
4.2 has no POM.

Edit:
I identified commits for the missing tags, but 5.0 and 5.1 can't package normal either.
5.2 was successfully created.

Edit 2:
I see 5.2 and older use an ANT build script, so I am creating the JARs using that.

@romani

This comment has been minimized.

Show comment
Hide comment
@romani

romani Jun 22, 2017

Member

No need to go below 5.0 , as it was major update, I doubt that smb use us below 5.0 .

Member

romani commented Jun 22, 2017

No need to go below 5.0 , as it was major update, I doubt that smb use us below 5.0 .

@rnveach

This comment has been minimized.

Show comment
Hide comment
@rnveach

rnveach Jun 24, 2017

Member

I updated the extract files with regression all the way back to 3.1.
3.0 doesn't have severity to ignore violations produced by check.
2.X doesn't support configuration files, doesn't have separate checks, and must be configured through system properties.

I will begin making the PR.

Member

rnveach commented Jun 24, 2017

I updated the extract files with regression all the way back to 3.1.
3.0 doesn't have severity to ignore violations produced by check.
2.X doesn't support configuration files, doesn't have separate checks, and must be configured through system properties.

I will begin making the PR.

rnveach added a commit to rnveach/checkstyle that referenced this issue Jun 25, 2017

rnveach added a commit to rnveach/checkstyle that referenced this issue Jun 25, 2017

romani added a commit that referenced this issue Jun 26, 2017

rnveach added a commit to rnveach/checkstyle that referenced this issue Jun 30, 2017

rnveach added a commit to rnveach/checkstyle that referenced this issue Jun 30, 2017

rnveach added a commit to rnveach/checkstyle that referenced this issue Jun 30, 2017

rnveach added a commit to rnveach/checkstyle that referenced this issue Jun 30, 2017

romani added a commit that referenced this issue Jun 30, 2017

@romani romani added this to the 8.0 milestone Jun 30, 2017

@romani

This comment has been minimized.

Show comment
Hide comment
@romani

romani Jun 30, 2017

Member

fix is merged

Member

romani commented Jun 30, 2017

fix is merged

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment