create a CONTRIBUTING.md to explain how to contribute to this repo.

[lostapathy]

Following up where #195 left off - I'm trying to move the current contributing.md to contributing-to-rubygems.md and then add a more conventional CONTRIBUTING.md that explains how to work on the guides themselves.

Specifically, to document what should be changed directly in this repo and what shouldn't, and point people to the correct location for things edited elsewhere. Hopefully that'll save maintainers some effort.

So far I've found that running rake postrelease on rubygems itself will run this which rebuilds some generated docs and pushes them out to release.

@segiddins (or anyone else) are there any other processes I should be aware of when writing this up?

[segiddins]

Maybe we can put this in .github so we don’t have to rename the existing file?

[lostapathy]

I thought about that, and I know you suggested it on the other thread, but I feel like putting it at the root is more of the "standard" so it's more likely to be discovered this way, and if it's more likely to be discovered people are more likely to follow it.

Also on https://github.com/rubygems/guides/community - I believe that page would forever link "Contributing" to the old file, which is not desired behavior.

[lostapathy]

This is now ready for review. I'm pretty sure I covered what's needed to at least point people in the right direction. I decided not to get into the details of the mechanics of how these docs are actually generated as it gets fairly involved to explain and most people won't need to know to contribute.

[colby-swandale]

There seems to be 2 changes here, one is adding CONTRIBUTING.md but why are you also changing the metadata as well?

[bundlerbot]

☔ The latest upstream changes (presumably #204) made this pull request unmergeable. Please resolve the merge conflicts.

[lostapathy]

Good question, I should have explained the change to the front matter.

Per the Jekyll docs, permalink is the correct way to specify the location of the page, not url.

I had to set it to permalink in the page I renamed to contributing-to-rubygems.md to keep it at the current URL. I updated the url param to match on the existing pages to get everything consistent again and hopefully prevent a regression in the future if someone were to "fix" that file by setting it back to url.

[colby-swandale]

This is pretty confusing as to what's happening here, either remove the ** or don't make this a header

[colby-swandale]

How about Setting up a local development environment instead? I find that more clearer.

[colby-swandale]

I would just say The guides are built on.., we don't need to link to the production site again.

[colby-swandale]

Extra spacing

[colby-swandale]

I'm happy to merge this once the feedback has been addressed.

[lostapathy]

Thanks for the review @colby-swandale! I believe I've updated everything as requested.

[colby-swandale]

Thanks!

[colby-swandale]

@lostapathy I've had to unfortunately revert this PR as there were a couple of issues.

All the URLs that Google has indexed where broken due to a difference in how the URI is generated between url: and permalink: in jekyll.

The other issue is that url: contributing doesn't appear to be working either. I get 404 on my machine unless i rename contributing-to-rubygems.md back to contributing.md.

These 2 issues forced me to revert the entire PR instead of just fixing the links.

I would still like to see a contributing doc for the rubygem guides but we will need to find a workaround.

[lostapathy]

Bummer! And sorry for the hassle @colby-swandale. It'll probably take a couple weeks before I'm free enough to troubleshoot it, but I'll get to the bottom of this and report back with a better-vetted solution.