[Project] Changelog

[iHiD]

This issue outlines an Exercism project. As with all issues in the exercism/wip repo, this is an internal issue restricted to the core team. If you have something you need to discuss on this please open an issue at github.com/exercism/exercism.

---

We are going to build a changelog that allows the team (maintainers, website, CLI, community) to update the community on improvements and changes that are being made.

The entries in the changelog will be disseminated via means such as the website (through a new dashboard, which falls outside of the scope of this project) and through Twitter (which will serve as the MVP for dissemination in this project).

The changelog data model

• [x] A model called ChangelogEntry, with:
• title (varchar 255) - This is the minimum requirement - a sentence that says what's happened.
• created_by_id (user_id foreign key) - The user who adds the created_by
• details_markdown (nullable text) - Some optional markdown describing it more
• details_html (nullable text) - details_markdown parsed into HTML.
• twitter_copy (nullable varchar 255) - some optional text that will be tweeted.
• published_at (nullable datetime) - This is the flag for when something is published
• tweeted_at (nullable datetime) - This is the flag for when something is tweeted
• about_type / about_id (nullable polymorphic belongs_to) - These will be something like Exercise#192 or Track#23
• about_key (nullable varchar 255) - This will be a key with regards to filtering/sorting. I prefer having an explicit key to having to build more complex (and slow) queries on the polymorphic columns.
• info_url (nullable varchar 255) - The URL of a website we want to link to for more information (e.g. a PR)

The changelog editing UI

• [x] Add a changelog_admin namespace with an entries controller (exercism.io/changelog_admin/entries)
• [x] Add a flag to users for may_edit_changelog which controls access to this controller (see note 1)
• [x] Any user (with the flag) can create changelog entries
• [x] The "About" should be done via a dropdown for ["Track", "Exercise"] and then a secondary dropdown for the actual possible entries. This should populate about_key/about_type/about_id.
• [x] Users can edit their own unpublished changelog entries.
• [x] Admin users can see an extra button for "publish" on the show page, which, when clicked, sets the published_at.

Viewing in the UI

• [x] There should be a changelog page at exercism.io/changelog, which lists everything that is published, ordered by published at.
• [x] We'll put a design together, but the rough layout should be "icon + title" on the first line, byline (created_at handle) on the second line, details below it (if available), then a link below.
• [x] The link text should say "View PR on GitHub" if the info_url is of the format "https://github.com/.../.../pull/..."
• [x] The link text should say "View commit on GitHub" if the info_url is of the format "https://github.com/.../.../commit/..."
• [x] The link text should say "View GitHub issue" if the info_url is of the format "https://github.com/.../.../issues/..."
• [x] Each changelog should be paginated to 20 entries per page.
• [x] Each changelog entry should have a show page too (exercism.io/changelog/:id), but these won't be linked from the index page. The show page should just be a replicate of the individual block on the index page. I think it's better to duplicate the code rather than share a partial as they might diverge.

I will add some styling with @nicolechalmers to both pages once they're ready.

Tweeting

• [x] When a changelog entry is published and tweet_copy is not blank, it should fire an ActiveJob to tweet it out.
• [x] If the tweet has a track or exercise as it's about, then the relevant twitter account should tweet it. We have a twitter account for each track (list is here). We should turn this into a config file (I don't think it needs to go in the db). We will need to create a Twitter "app" (under exercism) and auth it on all the accounts. If you request passwords for any that we don't have, I'll forward all the emails to you and you can set the passwords and auth the apps for each. This will be a boring 2hr job - sorry!
• [x] If the about is missing, then the main twitter account should tweet it.
• [x] If the details_markdown is present, then the tweet should end with the changelog show url.
• [x] If the details_markdown is not present, but there is an info_url, then the tweet should end with the the info_url.

Notes

1) We are going to introduce a permissions setup at some point, rather than adding flags onto users. However, rather than blocking this project, I think we should just go for the boolean flag approach for now. If you would like to think about roles first, then I'm happy to discuss that, and we could look at adding something like rolify. Ping me on Slack if you'd rather than this approach and we can schedule half an hour to discuss.

@kntsoriano There's probably lots to discuss here. Feel free to async with me either here or Slack, or arrange a time to sync up if you want to chat it all through. I'm pretty free at the normal time this week and next.

[kntsoriano]

This is enough for me to work with. I agree with having flags first and worrying about roles in the future, it seems like a big feature to bake into this whole thing.

[iHiD]

OK, great. I'm also not sure how you want to work it in terms of maybe having one feature branch for the whole thing with a draft PR, and then a series of PRs to that branch?

[kntsoriano]

I'm not yet sure how I bunch it up into small PRs. I'll come up with a list of small tasks that we can go through to review.

[iHiD]

Cool. I'll leave you to work it out :)

[kntsoriano]

@iHiD Can you explain what the about_key is for?

[iHiD]

So the about key would be the merging of the about_type and about_id (e.g. Exercise#192) but having it as a materialised string makes it much easier to search for things. So for example, we can have a query like WHERE about_type IN ("track_13", "track_17", "website", "product") rather than having a much more complex query (and slower indexes) of checking both the about type and id for each. Does that make sense?

[kntsoriano]

@iHiD I think we're okay with this. I just need to auth all our Twitter accounts which I'm holding off on until I get tired.

[iHiD]

Which I'm holding off on until I get tired.

Ha! That's good thinking.

OK, so I guess I need to do some styling, then I'll start writing a blog post up about this, and start to talk to maintainers about it. Excited!