search

pygame-community / pygame-ce

🐍🎮 pygame - Community Edition is a FOSS Python library for multimedia applications (like games). Built on top of the excellent SDL library.
https://pyga.me
767 stars 120 forks source link

Addition of CONTRIBUTING.md for project repo #2892

Closed MrF1ow closed 2 weeks ago

MrF1ow commented 1 month ago

Why Change was Made

Sifting through all the project docs to figure out how to contribute was a bit of a maze. It took some digging and hopping between wiki pages to find what I needed. But, I realized that having everything I need in one spot would've made life a whole lot easier for me and other contributors, old and new. It's like a roadmap that guides you straight to the goods without all the detours. So, consolidating all that vital info in one place really sets the stage for a smoother ride for everyone involved!

Why pygame CE should accept changes

If pygame CE accepts these changes, I know that it will speed-up the onboarding process for contributors, making it more inviting for new folks to jump in and for seasoned contributors to navigate with ease. Additionally, it will lessen the amount of questions people have about how to get started or where to find essential information. It is a win-win all around!

What I Did

Here is what was added and changed:

2883

novialriptide commented 1 month ago

I took a quick skim; this all looks good, but I think we (as in the pygame community members) should be the ones to write all of this. Seeing as this is your first contribution, I'd say it's a little inappropriate that you're the one writing this. Although if the others agree with this, my first takeaway is that this should be a reStructuredText file.

MrF1ow commented 1 month ago

I totally understand that. Just so you know though I hardly wrote any of it. It is 98% what was written in the wiki pages. I just collected it all into one document. Just makes it easier to find and navigate.

Also, there is a good conversation going in the the issue this is attached, where this addition is getting discussed.

MyreMylar commented 1 month ago

I totally understand that. Just so you know though I hardly wrote any of it. It is 98% what was written in the wiki pages. I just collected it all into one document.

I think this cuts to the heart of this. I think we should have a CONTRIBUTING.md file, but it should be brief and largely be composed of links to our existing documentation on the Wiki - otherwise we are just duplicating text in two places that we then have to maintain.

Pygame is older than Github and historically the contribution documentation has been on a wiki like page so I'd like to continue that tradition. I think we can accomodate people who search for a CONTRIBUTING.md file by just linking them to the existing documentation and making any improvements needed over there.

Does that make sense? I don't want to be updating text in two places as things change.

Here is an example of another large project (numpy) that takes this approach with CONTRIBUTING.md:

https://github.com/numpy/numpy/blob/main/.github/CONTRIBUTING.md

MrF1ow commented 1 month ago

I totally understand that. Just so you know though I hardly wrote any of it. It is 98% what was written in the wiki pages. I just collected it all into one document.

I think this cuts to the heart of this. I think we should have a CONTRIBUTING.md file, but it should be brief and largely be composed of links to our existing documentation on the Wiki - otherwise we are just duplicating text in two places that we then have to maintain.

Pygame is older than Github and historically the contribution documentation has been on a wiki like page so I'd like to continue that tradition. I think we can accomodate people who search for a CONTRIBUTING.md file by just linking them to the existing documentation and making any improvements needed over there.

Does that make sense? I don't want to be updating text in two places as things change.

Here is an example of another large project (numpy) that takes this approach with CONTRIBUTING.md:

https://github.com/numpy/numpy/blob/main/.github/CONTRIBUTING.md

This makes sense. I am more than willing to make a new pull request with what you said and making sure it is in .rst format. Does this sound good to you?

MyreMylar commented 1 month ago

This makes sense. I am more than willing to make a new pull request with what you said and making sure it is in .rst format. Does this sound good to you?

I thought the .md stood for 'markdown'? I'm not sure a .md file can be in .rst format. If it can, then sure - but the main point is not the style of the formatting in the CONTRIBUTING.md file it is to make it much shorter than in this PR and consist mainly of links to the wiki contributing documentation.

I'm thinking of people who search pygame-ce CONTRIBUTING.md or use some other contributing tool to find contribution instructions by looking specifically for this file in GitHub repos. Then I want the file to contain hyperlinks to our existing wiki documentation.

