search

purescript-contrib / governance

Guidelines and resources for the PureScript Contributors organization
15 stars 3 forks source link

Should the changelog go in the repo root rather than a docs directory? #17

Closed hdgarrood closed 3 years ago

hdgarrood commented 3 years ago

I've never seen a changelog anywhere other than in the repo root elsewhere. Also, just in case you hadn't spotted, we currently use GitHub Releases for changelogs, eg: https://github.com/purescript-contrib/purescript-string-parsers/releases

I would support putting the changelog into a file in the repo rather than in GitHub releases though: it's much easier to search through and it doesn't tie us to GitHub.

JordanMartinez commented 3 years ago

I agree with that. If we leave it in the docs folder, then we won't be able to delete that folder in cases like purescript-contrib/purescript-options#34.

thomashoneyman commented 3 years ago

I think it's better to have a single-file changelog rather than use GitHub releases for it, but we can use both. For the Halogen Hooks changelog I just copy/paste the unreleased section into the GitHub release when it goes out. That makes it easier to write good release notes rather than try to skim recent commits.

I can't remember why I put it in docs. It can definitely go in the repository root.

The CONTRIBUTING.md file is in the .github directory, where it's picked up when you open your first issue or PR. Do y'all prefer that also exists in the repo root instead?

thomashoneyman commented 3 years ago

This move would need to be applied to the 17 libraries which have been updated so far as well as updated in the contrib-updater tool.

hdgarrood commented 3 years ago

GitHub picks up CONTRIBUTING.md and prompts you to read it when you're opening an issue if the file exists in the repo root too, eg: https://github.com/nodejs/node/issues/new?template=1-bug-report.md I think I would prefer it there, personally, for the same reason: it's probably easier to find that way, especially if you're browsing the repository on your machine after having checked it out.

The approach you describe for changelogs sounds good to me too :+1:

thomashoneyman commented 3 years ago

Quick request: to save on any future updates -- @hdgarrood, @garyb, @JordanMartinez, @milesfrain if you have noticed anything from the 17 libraries we've updated so far that you think should be changed going forward, then please open an issue so I can batch those updates all together. It's great we're having this discussion!