Skip to content

Add specific upgrade instructions (if any) to PR body #20

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

Open
wants to merge 2 commits into
base: main
Choose a base branch
from

Conversation

oleole39
Copy link
Contributor

@oleole39 oleole39 commented Feb 4, 2025

Upstream upgrade for some apps needs more than just passing CI to get merged (e.g. jsoncrack_ynh)

This PR aims at implementing what was discussed earlier with @alexAubin, @orhtej2, miro5001 and @lapineige, i.e. short instructions's reminder in the upgrade PR created by the autoupdate script. Those are taken located at the app's root, in the file PACKAGE_UPDATE.md (@alexAubin, we had talked of calling it MAINTENANCE.md, but after a second though it seems to me that since this is meant to be displayed exclusively in autoupdate PR, it may be more fair to have a more specific filename). Here is an example: https://github.com/YunoHost-Apps/jsoncrack_ynh/blob/testing/PACKAGE_UPDATE.md

It will come together with a link to detailed instructions located in Github wiki (to avoid adding translation work in README.md for info which is only relevant to package maintainers). It could be later added to YNH doc if several apps share similar detailed instructions (e.g. maybe all apps using NPM, etc.). Here is an example: https://github.com/YunoHost-Apps/jsoncrack_ynh/wiki/How-to-apply-upstream-upgrades-to-this-package

PR is short & simple but wasn't tested.

@lapineige
Copy link
Contributor

Did I discuss something about it ? 😅

Anyway sounds like an improvement to push such kind of info and formatting to more packages :)

@DeMiro5001
Copy link

DeMiro5001 commented Feb 6, 2025

Did I discuss something about it ? 😅

Yes, with m606, about some process to be done before updating jsoncrack.
I always was wondering about using the wiki of the package, especially for noting the changelog, with human readable text and media, for me, to track what I did, what issues I faced, how did I manage to get it fixed, etc... A package-wiki 😉

@oleole39
Copy link
Contributor Author

oleole39 commented Feb 7, 2025

I always was wondering about using the wiki of the package, especially for noting the changelog, with human readable text and media, for me, to track what I did, what issues I faced, how did I manage to get it fixed, etc... A package-wiki 😉

That's exactly the point, for package maintainers, but also for others - people helping package maintainers, or people that may come as new package maintainer of an abandoned package.

improvement to push such kind of info and formatting to more packages :)

Sure, there can be various use cases depending on apps (and maintainers).
In the one of jsoncrack_ynh, I always have a doubt of what I am supposed to do at each upgrade. I feel having a note somewhere, as well as a short reminder of the required steps in the PR would make it easier. I could make a local note for me of course, but I guess it makes more sense to share it somewhere within YNH community if someone want to contribute at some point (e.g. for JSON Crack some allowed Github users sometimes merge autoupgrade branches to testing in good faith, although it does not really help for this very app due to its specific upgrade process, which they probably don't have in mind), or if for any reason I happen to disappear at some point that would make it much easier for anyone who would care about maintaining the package.

using the wiki of the package

Regarding the wiki use in itself, I indeed followed your suggestion @DeMiro5001, which was both relevant and quick to setup, although I wonder whether that would not create additional complexity in the long run to have yet another place with info on a package.
To illustrate my point, I remember that some time ago, YNH had a user/admin documentation page for every app in YNH documentation website which were not always matching the package instructions (in Github's README.md or /doc I don't remember) as it was often outdated. A situation that could led to confusion for admin and users.
Eventually /doc happened to be defined as the only place for app documentation (from which it would then be automatically duplicated within README.md or in the catalog and the webUI. I didn't follow the discussion that may have led to such decision, but I believe it would be better that the info of a package is not too spread around and remain as much as possible within the repo?
Maybe in the end, that would be better to use something similar to:

  • /doc/PACKAGE_UPDATE.md for reminding to be displayed in the autoupdater's PR
  • /doc/PACKAGE_MAINTENANCE.md for a general maintenance info section - for jsoncrack_ynh, that could be the content of the wiki page I created. Maybe it could be automatically concatened at the end of the README.md.
  • /doc/PACKAGE_CHANGELOG.md for package changelog

And that info for those files could be automatically used in some other places of YNH documentation infra.

However for now, I quote this point from @alexAubin which I tend to agree with:

any .md file in doc/ not named PRE/POST_INSTALL/UGRADE will be understood as "another piece of admin documentation similar to ADMIN.md" which is kind of an underused feature but anyway that would be confusing for admin to see packaging-related info in there)

So before a more general solution is thought of, I used the various suggestions received to set up with this PR PACKAGE_UPDATE.md at package's root, linking towards detailed instructions in a package repo's wiki page.

@DeMiro5001
Copy link

Mini-wiki for lychee, so I keep track of what I have done and what I am planning to do in a human readable format :
https://github.com/YunoHost-Apps/lychee_ynh/wiki

@oleole39
Copy link
Contributor Author

oleole39 commented Feb 16, 2025

Mini-wiki for lychee, so I keep track of what I have done and what I am planning to do in a human readable format : https://github.com/YunoHost-Apps/lychee_ynh/wiki

Note that for TO-DO list, there could be alternatives in Github:

  • Open a Kanban (planned/work in progress/done) in the Project tab.
  • Open a PR per feature with a tasks checklist (- [ ] Task 1)

Which would somehow makes changelog rather obvious if PR are properly named.

Although it would make repos even more complex on a broader scale!

oleole39 added a commit to YunoHost-Apps/jsoncrack_ynh that referenced this pull request Feb 22, 2025
Upgrade to v2025.02.05 and fix github workflow on_upstream
adds PACKAGE_UPDATE.md info (related to YunoHost/apps_tools#20)
@Salamandar
Copy link
Contributor

yesyesyesyes

Let me just create a documentation PR for this before merging. We don't want this feature to be lost in code.

@Salamandar Salamandar self-requested a review April 3, 2025 16:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants