New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Hercules needs a proper changelog #1853

Closed
Helianthella opened this Issue Oct 5, 2017 · 3 comments

Comments

Projects
None yet
2 participants
@Helianthella
Contributor

Helianthella commented Oct 5, 2017

Currently there's no changelog in the repo, no tags, no github releases and there's misc changelogs piled up pretty much everywhere on the forums. This situation is very chaotic and I believe we can do better.

Here's some ideas:

  • centralize all changelogs in a single forum thread with an index in the first post and all other posts of the thread serving as individual changelogs
    • ✔️ we get a central hub for for the changelogs
    • the changelogs would not be in the repo, so one has to open a web browser and navigate to the forums
    • the changelogs would not be actual releases, they would be dates

  • have a changelog.md file at the root of the repo that we update in every single PR
    • ✔️ we get a central hub for for the changelogs
    • ✔️ the changelogs would be distributed along with the repo, so no need to open a web browser
    • ✔️ the changelogs would always be up-to-date no matter what commit you checkout
    • the changelogs would not be actual releases, they would be sha1 short hashes

  • borrow the tmwAthena workflow: don't randomly push to master whenever you feel like it. Instead we would do releases every 2~4 weeks and add pull requests to milestones. Once the milestone deadline is reached, we push every PRs in the milestone that are ready, and move the PRs that are not ready to the next milestone. After the push, we tag the latest commit with the name of the release (ie v2017.10.5) and we put the changelog in a github release
    • ✔️ the changelogs would be actual releases
    • ✔️ Hercules would finally get tags, so we can refer to a release by its actual name rather than its sha1 hash
    • ✔️ releases are tracked easily and efficiently using the milestone system
@MishimaHaruna

This comment has been minimized.

Show comment
Hide comment
@MishimaHaruna

MishimaHaruna Oct 8, 2017

Member

After discussing the tmwAthena workflow, I agree on attempting to adopt it, on a 4-week frame.

Member

MishimaHaruna commented Oct 8, 2017

After discussing the tmwAthena workflow, I agree on attempting to adopt it, on a 4-week frame.

@MishimaHaruna MishimaHaruna added this to the Release v2017-10-22 milestone Oct 9, 2017

@Helianthella

This comment has been minimized.

Show comment
Hide comment
@Helianthella

Helianthella Oct 10, 2017

Contributor

Pasting here relevant logs for transparency:

<Kisuka> that suggestion gives me ptsd to eathena days
<Kisuka> i do agree with releases / tags tho. just kinda hard to do it tho with what kinda project this is. would have to like really buckle down on what should be considered a 'release' or like what all would be part of a tag. if it were episodes from RO thatd work great but thats really not possible
<Kisuka> would have to make an actual roadmap of things needing to be done and sort them into releases
<Kisuka> the tmwathena workflow one is pretty good tbh. thats a pretty standard git workflow.
<meko> what's considered a release? we don't have to wait for something major to make a release, we can just go with the rolling-release model and release every X days
<meko> X could be 2 weeks, 4 weeks, 6 weeks or whatever we decide
<Jguy> lol Release Candidates.
<Jguy> RC4 Kisuka
<Jguy> All we need is lemongrass to make an RC on Hercules and we're good to go.

<Haru> meko: about #1853 - assuming we borrow the tmwAthena workflow (which sounds good to me), how do we deal with any breakage that might land to master during the release process?
<Haru> (or, how does tmwAthena deal with it)
<meko> if we have urgent patches we just push again and tag again
<meko> so you end up with something like v1.2.3-1
<Haru> yeah, that's what I was wondering, whether it'd need to wait for the next scheduled release or not
<meko> but if we use semver we have to abide to their spec, and they have special instruction for those cases
<Haru> hmm it's pretty difficult for a project like Hercules to do that I believe
<Haru> well, maybe if we improve on the public/private API in the interfaces, we coudl eventually acheive it
<Haru> but right now, even minor changes cause an API change
<meko> then we go with YYYY.MM.DD(-patch)?
<Haru> yes, I think that works better right now
<meko> and simpler, even if ugly
<meko> what release window do you prefer? every 2 weeks? 3? 4? 6? 8?
<Haru> 2 is pretty tight, 4 is more reasonable

<meko> so... when's the "first" release?
<Haru> Hmm looking at what's already on my calendar, either the 22nd (2 weeks from now) or the 5th (4 weeks)
<Haru> (assuming we want to keep it on a weekend)
Contributor

Helianthella commented Oct 10, 2017

Pasting here relevant logs for transparency:

<Kisuka> that suggestion gives me ptsd to eathena days
<Kisuka> i do agree with releases / tags tho. just kinda hard to do it tho with what kinda project this is. would have to like really buckle down on what should be considered a 'release' or like what all would be part of a tag. if it were episodes from RO thatd work great but thats really not possible
<Kisuka> would have to make an actual roadmap of things needing to be done and sort them into releases
<Kisuka> the tmwathena workflow one is pretty good tbh. thats a pretty standard git workflow.
<meko> what's considered a release? we don't have to wait for something major to make a release, we can just go with the rolling-release model and release every X days
<meko> X could be 2 weeks, 4 weeks, 6 weeks or whatever we decide
<Jguy> lol Release Candidates.
<Jguy> RC4 Kisuka
<Jguy> All we need is lemongrass to make an RC on Hercules and we're good to go.