If the documentation on the wiki currently sucks, for whatever reason (something I'm quite willing to believe because I wrote a lot of it!) then I'd like to improve it on the wiki and not have to keep the text in CONTRIBUTING.md up to date with the text on the Wiki and visa versa as this is a maintenance burden. The point of it being a "contributor wiki" is that members of the pygame-ce contributors group (a group consisting of people who've contributed to the project a few times) can edit it and hopefully keep it useful, but most of it is not relevant to the end-users.

Ideally Github wikis would also be able to accept pull requests to let everyone recommend changes. Unfortunately GitHub has not made any moves towards this in some time. So far it's not really been too much of an issue just to slap up complaints in issues or on discord and have a pygame-ce contributor (from the community group) just go in and fix it directly.

Again, if you look at how numpy does it their contribution documentation is also on a separate web page - and the contributing.md file is 40 lines with 5 links to pages of more detailed information - I'd like something short like that.

On a separate note, we could also use linking to the contributor documentation in the wiki, either via the CONTRIBUTING.md file or just directly to the index page on the wiki. There is separately a plan afoot to somewhat rewrite the whole readme file so this part may become superseded by that PR when it materialises.

MrF1ow commented 1 month ago

This makes sense. I am more than willing to make a new pull request with what you said and making sure it is in .rst format. Does this sound good to you?

I thought the .md stood for 'markdown'? I'm not sure a .md file can be in .rst format. If it can, then sure - but the main point is not the style of the formatting in the CONTRIBUTING.md file it is to make it much shorter than in this PR and consist mainly of links to the wiki contributing documentation.

I'm thinking of people who search pygame-ce CONTRIBUTING.md or use some other contributing tool to find contribution instructions by looking specifically for this file in GitHub repos. Then I want the file to contain hyperlinks to our existing wiki documentation.

If the documentation on the wiki currently sucks, for whatever reason (something I'm quite willing to believe because I wrote a lot of it!) then I'd like to improve it on the wiki and not have to keep the text in CONTRIBUTING.md up to date with the text on the Wiki and visa versa as this is a maintenance burden. The point of it being a "contributor wiki" is that members of the pygame-ce contributors group (a group consisting of people who've contributed to the project a few times) can edit it and hopefully keep it useful, but most of it is not relevant to the end-users.

Ideally Github wikis would also be able to accept pull requests to let everyone recommend changes. Unfortunately GitHub has not made any moves towards this in some time. So far it's not really been too much of an issue just to slap up complaints in issues or on discord and have a pygame-ce contributor (from the community group) just go in and fix it directly.

Again, if you look at how numpy does it their contribution documentation is also on a separate web page - and the contributing.md file is 40 lines with 5 links to pages of more detailed information - I'd like something short like that.

On a separate note, we could also use linking to the contributor documentation in the wiki, either via the CONTRIBUTING.md file or just directly to the index page on the wiki. There is separately a plan afoot to somewhat rewrite the whole readme file so this part may become superseded by that PR when it materialises.

Yeah the .md does stand for MarkDown, but multiple people have told me that the .rst format is this projects bread and butter. For GitHub specifically, markdown is their main format, but they are both really similar so I think keeping it with what the project already has (.rst) is the best course of action.

I get what you guys have been saying about making it shorter and just a place for reference to the wiki pages. Similar to how numpy does it.

I will get something to you guys shortly if that is alright. I got a wedding I got to go to today. Thanks for letting me do this!

Starbuck5 commented 1 month ago

Call me he who shall not be named, but I don't want another file in the root directory.

I think the clear solution here is just to link the wiki from the existing README.

No duplicated content, no extra files.

Given how difficult (unfortunately) it is to contribute to this library, I don't think "I can't find a contributing.md file so I'm going to give up on my contribution" is a valid concern.

MyreMylar commented 1 month ago

We actually don't need to put it in the root. numpy's version is in the .github/ directory .

On Sun, 2 Jun 2024, 18:37 Charlie Hayden, @.***> wrote:

Call me he who shall not be named, but I don't want another file in the root directory.

I think the clear solution here is just to link the wiki from the existing README.

No duplicated content, no extra files.

Given how difficult (unfortunately) it is to contribute to this library, I don't think "I can't find a contributing.md file so I'm going to give up on my contribution" is a valid concern.

— Reply to this email directly, view it on GitHub https://github.com/pygame-community/pygame-ce/pull/2892#issuecomment-2143960595, or unsubscribe https://github.com/notifications/unsubscribe-auth/ADGDGGTHOXGJG3OJF2K6A6DZFNJ47AVCNFSM6AAAAABIRJHZX2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCNBTHE3DANJZGU . You are receiving this because your review was requested.Message ID: @.***>

MrF1ow commented 3 weeks ago

Here is a pull request for the addition of just a "How to Contribute" section to the README.rst instead of an entire file. @MyreMylar if you want the addition of smaller CONTRIBUTING.md in the ./github/ directory, I am more than happy to do that, but @Starbuck5 was pretty accurate in only needing one small section in the README.rst to show users where to go.

Just let me know

ankith26 commented 3 weeks ago

I'm personally fine with either approach, and also a possible third approach where we do both.

ankith26 commented 2 weeks ago

I have merged your other PR as it was more straightforward than this one

Starbuck5 commented 2 weeks ago

Since the other PR has been merged, I'm going to close this one.