Move changelog to crate documentation

[madsmtm]

Fixes #3477.

Part of #3431.

I've kept the CHANGELOG.md file as a sort of "redirect", as that's where most people expect to find the changelog in a project.

[kchibisov]

My idea was to keep the CHANGELOG around which will represent next release actually. It's also easy to cherry-pick that way since you clearly see what is new and you don't create dead files in between.

[daxpedda]

LGTM except some suggestions I had.

@kchibisov

My idea was to keep the CHANGELOG around which will represent next release actually. It's also easy to cherry-pick that way since you clearly see what is new and you don't create dead files in between.

Doesn't the unreleased.md file serve that purpose?

[kchibisov]

Doesn't the unreleased.md file serve that purpose?

Yes, but I want it to be in the root directory and still be called CHANGELOG and then it'll be added to docsrs once release is actually done, I guess?

[madsmtm]

Yes, but I want it to be in the root directory and still be called CHANGELOG and then it'll be added to docsrs once release is actually done, I guess?

Functionally, I don't think there's really going to be much of a difference, except maybe that users are going to be confused at how empty the root CHANGELOG.md is (people don't read the header in such a file, so if there's some entries, then people will think that all entries should be there).

I do also kinda like that the unreleased changes are close to the other changelog entries, but I don't mind much either way.

---

I think I will rebase this after #3447, and include the changelog entry from that one.

[kchibisov]

Could you just symlink the CHANGELOG to unreleased one? Then it should be good as long as @daxpedda comments are addressed.

[madsmtm]

Symlinks are likely to cause problems for people cloning on Windows that haven't set their environment up properly.

I could easily use #[doc = include_str!("../../../CHANGELOG.md")], but I still believe that it's gonna confuse people if parts of the content in that file that people expect is available.

[kchibisov]

I could easily use #[doc = include_str!("../../../CHANGELOG.md")], but I still believe that it's gonna confuse people if parts of the content in that file that people expect is available.

I don't really understand what's the issue here, I want the file to be easily discoverable for the contributors. Also, the unreleased change must not be included for any release, because it's just straight confusing.

So just thinking more about it, probably should just never include master's changelog anywhere and keep it in CHANGELOG.md.

[kchibisov]

@madsmtm did you have a chance to work on that, since last time you've mentioned that you have some solution to the outlined issues here and during the meeting?

[madsmtm]

I just worked on it a little bit.

Note that CHANGELOG.md is not actually deleted even though GitHub shows it as such, it's just reduced to two lines that point users to the correct place(s).

[kchibisov]

I think something like that should be better, since it just shows the most relevant changelog by default, which you generally want as a user.

I've also updated CONTRIBUTING.md to be more explicit on what to do.

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 87289e80..1144ceeb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,8 @@
-Changelog entries should be put in the [`changelog::unreleased`](src/changelog/unreleased.md) module.
+Changelog entries should be put in the [`changelog::unreleased`].
 
-The changelog can also be viewed [on docs.rs](https://docs.rs/winit/latest/winit/changelog/index.html) or [on the current master docs](https://rust-windowing.github.io/winit/winit/changelog/index.html).
+The changelog can also be viewed [on docs.rs][docs.rs], [on the current
+master docs][master_docs].
+
+[`changelog::unreleased`]: src/changelog/unreleased.md
+[docs.rs]: https://docs.rs/winit/latest/winit/changelog/index.html
+[master_docs]: https://rust-windowing.github.io/winit/winit/changelog/index.html
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f4049df5..972e6af7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -56,14 +56,16 @@ To achieve these goals, a new branch is created for every new release. Releases
 The exact steps for an exemplary `0.2.0` release might look like this:
   1. Initially, the version on the latest master is `0.1.0`
   2. A new `v0.2.x` branch is created for the release
-  3. In the branch, the version is bumped to `v0.2.0` (including the link to the `current` changelog file)
-  4. The new commit in the branch is tagged `v0.2.0`
-  5. The version is pushed to crates.io
-  6. A GitHub release is created for the `v0.2.0` tag
-  7. On master, the version is bumped to `0.2.0`, and the changelog is updated
+  3. Move entries from `src/changelog/unreleased.md` into `src/changelog/v0.2.md`
+  4. In the branch, the version is bumped to `v0.2.0`
+  5. The new commit in the branch is tagged `v0.2.0`
+  6. The version is pushed to crates.io
+  7. A GitHub release is created for the `v0.2.0` tag
+  8. On master, the version is bumped to `0.2.0`, and the changelog is updated
 
 When doing a patch release, the process is similar:
   1. Initially, the version of the latest release is `0.2.0`
   2. Checkout the `v0.2.x` branch
   3. Cherry-pick the required non-breaking changes into the `v0.2.x`
-  4. Follow steps 3-7 of the regular release example
+  4. Move changelog entries from `src/changelog/unreleased.md` into `src/changelog/v0.2.md`
+  5. Follow steps 4-8 of the regular release example
diff --git a/src/changelog/mod.rs b/src/changelog/mod.rs
index 624a18fd..694cac0c 100644
--- a/src/changelog/mod.rs
+++ b/src/changelog/mod.rs
@@ -1,17 +1,5 @@
-//! # Changelog and migrations
-//!
-//! All notable changes to this project will be documented in this module,
-//! along with migration instructions for larger changes.
-
-// Put the current changelog entry at the top of rustdoc output.
-#[cfg(unreleased_changelogs)]
-pub use unreleased as current;
-#[cfg(not(unreleased_changelogs))]
-pub use v0_29 as current;
-
-#[cfg(unreleased_changelogs)]
-#[doc = include_str!("unreleased.md")]
-pub mod unreleased {}
+#![cfg_attr(unreleased_changelogs, doc = include_str!("unreleased.md"))]
+#![cfg_attr(not(unreleased_changelogs), doc = include_str!("v0.29.md"))]
 
 #[doc = include_str!("v0.29.md")]
 pub mod v0_29 {}

[madsmtm]

Hmm, that is kinda nice, though one fear is that users wanting to link to v0.29.5 would link with https://docs.rs/winit/latest/winit/changelog/index.html#0295, which is not a stable link, they should use https://docs.rs/winit/latest/winit/changelog/v0_29/index.html#0295.

Though seeing this, I'm starting to think we should just inline all of the changelog entries? I've done that in the last commit, can be easily reverted if we choose something else.

[kchibisov]

Hmm, that is kinda nice, though one fear is that users wanting to link to v0.29.5 would link with https://docs.rs/winit/latest/winit/changelog/index.html#0295, which is not a stable link, they should use https://docs.rs/winit/latest/winit/changelog/v0_29/index.html#0295.

That's not really our problem though, they should use stable link which we also provide...

Though seeing this, I'm starting to think we should just inline all of the changelog entries? I've done that in the last commit, can be easily reverted if we choose something else.

Nah, inlining all is too much.

[madsmtm]

Nah, inlining all is too much.

I think I disagree, but doesn't matter that much, so let's not block this PR on that discussion.