<Haru> meko: about #1853 - assuming we borrow the tmwAthena workflow (which sounds good to me), how do we deal with any breakage that might land to master during the release process?
<Haru> (or, how does tmwAthena deal with it)
<meko> if we have urgent patches we just push again and tag again
<meko> so you end up with something like v1.2.3-1
<Haru> yeah, that's what I was wondering, whether it'd need to wait for the next scheduled release or not
<meko> but if we use semver we have to abide to their spec, and they have special instruction for those cases
<Haru> hmm it's pretty difficult for a project like Hercules to do that I believe
<Haru> well, maybe if we improve on the public/private API in the interfaces, we coudl eventually acheive it
<Haru> but right now, even minor changes cause an API change
<meko> then we go with YYYY.MM.DD(-patch)?
<Haru> yes, I think that works better right now
<meko> and simpler, even if ugly
<meko> what release window do you prefer? every 2 weeks? 3? 4? 6? 8?
<Haru> 2 is pretty tight, 4 is more reasonable

<meko> so... when's the "first" release?
<Haru> Hmm looking at what's already on my calendar, either the 22nd (2 weeks from now) or the 5th (4 weeks)
<Haru> (assuming we want to keep it on a weekend)
@Helianthella

This comment has been minimized.

Show comment
Hide comment
@Helianthella

Helianthella Oct 16, 2017

Contributor

more logs

<4144> Haru: you want delay pull requests to merge before next release?
<4144> i think better merge all want can be merged into master. and release is other branch what merged once it released
<Dastgir> Wouldn't that create too many branches?
<Dastgir> Also if someone clones, they would use master branch by default. So that would defeat the purpose of releases?
<4144> one branch for release and one for current commits
<4144> for each release tag
<4144> or even simpler. for release dont need any branches. set tag and this is release
<Haru> Hmm I was thinking of using a temporary branch to merge into a few days in advance, let travis and gitlab-ci build (possibly even coverity -- I'll see about setting it up to target another branch in case), and then once everything is in a good state, fast-forward the temp branch into master
<Haru> but we can use master as dev branch, that's also fine

<meko> ok and do we add a CHANGELOG file to the repo that we'd update on each release day?
<meko> or do we put the changelog solely in github "releases"?
<Haru> hmm good question
<meko> perhaps both?
<Haru> the CHANGELOG file (or CHANGELOG.md, whatever) might be annoying to do, but it's worth having, so that people aren't forced to use a browser
<Haru> as long as we update it on the release day (rather than each individual commit), it won't cause merge conflicts at each PR
<Haru> we can keep an up to date draft in the github wiki or wherever

<meko> so let's recap so we all agree: we merge PRs to master when they are ready, then on release day we update the changelog, push master to stable and finally tag?
<4144> look like yes
<Haru> yeah, I agree with that workflow (unless someone has a strong opinion voicing for a different one of course)

Here's the new workflow, according to what was decided:

  1. we create a milestone and add to it PRs that are release candidates
  2. when PRs are reviewed and approved, we push them to master
  3. on the release day:
    1. we update the CHANGELOG.md file and push it to master
    2. we push master to stable
    3. we tag with the name of the release, ie v2017.10.22, and push the tag
    4. we create a github release using the latest tag, and add the relevant markdown changelog to it
  4. we move any unmerged PR to the next milestone
Contributor

Helianthella commented Oct 16, 2017

more logs

<4144> Haru: you want delay pull requests to merge before next release?
<4144> i think better merge all want can be merged into master. and release is other branch what merged once it released
<Dastgir> Wouldn't that create too many branches?
<Dastgir> Also if someone clones, they would use master branch by default. So that would defeat the purpose of releases?
<4144> one branch for release and one for current commits
<4144> for each release tag
<4144> or even simpler. for release dont need any branches. set tag and this is release
<Haru> Hmm I was thinking of using a temporary branch to merge into a few days in advance, let travis and gitlab-ci build (possibly even coverity -- I'll see about setting it up to target another branch in case), and then once everything is in a good state, fast-forward the temp branch into master
<Haru> but we can use master as dev branch, that's also fine

<meko> ok and do we add a CHANGELOG file to the repo that we'd update on each release day?
<meko> or do we put the changelog solely in github "releases"?
<Haru> hmm good question
<meko> perhaps both?
<Haru> the CHANGELOG file (or CHANGELOG.md, whatever) might be annoying to do, but it's worth having, so that people aren't forced to use a browser
<Haru> as long as we update it on the release day (rather than each individual commit), it won't cause merge conflicts at each PR
<Haru> we can keep an up to date draft in the github wiki or wherever

<meko> so let's recap so we all agree: we merge PRs to master when they are ready, then on release day we update the changelog, push master to stable and finally tag?
<4144> look like yes
<Haru> yeah, I agree with that workflow (unless someone has a strong opinion voicing for a different one of course)

Here's the new workflow, according to what was decided:

  1. we create a milestone and add to it PRs that are release candidates
  2. when PRs are reviewed and approved, we push them to master
  3. on the release day:
    1. we update the CHANGELOG.md file and push it to master
    2. we push master to stable
    3. we tag with the name of the release, ie v2017.10.22, and push the tag
    4. we create a github release using the latest tag, and add the relevant markdown changelog to it
  4. we move any unmerged PR to the next milestone
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment