Documentation and Licensing #28
Conversation
|
"Contribution" is misspelled in the commit message for 60ce654 |
CONTRIBUTING.md
Outdated
|
|
||
| ## Feature Requests | ||
|
|
||
| Need some new functionality to help? You can let us know by opening an [issue][new issue]. It's helpful to look through [all |
There was a problem hiding this comment.
nit: wrap to 80 columns
CONTRIBUTING.md
Outdated
| ## Bug Reports | ||
|
|
||
| Please let us know about what problems you run into, whether in behavior or | ||
| ergonomics of API. You can do this by opening an [issue][new issue].. It's |
CONTRIBUTING.md
Outdated
|
|
||
| ### Process | ||
|
|
||
| When you first post a PR, it might be good to clean up the commit history. We |
There was a problem hiding this comment.
Rephrase from "it might be a good idea" to "we request that"? There really aren't any times I wouldn't want a messy commit history cleaned up.
CONTRIBUTING.md
Outdated
| history. Once you let us know this is done, we can move forward with merging! | ||
| If you are uncomfortable with these parts of git, let us know and we can help. | ||
|
|
||
| We ask that all new files have the copyright header. Please update the |
There was a problem hiding this comment.
Maybe include the text of the copyright header here? Or in an appendix?
There was a problem hiding this comment.
I was going to but skipped it to see how much you cared out of concern for keeping the year up to date in it (or having a placeholder <YEAR> in it). I was figuring its easy enough to grab from another file.
So if you want it there more than willing to add it.
CONTRIBUTING.md
Outdated
| When we're ready to release, a project owner should do the following | ||
| - Determine what the next version is, according to semver | ||
| - Bump version in a commit | ||
| - Run `clog --setversion <X>.<Y>.<Z>`, touch up the log |
There was a problem hiding this comment.
I fall on the side of "changelogs are for humans, they should be written by humans". Specifically, when I'm looking at a changelog I don't care to see each commit described, I want to see what has "changed" for the human using the library. Tools like clog can be helpful for checking that everything was covered but I shy away from recommending them as the primary way to generate changelogs. https://keepachangelog.com/en/1.0.0/ lays out the reasons for this better than I ever could.
I think I'd feel better about recommending clog if there was also a mention of keepachangelog.com and something more like "curating the changes" than "touching up the log".
There was a problem hiding this comment.
Yeah, killercup and I have had discussions on this (which his posts are what led me to clog).
I've been using clog with cobalt and liquid and its been good enough for the time with minimal changes to the generated output.
My leaning is to just remove this line atm and not talk about changelogs and you can come in with a PR with a more detailed explanation of how you want to handle changelogs. I propose this because if you aren't using clog, it seems like we'd want to document steps in the PR section and here and that way you can choose how you'd like.
CONTRIBUTING.md
Outdated
| - Update the version in `Cargo.toml` | ||
| - Update the dependency version in `src/lib.rs` | ||
| - Update the dependency version in `README.md` | ||
| - Tag the commit via `git tag -a v<X>.<Y>.<Z>` |
There was a problem hiding this comment.
Annotated tags require a message, which I almost always just set to the same text as the version. This command could just be git tag -am "v<X>.<Y>.<Z>" v<X>.<Y>.<Z> and eliminate some ambiguity.
There was a problem hiding this comment.
I'll do this for now but I still want to explore sometime what are the best tag messages.
The fact that github automatically shows the messages and that its then easy to pull that out into release notes, I tend to put the changelog notes in my message.
The Issue template is based on rust's `CONTRIBUTING.md`. The PR template is a quick reminder of things from our `CONTRIBUTING.md`.
|
Meant to add the templates when writing CONTRIBUTING.md. |
Fixes #22 and #23