Add a section on pull requests to contributing instructions #635
Conversation
|
Preview the changes: https://turinglang.org/docs/pr-previews/635 |
|
Version lag issue, causing CI failure, being fixed here: #636 |
developers/contributing/index.qmd
Outdated
|
|
||
| #### Change history | ||
|
|
||
| We keep a cumulative changelog in a file called `HISTORY.md` at the root of the repository. It should have an entry for every new breaking release, explaining everything our users need to know about the changes, such as what may have broken and how to fix things to work with the new version. Any major new features should also be described in `HISTORY.md`, as may any other changes that are useful for users to know about. Bug fixes generally don't need an entry in `HISTORY.md`. Any new breaking release must have an entry in `HISTORY.md`, entries for non-breaking releases are optional. |
There was a problem hiding this comment.
Hmmmm I've been putting changelog entries for all patch releases so far (at least for Turing / DPPL). I think it's a net benefit -- would it be too strict to enforce at least a one-liner for all releases?
There was a problem hiding this comment.
I haven't felt it being worth it at this stage, when we are still changing things quite rapidly (pre-v1.0), but I'm not strongly opposed if you want to make it a rule. Eventually when things stabilise (post-v1.0) I think we should start doing it.
There was a problem hiding this comment.
No problem, I'm quite happy to not enforce until post 1.0. I'll still do it anyway when making PRs.
|
Added semantic line breaks and the bit you proposed. @AoifeHughes, can you also take a look? |
|
@AoifeHughes, did you want to give comments on this? I think this arose from your request. |
|
|
||
| #### Please make mistakes | ||
|
|
||
| Getting pull requests from outside the core developer team is one of the greatest joys of open source maintenance, and Turing's community of contributors is its greatest asset. |
There was a problem hiding this comment.
I can't quite figure out why, maybe it's the over joyous writing style of AI models and the deluge of their outputs, but sentences like this " greatest joys" seem superfluous and unnecessary. (but maybe I'm just becoming a grumpy old lady, so again this can probably be disregarded as a comment
There was a problem hiding this comment.
I wanted to counter-balance the seriousness of some of the rest of this doc, and make people feel like we do really enjoy it when others send us PRs. As you can tell from one of the earlier comments too, I also generally like an informal way of writing. (I think academics are often unnecessarily formal and it makes things harder to understand and more boring than they need to be. This is why talks are often better than papers, and conversations are almost always better than talks. But that's a whole different rant.)
There was a problem hiding this comment.
:) yes another rant, though I'd take a well written paper over a talk or conversation any day (e.g., Science Journal papers are a thing of beauty to read)
Co-authored-by: Penelope Yong <penelopeysm@gmail.com>
Closes #619