doc: improve CONTRIBUTING.md #14514

nrmancuso · 2024-02-21T04:58:26Z

Improves the CONTRIBUTING.md file, README.md file, and creates the GSOC.md file for GSoC participants. Make sure to "View File" on each to see rendered markdown content.

GH Views:
https://github.com/nrmancuso/checkstyle/blob/contributing/.github/CONTRIBUTING.md
https://github.com/nrmancuso/checkstyle/blob/contributing/.github/GSOC.md
https://github.com/nrmancuso/checkstyle/blob/contributing/README.md

romani

one item:

romani · 2024-02-23T14:13:53Z

.github/CONTRIBUTING.md

+    [Issues Page](https://github.com/checkstyle/checkstyle/issues). We
+    have a few issues labeled as
+    https://github.com/checkstyle/checkstyle/labels/good%20first%20issue to
+    help you get started.


please mention here second, third, .... We rank them on purpose to increase complexity slowly.
Such issues are for all contributors.

romani

Ok to merge.
Thanks a lot

rnveach

Reviewed first document.

rnveach · 2024-02-24T20:27:19Z

.github/CONTRIBUTING.md

-* [Pull Request Template](https://github.com/checkstyle/checkstyle/blob/master/.github/PULL_REQUEST_TEMPLATE.md)
+ - Please see the [CheckStyle Documentation](https://checkstyle.org/beginning_development.html)
+    for information on how to get started with the project. This includes setting up your
+    development environment, building the project, and running tests.


I didn't see anything about running tests in the beginning development, but I think we should add it to there and not change this line.
Is this referencing the mvn install command?

I was referring to mvn clean verify, but wanted to keep this general enough to allow us to change the beginning development document.

I am going to say that this should be covered by #14542 as well. It wasn't very easy finding the commands with this text.

rnveach · 2024-02-24T20:31:30Z

.github/CONTRIBUTING.md

+    for information on how to get started with the project. This includes setting up your
+    development environment, building the project, and running tests.
+ - Take a look at the [Contribution Guidelines](https://checkstyle.org/contributing.html) for
+    on how to contribute to the project.


I find it odd that beginning_development.html has instructions on pushing, but then we go into contributing, which is really where the pushing instructions should be IMO. Then it is also odd contributing has build instructions but then we already went over beginning_development.html which has those instructions.

Some of the commands in contributing are also not in beginning_development.html.

Yeah, this does need improvement. Let me think on how to separate and improve this.

We can clean all this up in the scope of #14542

Please make sure to mention that this page needs to be re-updated when we change the other pages.

rnveach · 2024-02-24T20:32:49Z

.github/CONTRIBUTING.md

+    development environment, building the project, and running tests.
+ - Take a look at the [Contribution Guidelines](https://checkstyle.org/contributing.html) for
+    on how to contribute to the project.
+ - Select an issue to work on from the


I think we should have a document for the labels. You mention first/second issue, but don't mention easy and approved. Both are very important to mention as new users gloss over approved on issues and jump the gun.

If we are getting rid of any old labels like easy, then we should do that.

easy needs to go in my opinion. I have never liked this label, I remember when I started out here and struggled for a long time on an easy issue. easy is highly subjective to both experience with software development in general AND experience with the project.

first, second, third, etc. is good. Even something like good beginner issue or even simple might be ok. easy is likely to make people feel discouraged if they are struggling with it (I know that I did).

Issue to improve:
#14541

@nrmancuso Were you thinking adding text for approved will be in other issue? I was not seeing it added yet. I can understand moving the other labels to the issue as there is more to work on, but I think approved is pretty much solidified and understood from maintainers and it definitely needs to be conveyed to contributors.

yeah, good point, done

I think the new Select an issue to work on from the Issues Page is too bloated for a bullet. Bullets should be shorter and more to the point, maybe 1-2 sentences, 3 at most. I think this clearly shows that this bullet needs to be its own section "Selecting an Issue to Contribute To" (or some form). I think the mention of the approved label should be in the first 2 sentences.

Edit: If we start this new section, "I am on it" should probably be moved to it.

.github/CONTRIBUTING.md

rnveach · 2024-02-24T20:44:36Z

.github/CONTRIBUTING.md

+
+ - **Read our pull request rules.** See [PR Rules](https://github.com/checkstyle/checkstyle/wiki/PR-rules).
+ - **Comment on the issue.** If you are working on an existing issue, please comment on the issue
+    to let others know that you are working on it ("I am on it.").


I think this left open ended on what if there is no existing issue.

Also this point should first. PR rules was created for already opened PRs and should probably be last.

Maybe also make a point re pointing to https://checkstyle.org/contributing.html#Submitting_your_contribution and https://checkstyle.org/beginning_development.html#Starting_Development where we talk about remotes and branches? I think some work needs to be done with the external pages some. Things are a bit all over the place.

I think this left open ended on what if there is no existing issue.

fixed

Maybe also make a point re pointing to

I would like to keep this as concise as possible and avoid repetition

fixed

I am sorry, I am not seeing how this one is fixed.

.github/CONTRIBUTING.md

rnveach

Additional comment.

.github/CONTRIBUTING.md

rnveach · 2024-02-25T15:04:12Z

https://github.com/nrmancuso/checkstyle/blob/contributing/.github/CONTRIBUTING.md

I found an easier way to link to the view of the page. I am going to put this in the first post.

nrmancuso · 2024-02-25T16:13:05Z

https://github.com/nrmancuso/checkstyle/blob/contributing/.github/CONTRIBUTING.md

I found an easier way to link to the view of the page. I am going to put this in the first post.

Ah, cool, I didn't know about this. Nice to have a link that doesn't get outdated.

rnveach · 2024-02-26T17:34:15Z

https://github.com/nrmancuso/checkstyle/blob/contributing/.github/GSOC.md

rnveach · 2024-02-26T17:39:58Z

.github/GSOC.md

+   2. Join the Checkstyle group on [Google Groups](https://groups.google.com/forum/#!forum/checkstyle).
+      This is another place to ask questions and get to know the community.
+3. **Start contributing.** We have a list of issues labeled as
+   https://github.com/checkstyle/checkstyle/labels/good%20first%20issue. These are a great place to


This and some other things seem like a re-hash of https://github.com/nrmancuso/checkstyle/blob/contributing/.github/CONTRIBUTING.md#rocket-getting-started and such.

Why don't we move everything from here talking about general contributions and such, and move it to CONTRIBUTING and this page only contain extremely GSOC specific things. We should be able to link to the other MD pages like I did above.

Get to know the project shouldn't be GSOC specific. I am ok with join the community. I mentioned labels.

rnveach · 2024-02-26T17:42:54Z

.github/GSOC.md

+   great for GSoC. You can find them in our wiki [Checkstyle Wiki](https://github.com/checkstyle/checkstyle/wiki).
+   You can also propose your own project idea. We are open to new ideas and would love to hear
+   what you are interested in working on.
+5. **Create a Draft Proposal.** Once you have a good understanding of the project and have an idea


I am not seeing anything about timing. One concern I see is new people just thinking they "joined" and will start submitting proposals. They need to do X issues / PRs first to show they have an understanding of CS and our flow. Shouldn't they then be talking to us a little bit about the projects before jumping into the proposal?

rnveach · 2024-02-26T17:43:33Z

.github/GSOC.md

+   more challenging issues, like bug fixes and new features.
+4. **Take a Look at Our Project Ideas.** We have a list of project ideas that we think would be
+   great for GSoC. You can find them in our wiki [Checkstyle Wiki](https://github.com/checkstyle/checkstyle/wiki).
+   You can also propose your own project idea. We are open to new ideas and would love to hear


@romani

You can also propose your own project idea.

You are ok with this?

I don't think this should be explicitly worded. We can discuss all and everything, but project for gsoc is very complicated process.

What are we afraid of here? It’s not clear to me why we would not encourage this.

rnveach · 2024-02-26T17:46:04Z

.github/GSOC.md

+6. **Submit Your Proposal.** Now that you have refined your proposal, submit it through the
+   GSoC website **before the final submission deadline**.
+
+## :star: Additional Tips


I find it odd that this tips section is right between 2 proposals pieces. Its like you are cutting your thought in half and putting something else between them. I think this should probably be moved more to the end.

Also I think the Contribute bullet is what I recommended above for another section.

rnveach · 2024-02-26T17:49:13Z

.github/GSOC.md

+
+All projects aim to solve a problem or improve something. Start your proposal by introducing the
+problem you are trying to solve or the improvement you are trying to make. This is your opportunity
+to show us that you understand the problem, why it is important, and why it is worth solving.


why it is important

why it should be important to the maintainers ?

rnveach · 2024-02-26T17:51:55Z

.github/GSOC.md

+Include any relevant background information that will help us understand the problem, like
+statistics, examples, references to existing issues, etc.
+
+#### Project Goals


~~It isn't mentioned the time table. How long for each deliverable/milestone.~~ There is a timeline section, so my point is somewhat pointless, but it also seems like to provide a timeline you have to resay what the deliverables/milestones are.

Also this section seems to be more questions than guidance, like you are almost saying some things are optional.

rnveach · 2024-02-26T17:55:01Z

.github/GSOC.md

+
+#### Implementation Plan
+
+Describe your solution to the problem. This should include a high-level overview of the


How technical should this plan be?

rnveach · 2024-02-26T17:56:57Z

.github/GSOC.md

+#### Timeline
+
+Show us that you can break down your project into manageable tasks and that you have a clear plan
+for how you will accomplish your goals. This should be a timeline that shows what you will be


I find it odd you ask for how you will accomplish your goals but then turn around and say this is a timeline. The "HOW" should be the Implementation Plan, this section should be only about what we will get and when.

rnveach · 2024-02-26T17:58:03Z

.github/GSOC.md

+Show us that you can break down your project into manageable tasks and that you have a clear plan
+for how you will accomplish your goals. This should be a timeline that shows what you will be
+working on each week. It should include milestones and deliverables. An effective way to present
+this is in a table or a Gantt chart.


For me, I am not familar with Gantt chart by name. You think it may be beneficial to link to wikipedia or something to show an example of what you want?

rnveach · 2024-02-26T18:05:09Z

.github/GSOC.md

+  We want to see that you have a clear plan.
+- **Be Professional.** We are looking for a proposal that is well-written and professional.
+- **One Proposal <-> One Project.** Do not create a proposal that spans multiple projects.
+- **Proposal Title** If creating a proposal based on our project ideas, please use the title of the


Why is this one a tip and not a requirement? There is nothing here that seems subjective. I consider a tip something that is beneficial but can be ignored (but probably unwise).

rnveach · 2024-02-26T18:06:48Z

https://github.com/nrmancuso/checkstyle/blob/contributing/README.md

rnveach · 2024-02-26T18:14:15Z

.github/GSOC.md

+What are your career goals? What do you hope to get out of GSoC? What do you hope to contribute to
+Checkstyle? This is your opportunity to show us that you are a good fit for the project and that
+you are excited to work with us. **You must include a list of links to your Checkstyle contributions
+to be considered for GSoC; this is one of the most important selection criteria.**


Should we also mention that they should specify partial and complete contributions?

I also find it odd again with all the questions and then ending with "You must include". Maybe consider splitting this into 2 paragraphs, 1 for optional and the other for required.

rnveach · 2024-02-26T18:17:53Z

README.md


-[Explanation on how to create your own module](https://checkstyle.org/extending.html)
+- Download our [Latest Release](https://github.com/checkstyle/checkstyle/releases/) from GitHub.
+- Add Checkstyle to your build from [Maven Central](https://search.maven.org/search?q=g:%22com.puppycrawl.tools%22%20AND%20a:%22checkstyle%22).


https://central.sonatype.com/search?q=g:%22com.puppycrawl.tools%22%20%20a:%22checkstyle%22&smo=true

Showing 0 results out of the 594054 available packages

I am not sure I understand the purpose of this link.

rnveach · 2024-02-26T18:20:49Z

README.md

-[Explanation on how to create your own module](https://checkstyle.org/extending.html)
+- Download our [Latest Release](https://github.com/checkstyle/checkstyle/releases/) from GitHub.
+- Add Checkstyle to your build from [Maven Central](https://search.maven.org/search?q=g:%22com.puppycrawl.tools%22%20AND%20a:%22checkstyle%22).
+- Read our [Documentation](https://checkstyle.org/checks.html) for usage and configuration.


Before this item should probably be something on running. https://checkstyle.org/running.html

rnveach · 2024-02-26T18:21:39Z

README.md

+[Contribution Guidelines](https://github.com/checkstyle/checkstyle/blob/master/.github/CONTRIBUTING.md)
+for information on how to contribute to the project. This includes creating issues, submitting pull
+requests, and setting up your development environment. **If you are a potential Google Summer
+of Code (GSoC) participant, this is a great place to start.**


So we don't want to tell them about the new GSOC MD page?

rnveach · 2024-02-26T18:25:45Z

README.md


-[Setup IDE for development](https://checkstyle.org/beginning_development.html)
+## Quick Start


This is probably a good first pass, but I feel quick start is way too quick. Usually I like to see small and quick examples and such on the README on how to use the repo. I usually go to documentation afterwards once I am looking for more complex or specific items.

rnveach · 2024-02-27T20:20:47Z

.github/GSOC.md

+working on each week. It should include milestones and deliverables. An effective way to present
+this is in a table or a Gantt chart.
+
+#### About You


We usually ask GSOC participants what days and times they are available for communication/work so we can plan collaboration days, answer questions faster, or get an idea of when progress will be made.

nrmancuso force-pushed the contributing branch 5 times, most recently from 97a8b2c to a4bedbb Compare February 23, 2024 03:46

nrmancuso self-assigned this Feb 23, 2024

nrmancuso force-pushed the contributing branch from a4bedbb to 04b7219 Compare February 23, 2024 05:33

nrmancuso marked this pull request as ready for review February 23, 2024 05:33

nrmancuso requested review from romani and rnveach February 23, 2024 05:33

nrmancuso removed their assignment Feb 23, 2024

romani requested changes Feb 23, 2024

View reviewed changes

nrmancuso force-pushed the contributing branch from 04b7219 to 74279d2 Compare February 24, 2024 14:15

romani approved these changes Feb 24, 2024

View reviewed changes

romani assigned rnveach Feb 24, 2024

This comment was marked as outdated.

Sign in to view

rnveach requested changes Feb 24, 2024

View reviewed changes

.github/CONTRIBUTING.md Outdated Show resolved Hide resolved

nrmancuso force-pushed the contributing branch 2 times, most recently from 7f420ee to 0348f11 Compare February 25, 2024 14:38

nrmancuso added 3 commits February 25, 2024 10:03

doc: improve CONTRIBUTING.md

1ad040a

doc: improve README.md

68d3186

doc: gsoc contributor guide

5c637b8

nrmancuso force-pushed the contributing branch from 0348f11 to 5c637b8 Compare February 25, 2024 15:03

rnveach requested changes Feb 26, 2024

View reviewed changes

rnveach reviewed Feb 26, 2024

View reviewed changes

rnveach requested changes Feb 26, 2024

View reviewed changes

rnveach requested changes Feb 27, 2024

View reviewed changes

rnveach added the awaiting changes label Mar 4, 2024

romani assigned nrmancuso and unassigned rnveach Mar 12, 2024

nrmancuso mentioned this pull request Apr 29, 2024

Please, add a small section to the README on how to install and use this tool #14838

Open


		#### Implementation Plan

		Describe your solution to the problem. This should include a high-level overview of the


		[Setup IDE for development](https://checkstyle.org/beginning_development.html)
		## Quick Start

doc: improve CONTRIBUTING.md #14514

Are you sure you want to change the base?

doc: improve CONTRIBUTING.md #14514

Conversation

nrmancuso commented Feb 21, 2024 • edited by rnveach

romani left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

romani left a comment

Choose a reason for hiding this comment

This comment was marked as outdated.

rnveach left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rnveach Feb 26, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nrmancuso Feb 25, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rnveach left a comment

Choose a reason for hiding this comment

rnveach commented Feb 25, 2024

nrmancuso commented Feb 25, 2024

rnveach commented Feb 26, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rnveach commented Feb 26, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nrmancuso commented Feb 21, 2024 •

edited by rnveach

rnveach Feb 26, 2024 •

edited

nrmancuso Feb 25, 2024 •

edited