Collaboration best practices

[SimJoSt]

Continuation of the following conversation: #136 (comment)

@SimJoSt:

@jerodfritz do you prefer being able to fast-forward merge and me to update the PR?
If yes, do you prefer rebases or do you like me to keep an accurate history and just merge dev into the feature branches?
Especially, if the npm run gen:all command needs to be run to add the new script including file size to the list of curated scripts.

@jerodfritz:

Honestly, I don't have a strong preference. Would you be interested in helping dictate and moderate the flow here?

Here are my quick thoughts and suggestions:

• Don't require fast-forward merges
  • this is not a full code base of an app, where every change to the base branch requires a retest of the whole feature branch
  • this repositories settings for PRs already seem to be set up this way
• Remove/change the pre-commit hook
  https://github.com/eshtek/hexos-docs/blob/main/.husky/pre-commit
  • A feature branch that adds or changes an install script has to be updated every time a change is made to other install scripts before a merge
  • Make it a "CI / GitHub action"-only thing, and run it if files in the docs/public/install-scripts/ directory are changed
  • This also eliminates the risk of merging docs that were not properly generated (otherwise fast-forward merges would be necessary)
• Updating feature branches
  • Merging the dev branch into the feature branch is preferred over rebases
    • preserves accurate history
    • allows seeing the evolution of the code and thought process over time
  • just a preference, not a rule, as the changed code is not yet in the repositories branches

[garrettjoecox]

@SimJoSt
For merging a PR into the dev branch I don't have strong preferences when it comes to merge strategy as I've never found one that much more useful over another in practice. For feature branches I tend to just leave it up to the preferences of who's working on it, as people tend to have different workflows they are used to.

That being said consistency/direction is good to have, and I'm fine with this direction in general. So If you want to create a CONTRIBUTING.md with some of this guidance and make the appropriate changes for CI (and the precommit hook) we'll get it merged in.

The goal is for us to make changes to the script, and by the time they get deployed the page accurately reflects the date modified and size for each script. How and when this happens isn't super important, just that it's automated.

[SimJoSt]

Thanks for the feedback.
It might be a bit until I have time to get to it though.

So I don't mess with anything on your side, can you tell me about the deployment process? The better I understand it, the better I can make the workflows to get the content ready for it.
Do you have an automatic deployment to the https://docs.hexos.com site when something is merged to the main branch?
Or is that completely detached and a manual process?

[SimJoSt]

Off topic: How come you chose VitePress over other solutions like Starlight (Astro)?

[garrettjoecox]

can you tell me about the deployment process?

It's mostly self contained in Github Actions. We're using Github Pages for our prod site, then for dev and for each PR (when tagged with pull preview) we have a server that we build for and plop on there to serve statically.

The remaining generated-check.yml is just a final failsafe to prevent merging PR's if we detect they haven't run the script to update the metadata/sidebar linkings

How come you chose VitePress

I'll let @jerodfritz speak to that if they have any real reasons. If I had to guess it was just the most popular option in the vue ecosystem at the time of choosing.

[SimJoSt]

Thanks for the feedback, that helps to understand a bit and I will look into the GitHub actions for some more insight.
I've noticed that every time I open a PR, I need to manually select dev as the branch as the merge target, main is preselected. It would be great, if that could be adjusted in the repository settings.

[jerodfritz]

How come you chose VitePress

I'll let @jerodfritz speak to that if they have any real reasons. If I had to guess it was just the most popular option in the vue ecosystem at the time of choosing.

Yes, VitePress was a solid choice, because it lined up well with our team and stack.

[jerodfritz]

It would be great, if that could be adjusted in the repository settings.

☑ default branch main -> dev

[SimJoSt]

Collecting some resources:

• https://hub.hexos.com/topic/3876-how-to-contribute/#comment-23736
• https://contributing.md/
  • https://contributing.md/generator/