Update post-checkout hook to auto build backend

[tlylt]

What is the purpose of this pull request?

• Documentation update
• Bug fix
• Feature addition or enhancement
• Code maintenance
• DevOps
• Improve developer experience
• Others, please explain:

Overview of changes:
Related to discussions in #1934

• a convenient fix to improve developer experience around the need to invoke npm run build:backend every time after checking out to a branch, until an alternative is implemented (see comments in Discontinue the use of TypeScript project references #1934 for details)

Anything you'd like to highlight/discuss:
Post checkout hook inputs reference: https://www.atlassian.com/git/tutorials/git-hooks#:~:text=your%20continuous%20integration.-,Post%2DCheckout,-The

Testing instructions:

• Checkout to this PR branch, the following should be shown
  
• Afterwards, can cd docs and markbind serve -d to see that the docs can be served
• Try modifying the "README.md" file, and discard it via git commit -- README.md, the post checkout hook should not be triggered

Proposed commit message: (wrap lines at 72 characters)
Update post-checkout hook to auto build backend

---

Checklist: ☑️

• Updated the documentation for feature additions and enhancements
• Added tests for bug fixes or features
• Linked all related issues
• No unrelated changes

[jonahtanjz]

Thanks @tlylt 👍

Just one suggestion :)

[jonahtanjz]

LGTM 👍

[ang-zeyu]

Not sure if I mentioned this in #1934 as well, but if not then take it as a new point. This tackles only a very small subset of cases if the intention is to streamline the development experience.

Collaborative ones:

• Fresh repo clone
• git pull
• git merge master

Individual ones:

• git stash pop
• copy pasting file from some other place on your PC
• ❔ git is powerful. there are probably a lot more cases where source files can change not related to a checkout

Again, I think we should be providing separate commands that does the build by default to account for all of these. I emphasize separate, so if you don't need to rebuild the typescript files, you don't need to run a watcher -- just build the files once, or not at all, we can let the developer decide based on their individual preferences, workflow (did you do a git stash? merge? ...), PC capabilities (referring the point on tsc watcher being expensive).

While post-checkout is handy, I do not believe we should be relying solely (or at all, for the sake of consistency ("magic" 🎁 that sometimes works but sometimes dosen't)) on it to produce the build artifacts (typescript / anything else) necessary for development. The same goes for cleaning up artifacts in clean.jsvia post-checkout (I only realised this one in retrospect), which does not account for git pull / merge / ....

It also triggers many unnecessary rebuilds / cleans (e.g. checkout to another branch whose HEAD is referencing the same commit).

tldr I think this is ok as an interim solution, I'm still favouring supporting a few separate nuke-everything commands to streamline the development:

// can be less verbose
// the separate commands for the templates can probably be made into cli args as well.
"buildAndDevDocs": "npm run clean && npm run build:backend && node ...index.js s -d -o thedocs",
"buildAndDevDefaultTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o defaulttemplate",
"buildAndDevMinimalTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o minimaltemplate",
// can be less verbose
"watchAndDevDocs": "npm run clean && run the tsc watcher ... && node ...index.js s -d -o thedoc",
"watchAndDevDefaultTemplate": "...",
"watchAndDevMinimalTemplate": "...",
...

[tlylt]

Thanks @ang-zeyu for the detailed comment. Think I should have mentioned more clearly that this is indeed an interim fix in the hope of improving the developer experience.

While not capturing all the cases, especially the unnecessary rebuild when checking out to a new branch whose HEAD is referencing the same commit, it solves most of the issues I faced in the past few weeks of somewhat active development and code review here. For some of the cases listed, they are certainly not in the purview of this PR which makes use of "post-checkout" (and not pull, or merge hooks) that hopefully addresses the case of.......checkout. On the point of "magic", I was thinking that the CLI output of the githook gives quite a bit of hint as to what commands are executed, so it alludes to the underlying working of the script. Of course, this does not replace the details in our DG.

Again, I think we should be providing separate commands that does the build by default to account for all of these. I emphasize separate, so if you don't need to rebuild the typescript files, you don't need to run a watcher -- just build the files once, or not at all, we can let the developer decide based on their individual preferences, workflow (did you do a git stash? merge? ...), PC capabilities (referring the point on tsc watcher being expensive).

tldr I think this is ok as an interim solution, I'm still favouring supporting a few separate nuke-everything commands to streamline the development:

// can be less verbose
// the separate commands for the templates can probably be made into cli args as well.
"buildAndDevDocs": "npm run clean && npm run build:backend && node ...index.js s -d -o thedocs",
"buildAndDevDefaultTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o defaulttemplate",
"buildAndDevMinimalTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o minimaltemplate",
// can be less verbose
"watchAndDevDocs": "npm run clean && run the tsc watcher ... && node ...index.js s -d -o thedoc",
"watchAndDevDefaultTemplate": "...",
"watchAndDevMinimalTemplate": "...",
...

Good points here 👍 would defer to you to put up a tracking issue whenever you are free since I am not entirely sure of any additional details/requirements of the solution you have in mind

[ang-zeyu]

🙆‍♂️

[tlylt]

What is the purpose of this pull request?

• Documentation update
• Bug fix
• Feature addition or enhancement
• Code maintenance
• DevOps
• Improve developer experience
• Others, please explain:

Overview of changes:
Related to discussions in #1934

• a convenient fix to improve developer experience around the need to invoke npm run build:backend every time after checking out to a branch, until an alternative is implemented (see comments in Discontinue the use of TypeScript project references #1934 for details)

Anything you'd like to highlight/discuss:
Post checkout hook inputs reference: https://www.atlassian.com/git/tutorials/git-hooks#:~:text=your%20continuous%20integration.-,Post%2DCheckout,-The

Testing instructions:

• Checkout to this PR branch, the following should be shown
  
• Afterwards, can cd docs and markbind serve -d to see that the docs can be served
• Try modifying the "README.md" file, and discard it via git commit -- README.md, the post checkout hook should not be triggered

Proposed commit message: (wrap lines at 72 characters)
Update post-checkout hook to auto build backend

---

Checklist: ☑️

• Updated the documentation for feature additions and enhancements
• Added tests for bug fixes or features
• Linked all related issues
• No unrelated changes

[jonahtanjz]

Thanks @tlylt 👍

Just one suggestion :)

[jonahtanjz]

LGTM 👍

[ang-zeyu]

Not sure if I mentioned this in #1934 as well, but if not then take it as a new point. This tackles only a very small subset of cases if the intention is to streamline the development experience.

Collaborative ones:

• Fresh repo clone
• git pull
• git merge master

Individual ones:

• git stash pop
• copy pasting file from some other place on your PC
• ❔ git is powerful. there are probably a lot more cases where source files can change not related to a checkout

Again, I think we should be providing separate commands that does the build by default to account for all of these. I emphasize separate, so if you don't need to rebuild the typescript files, you don't need to run a watcher -- just build the files once, or not at all, we can let the developer decide based on their individual preferences, workflow (did you do a git stash? merge? ...), PC capabilities (referring the point on tsc watcher being expensive).

While post-checkout is handy, I do not believe we should be relying solely (or at all, for the sake of consistency ("magic" 🎁 that sometimes works but sometimes dosen't)) on it to produce the build artifacts (typescript / anything else) necessary for development. The same goes for cleaning up artifacts in clean.jsvia post-checkout (I only realised this one in retrospect), which does not account for git pull / merge / ....

It also triggers many unnecessary rebuilds / cleans (e.g. checkout to another branch whose HEAD is referencing the same commit).

tldr I think this is ok as an interim solution, I'm still favouring supporting a few separate nuke-everything commands to streamline the development:

// can be less verbose
// the separate commands for the templates can probably be made into cli args as well.
"buildAndDevDocs": "npm run clean && npm run build:backend && node ...index.js s -d -o thedocs",
"buildAndDevDefaultTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o defaulttemplate",
"buildAndDevMinimalTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o minimaltemplate",
// can be less verbose
"watchAndDevDocs": "npm run clean && run the tsc watcher ... && node ...index.js s -d -o thedoc",
"watchAndDevDefaultTemplate": "...",
"watchAndDevMinimalTemplate": "...",
...

[tlylt]

Thanks @ang-zeyu for the detailed comment. Think I should have mentioned more clearly that this is indeed an interim fix in the hope of improving the developer experience.

While not capturing all the cases, especially the unnecessary rebuild when checking out to a new branch whose HEAD is referencing the same commit, it solves most of the issues I faced in the past few weeks of somewhat active development and code review here. For some of the cases listed, they are certainly not in the purview of this PR which makes use of "post-checkout" (and not pull, or merge hooks) that hopefully addresses the case of.......checkout. On the point of "magic", I was thinking that the CLI output of the githook gives quite a bit of hint as to what commands are executed, so it alludes to the underlying working of the script. Of course, this does not replace the details in our DG.

Again, I think we should be providing separate commands that does the build by default to account for all of these. I emphasize separate, so if you don't need to rebuild the typescript files, you don't need to run a watcher -- just build the files once, or not at all, we can let the developer decide based on their individual preferences, workflow (did you do a git stash? merge? ...), PC capabilities (referring the point on tsc watcher being expensive).

tldr I think this is ok as an interim solution, I'm still favouring supporting a few separate nuke-everything commands to streamline the development:

// can be less verbose
// the separate commands for the templates can probably be made into cli args as well.
"buildAndDevDocs": "npm run clean && npm run build:backend && node ...index.js s -d -o thedocs",
"buildAndDevDefaultTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o defaulttemplate",
"buildAndDevMinimalTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o minimaltemplate",
// can be less verbose
"watchAndDevDocs": "npm run clean && run the tsc watcher ... && node ...index.js s -d -o thedoc",
"watchAndDevDefaultTemplate": "...",
"watchAndDevMinimalTemplate": "...",
...

Good points here 👍 would defer to you to put up a tracking issue whenever you are free since I am not entirely sure of any additional details/requirements of the solution you have in mind

[ang-zeyu]

🙆‍♂️

[tlylt]

What is the purpose of this pull request?

• Documentation update
• Bug fix
• Feature addition or enhancement
• Code maintenance
• DevOps
• Improve developer experience
• Others, please explain:

Overview of changes:
Related to discussions in #1934

• a convenient fix to improve developer experience around the need to invoke npm run build:backend every time after checking out to a branch, until an alternative is implemented (see comments in Discontinue the use of TypeScript project references #1934 for details)

Anything you'd like to highlight/discuss:
Post checkout hook inputs reference: https://www.atlassian.com/git/tutorials/git-hooks#:~:text=your%20continuous%20integration.-,Post%2DCheckout,-The

Testing instructions:

• Checkout to this PR branch, the following should be shown
  
• Afterwards, can cd docs and markbind serve -d to see that the docs can be served
• Try modifying the "README.md" file, and discard it via git commit -- README.md, the post checkout hook should not be triggered

Proposed commit message: (wrap lines at 72 characters)
Update post-checkout hook to auto build backend

---

Checklist: ☑️

• Updated the documentation for feature additions and enhancements
• Added tests for bug fixes or features
• Linked all related issues
• No unrelated changes

[jonahtanjz]

Thanks @tlylt 👍

Just one suggestion :)

[jonahtanjz]

LGTM 👍

[ang-zeyu]

Not sure if I mentioned this in #1934 as well, but if not then take it as a new point. This tackles only a very small subset of cases if the intention is to streamline the development experience.

Collaborative ones:

• Fresh repo clone
• git pull
• git merge master

Individual ones:

• git stash pop
• copy pasting file from some other place on your PC
• ❔ git is powerful. there are probably a lot more cases where source files can change not related to a checkout

Again, I think we should be providing separate commands that does the build by default to account for all of these. I emphasize separate, so if you don't need to rebuild the typescript files, you don't need to run a watcher -- just build the files once, or not at all, we can let the developer decide based on their individual preferences, workflow (did you do a git stash? merge? ...), PC capabilities (referring the point on tsc watcher being expensive).

While post-checkout is handy, I do not believe we should be relying solely (or at all, for the sake of consistency ("magic" 🎁 that sometimes works but sometimes dosen't)) on it to produce the build artifacts (typescript / anything else) necessary for development. The same goes for cleaning up artifacts in clean.jsvia post-checkout (I only realised this one in retrospect), which does not account for git pull / merge / ....

It also triggers many unnecessary rebuilds / cleans (e.g. checkout to another branch whose HEAD is referencing the same commit).

tldr I think this is ok as an interim solution, I'm still favouring supporting a few separate nuke-everything commands to streamline the development:

// can be less verbose
// the separate commands for the templates can probably be made into cli args as well.
"buildAndDevDocs": "npm run clean && npm run build:backend && node ...index.js s -d -o thedocs",
"buildAndDevDefaultTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o defaulttemplate",
"buildAndDevMinimalTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o minimaltemplate",
// can be less verbose
"watchAndDevDocs": "npm run clean && run the tsc watcher ... && node ...index.js s -d -o thedoc",
"watchAndDevDefaultTemplate": "...",
"watchAndDevMinimalTemplate": "...",
...

[tlylt]

Thanks @ang-zeyu for the detailed comment. Think I should have mentioned more clearly that this is indeed an interim fix in the hope of improving the developer experience.

While not capturing all the cases, especially the unnecessary rebuild when checking out to a new branch whose HEAD is referencing the same commit, it solves most of the issues I faced in the past few weeks of somewhat active development and code review here. For some of the cases listed, they are certainly not in the purview of this PR which makes use of "post-checkout" (and not pull, or merge hooks) that hopefully addresses the case of.......checkout. On the point of "magic", I was thinking that the CLI output of the githook gives quite a bit of hint as to what commands are executed, so it alludes to the underlying working of the script. Of course, this does not replace the details in our DG.

Again, I think we should be providing separate commands that does the build by default to account for all of these. I emphasize separate, so if you don't need to rebuild the typescript files, you don't need to run a watcher -- just build the files once, or not at all, we can let the developer decide based on their individual preferences, workflow (did you do a git stash? merge? ...), PC capabilities (referring the point on tsc watcher being expensive).

tldr I think this is ok as an interim solution, I'm still favouring supporting a few separate nuke-everything commands to streamline the development:

// can be less verbose
// the separate commands for the templates can probably be made into cli args as well.
"buildAndDevDocs": "npm run clean && npm run build:backend && node ...index.js s -d -o thedocs",
"buildAndDevDefaultTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o defaulttemplate",
"buildAndDevMinimalTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o minimaltemplate",
// can be less verbose
"watchAndDevDocs": "npm run clean && run the tsc watcher ... && node ...index.js s -d -o thedoc",
"watchAndDevDefaultTemplate": "...",
"watchAndDevMinimalTemplate": "...",
...

Good points here 👍 would defer to you to put up a tracking issue whenever you are free since I am not entirely sure of any additional details/requirements of the solution you have in mind

[ang-zeyu]

🙆‍♂️

[tlylt]

What is the purpose of this pull request?

• Documentation update
• Bug fix
• Feature addition or enhancement
• Code maintenance
• DevOps
• Improve developer experience
• Others, please explain:

Overview of changes:
Related to discussions in #1934

• a convenient fix to improve developer experience around the need to invoke npm run build:backend every time after checking out to a branch, until an alternative is implemented (see comments in Discontinue the use of TypeScript project references #1934 for details)

Anything you'd like to highlight/discuss:
Post checkout hook inputs reference: https://www.atlassian.com/git/tutorials/git-hooks#:~:text=your%20continuous%20integration.-,Post%2DCheckout,-The

Testing instructions:

• Checkout to this PR branch, the following should be shown
  
• Afterwards, can cd docs and markbind serve -d to see that the docs can be served
• Try modifying the "README.md" file, and discard it via git commit -- README.md, the post checkout hook should not be triggered

Proposed commit message: (wrap lines at 72 characters)
Update post-checkout hook to auto build backend

---

Checklist: ☑️

• Updated the documentation for feature additions and enhancements
• Added tests for bug fixes or features
• Linked all related issues
• No unrelated changes

[jonahtanjz]

Thanks @tlylt 👍

Just one suggestion :)

[jonahtanjz]

LGTM 👍

[ang-zeyu]

Not sure if I mentioned this in #1934 as well, but if not then take it as a new point. This tackles only a very small subset of cases if the intention is to streamline the development experience.

Collaborative ones:

• Fresh repo clone
• git pull
• git merge master

Individual ones:

• git stash pop
• copy pasting file from some other place on your PC
• ❔ git is powerful. there are probably a lot more cases where source files can change not related to a checkout

Again, I think we should be providing separate commands that does the build by default to account for all of these. I emphasize separate, so if you don't need to rebuild the typescript files, you don't need to run a watcher -- just build the files once, or not at all, we can let the developer decide based on their individual preferences, workflow (did you do a git stash? merge? ...), PC capabilities (referring the point on tsc watcher being expensive).

While post-checkout is handy, I do not believe we should be relying solely (or at all, for the sake of consistency ("magic" 🎁 that sometimes works but sometimes dosen't)) on it to produce the build artifacts (typescript / anything else) necessary for development. The same goes for cleaning up artifacts in clean.jsvia post-checkout (I only realised this one in retrospect), which does not account for git pull / merge / ....

It also triggers many unnecessary rebuilds / cleans (e.g. checkout to another branch whose HEAD is referencing the same commit).

tldr I think this is ok as an interim solution, I'm still favouring supporting a few separate nuke-everything commands to streamline the development:

// can be less verbose
// the separate commands for the templates can probably be made into cli args as well.
"buildAndDevDocs": "npm run clean && npm run build:backend && node ...index.js s -d -o thedocs",
"buildAndDevDefaultTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o defaulttemplate",
"buildAndDevMinimalTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o minimaltemplate",
// can be less verbose
"watchAndDevDocs": "npm run clean && run the tsc watcher ... && node ...index.js s -d -o thedoc",
"watchAndDevDefaultTemplate": "...",
"watchAndDevMinimalTemplate": "...",
...

[tlylt]

Thanks @ang-zeyu for the detailed comment. Think I should have mentioned more clearly that this is indeed an interim fix in the hope of improving the developer experience.

While not capturing all the cases, especially the unnecessary rebuild when checking out to a new branch whose HEAD is referencing the same commit, it solves most of the issues I faced in the past few weeks of somewhat active development and code review here. For some of the cases listed, they are certainly not in the purview of this PR which makes use of "post-checkout" (and not pull, or merge hooks) that hopefully addresses the case of.......checkout. On the point of "magic", I was thinking that the CLI output of the githook gives quite a bit of hint as to what commands are executed, so it alludes to the underlying working of the script. Of course, this does not replace the details in our DG.

Again, I think we should be providing separate commands that does the build by default to account for all of these. I emphasize separate, so if you don't need to rebuild the typescript files, you don't need to run a watcher -- just build the files once, or not at all, we can let the developer decide based on their individual preferences, workflow (did you do a git stash? merge? ...), PC capabilities (referring the point on tsc watcher being expensive).

tldr I think this is ok as an interim solution, I'm still favouring supporting a few separate nuke-everything commands to streamline the development:

// can be less verbose
// the separate commands for the templates can probably be made into cli args as well.
"buildAndDevDocs": "npm run clean && npm run build:backend && node ...index.js s -d -o thedocs",
"buildAndDevDefaultTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o defaulttemplate",
"buildAndDevMinimalTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o minimaltemplate",
// can be less verbose
"watchAndDevDocs": "npm run clean && run the tsc watcher ... && node ...index.js s -d -o thedoc",
"watchAndDevDefaultTemplate": "...",
"watchAndDevMinimalTemplate": "...",
...

Good points here 👍 would defer to you to put up a tracking issue whenever you are free since I am not entirely sure of any additional details/requirements of the solution you have in mind

[ang-zeyu]

🙆‍♂️

[tlylt]

What is the purpose of this pull request?

• Documentation update
• Bug fix
• Feature addition or enhancement
• Code maintenance
• DevOps
• Improve developer experience
• Others, please explain:

Overview of changes:
Related to discussions in #1934

• a convenient fix to improve developer experience around the need to invoke npm run build:backend every time after checking out to a branch, until an alternative is implemented (see comments in Discontinue the use of TypeScript project references #1934 for details)

Anything you'd like to highlight/discuss:
Post checkout hook inputs reference: https://www.atlassian.com/git/tutorials/git-hooks#:~:text=your%20continuous%20integration.-,Post%2DCheckout,-The

Testing instructions:

• Checkout to this PR branch, the following should be shown
  
• Afterwards, can cd docs and markbind serve -d to see that the docs can be served
• Try modifying the "README.md" file, and discard it via git commit -- README.md, the post checkout hook should not be triggered

Proposed commit message: (wrap lines at 72 characters)
Update post-checkout hook to auto build backend

---

Checklist: ☑️

• Updated the documentation for feature additions and enhancements
• Added tests for bug fixes or features
• Linked all related issues
• No unrelated changes

[jonahtanjz]

Thanks @tlylt 👍

Just one suggestion :)

[jonahtanjz]

LGTM 👍

[ang-zeyu]

Not sure if I mentioned this in #1934 as well, but if not then take it as a new point. This tackles only a very small subset of cases if the intention is to streamline the development experience.

Collaborative ones:

• Fresh repo clone
• git pull
• git merge master

Individual ones:

• git stash pop
• copy pasting file from some other place on your PC
• ❔ git is powerful. there are probably a lot more cases where source files can change not related to a checkout

Again, I think we should be providing separate commands that does the build by default to account for all of these. I emphasize separate, so if you don't need to rebuild the typescript files, you don't need to run a watcher -- just build the files once, or not at all, we can let the developer decide based on their individual preferences, workflow (did you do a git stash? merge? ...), PC capabilities (referring the point on tsc watcher being expensive).

While post-checkout is handy, I do not believe we should be relying solely (or at all, for the sake of consistency ("magic" 🎁 that sometimes works but sometimes dosen't)) on it to produce the build artifacts (typescript / anything else) necessary for development. The same goes for cleaning up artifacts in clean.jsvia post-checkout (I only realised this one in retrospect), which does not account for git pull / merge / ....

It also triggers many unnecessary rebuilds / cleans (e.g. checkout to another branch whose HEAD is referencing the same commit).

tldr I think this is ok as an interim solution, I'm still favouring supporting a few separate nuke-everything commands to streamline the development:

// can be less verbose
// the separate commands for the templates can probably be made into cli args as well.
"buildAndDevDocs": "npm run clean && npm run build:backend && node ...index.js s -d -o thedocs",
"buildAndDevDefaultTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o defaulttemplate",
"buildAndDevMinimalTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o minimaltemplate",
// can be less verbose
"watchAndDevDocs": "npm run clean && run the tsc watcher ... && node ...index.js s -d -o thedoc",
"watchAndDevDefaultTemplate": "...",
"watchAndDevMinimalTemplate": "...",
...

[tlylt]

Thanks @ang-zeyu for the detailed comment. Think I should have mentioned more clearly that this is indeed an interim fix in the hope of improving the developer experience.

While not capturing all the cases, especially the unnecessary rebuild when checking out to a new branch whose HEAD is referencing the same commit, it solves most of the issues I faced in the past few weeks of somewhat active development and code review here. For some of the cases listed, they are certainly not in the purview of this PR which makes use of "post-checkout" (and not pull, or merge hooks) that hopefully addresses the case of.......checkout. On the point of "magic", I was thinking that the CLI output of the githook gives quite a bit of hint as to what commands are executed, so it alludes to the underlying working of the script. Of course, this does not replace the details in our DG.

Again, I think we should be providing separate commands that does the build by default to account for all of these. I emphasize separate, so if you don't need to rebuild the typescript files, you don't need to run a watcher -- just build the files once, or not at all, we can let the developer decide based on their individual preferences, workflow (did you do a git stash? merge? ...), PC capabilities (referring the point on tsc watcher being expensive).

tldr I think this is ok as an interim solution, I'm still favouring supporting a few separate nuke-everything commands to streamline the development:

// can be less verbose
// the separate commands for the templates can probably be made into cli args as well.
"buildAndDevDocs": "npm run clean && npm run build:backend && node ...index.js s -d -o thedocs",
"buildAndDevDefaultTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o defaulttemplate",
"buildAndDevMinimalTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o minimaltemplate",
// can be less verbose
"watchAndDevDocs": "npm run clean && run the tsc watcher ... && node ...index.js s -d -o thedoc",
"watchAndDevDefaultTemplate": "...",
"watchAndDevMinimalTemplate": "...",
...

Good points here 👍 would defer to you to put up a tracking issue whenever you are free since I am not entirely sure of any additional details/requirements of the solution you have in mind

[ang-zeyu]

🙆‍♂️

[tlylt]

What is the purpose of this pull request?

• Documentation update
• Bug fix
• Feature addition or enhancement
• Code maintenance
• DevOps
• Improve developer experience
• Others, please explain:

Overview of changes:
Related to discussions in #1934

• a convenient fix to improve developer experience around the need to invoke npm run build:backend every time after checking out to a branch, until an alternative is implemented (see comments in Discontinue the use of TypeScript project references #1934 for details)

Anything you'd like to highlight/discuss:
Post checkout hook inputs reference: https://www.atlassian.com/git/tutorials/git-hooks#:~:text=your%20continuous%20integration.-,Post%2DCheckout,-The

Testing instructions:

• Checkout to this PR branch, the following should be shown
  
• Afterwards, can cd docs and markbind serve -d to see that the docs can be served
• Try modifying the "README.md" file, and discard it via git commit -- README.md, the post checkout hook should not be triggered

Proposed commit message: (wrap lines at 72 characters)
Update post-checkout hook to auto build backend

---

Checklist: ☑️

• Updated the documentation for feature additions and enhancements
• Added tests for bug fixes or features
• Linked all related issues
• No unrelated changes

[jonahtanjz]

Thanks @tlylt 👍

Just one suggestion :)

[jonahtanjz]

LGTM 👍

[ang-zeyu]

Not sure if I mentioned this in #1934 as well, but if not then take it as a new point. This tackles only a very small subset of cases if the intention is to streamline the development experience.

Collaborative ones:

• Fresh repo clone
• git pull
• git merge master

Individual ones:

• git stash pop
• copy pasting file from some other place on your PC
• ❔ git is powerful. there are probably a lot more cases where source files can change not related to a checkout

Again, I think we should be providing separate commands that does the build by default to account for all of these. I emphasize separate, so if you don't need to rebuild the typescript files, you don't need to run a watcher -- just build the files once, or not at all, we can let the developer decide based on their individual preferences, workflow (did you do a git stash? merge? ...), PC capabilities (referring the point on tsc watcher being expensive).

While post-checkout is handy, I do not believe we should be relying solely (or at all, for the sake of consistency ("magic" 🎁 that sometimes works but sometimes dosen't)) on it to produce the build artifacts (typescript / anything else) necessary for development. The same goes for cleaning up artifacts in clean.jsvia post-checkout (I only realised this one in retrospect), which does not account for git pull / merge / ....

It also triggers many unnecessary rebuilds / cleans (e.g. checkout to another branch whose HEAD is referencing the same commit).

tldr I think this is ok as an interim solution, I'm still favouring supporting a few separate nuke-everything commands to streamline the development:

// can be less verbose
// the separate commands for the templates can probably be made into cli args as well.
"buildAndDevDocs": "npm run clean && npm run build:backend && node ...index.js s -d -o thedocs",
"buildAndDevDefaultTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o defaulttemplate",
"buildAndDevMinimalTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o minimaltemplate",
// can be less verbose
"watchAndDevDocs": "npm run clean && run the tsc watcher ... && node ...index.js s -d -o thedoc",
"watchAndDevDefaultTemplate": "...",
"watchAndDevMinimalTemplate": "...",
...

[tlylt]

Thanks @ang-zeyu for the detailed comment. Think I should have mentioned more clearly that this is indeed an interim fix in the hope of improving the developer experience.

While not capturing all the cases, especially the unnecessary rebuild when checking out to a new branch whose HEAD is referencing the same commit, it solves most of the issues I faced in the past few weeks of somewhat active development and code review here. For some of the cases listed, they are certainly not in the purview of this PR which makes use of "post-checkout" (and not pull, or merge hooks) that hopefully addresses the case of.......checkout. On the point of "magic", I was thinking that the CLI output of the githook gives quite a bit of hint as to what commands are executed, so it alludes to the underlying working of the script. Of course, this does not replace the details in our DG.

Again, I think we should be providing separate commands that does the build by default to account for all of these. I emphasize separate, so if you don't need to rebuild the typescript files, you don't need to run a watcher -- just build the files once, or not at all, we can let the developer decide based on their individual preferences, workflow (did you do a git stash? merge? ...), PC capabilities (referring the point on tsc watcher being expensive).

tldr I think this is ok as an interim solution, I'm still favouring supporting a few separate nuke-everything commands to streamline the development:

// can be less verbose
// the separate commands for the templates can probably be made into cli args as well.
"buildAndDevDocs": "npm run clean && npm run build:backend && node ...index.js s -d -o thedocs",
"buildAndDevDefaultTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o defaulttemplate",
"buildAndDevMinimalTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o minimaltemplate",
// can be less verbose
"watchAndDevDocs": "npm run clean && run the tsc watcher ... && node ...index.js s -d -o thedoc",
"watchAndDevDefaultTemplate": "...",
"watchAndDevMinimalTemplate": "...",
...

Good points here 👍 would defer to you to put up a tracking issue whenever you are free since I am not entirely sure of any additional details/requirements of the solution you have in mind

[ang-zeyu]

🙆‍♂️

[tlylt]

What is the purpose of this pull request?

• Documentation update
• Bug fix
• Feature addition or enhancement
• Code maintenance
• DevOps
• Improve developer experience
• Others, please explain:

Overview of changes:
Related to discussions in #1934

• a convenient fix to improve developer experience around the need to invoke npm run build:backend every time after checking out to a branch, until an alternative is implemented (see comments in Discontinue the use of TypeScript project references #1934 for details)

Anything you'd like to highlight/discuss:
Post checkout hook inputs reference: https://www.atlassian.com/git/tutorials/git-hooks#:~:text=your%20continuous%20integration.-,Post%2DCheckout,-The

Testing instructions:

• Checkout to this PR branch, the following should be shown
  
• Afterwards, can cd docs and markbind serve -d to see that the docs can be served
• Try modifying the "README.md" file, and discard it via git commit -- README.md, the post checkout hook should not be triggered

Proposed commit message: (wrap lines at 72 characters)
Update post-checkout hook to auto build backend

---

Checklist: ☑️

• Updated the documentation for feature additions and enhancements
• Added tests for bug fixes or features
• Linked all related issues
• No unrelated changes

[jonahtanjz]

Thanks @tlylt 👍

Just one suggestion :)

[jonahtanjz]

LGTM 👍

[ang-zeyu]

Not sure if I mentioned this in #1934 as well, but if not then take it as a new point. This tackles only a very small subset of cases if the intention is to streamline the development experience.

Collaborative ones:

• Fresh repo clone
• git pull
• git merge master

Individual ones:

• git stash pop
• copy pasting file from some other place on your PC
• ❔ git is powerful. there are probably a lot more cases where source files can change not related to a checkout

Again, I think we should be providing separate commands that does the build by default to account for all of these. I emphasize separate, so if you don't need to rebuild the typescript files, you don't need to run a watcher -- just build the files once, or not at all, we can let the developer decide based on their individual preferences, workflow (did you do a git stash? merge? ...), PC capabilities (referring the point on tsc watcher being expensive).

While post-checkout is handy, I do not believe we should be relying solely (or at all, for the sake of consistency ("magic" 🎁 that sometimes works but sometimes dosen't)) on it to produce the build artifacts (typescript / anything else) necessary for development. The same goes for cleaning up artifacts in clean.jsvia post-checkout (I only realised this one in retrospect), which does not account for git pull / merge / ....

It also triggers many unnecessary rebuilds / cleans (e.g. checkout to another branch whose HEAD is referencing the same commit).

tldr I think this is ok as an interim solution, I'm still favouring supporting a few separate nuke-everything commands to streamline the development:

// can be less verbose
// the separate commands for the templates can probably be made into cli args as well.
"buildAndDevDocs": "npm run clean && npm run build:backend && node ...index.js s -d -o thedocs",
"buildAndDevDefaultTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o defaulttemplate",
"buildAndDevMinimalTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o minimaltemplate",
// can be less verbose
"watchAndDevDocs": "npm run clean && run the tsc watcher ... && node ...index.js s -d -o thedoc",
"watchAndDevDefaultTemplate": "...",
"watchAndDevMinimalTemplate": "...",
...

[tlylt]

Thanks @ang-zeyu for the detailed comment. Think I should have mentioned more clearly that this is indeed an interim fix in the hope of improving the developer experience.

While not capturing all the cases, especially the unnecessary rebuild when checking out to a new branch whose HEAD is referencing the same commit, it solves most of the issues I faced in the past few weeks of somewhat active development and code review here. For some of the cases listed, they are certainly not in the purview of this PR which makes use of "post-checkout" (and not pull, or merge hooks) that hopefully addresses the case of.......checkout. On the point of "magic", I was thinking that the CLI output of the githook gives quite a bit of hint as to what commands are executed, so it alludes to the underlying working of the script. Of course, this does not replace the details in our DG.

Again, I think we should be providing separate commands that does the build by default to account for all of these. I emphasize separate, so if you don't need to rebuild the typescript files, you don't need to run a watcher -- just build the files once, or not at all, we can let the developer decide based on their individual preferences, workflow (did you do a git stash? merge? ...), PC capabilities (referring the point on tsc watcher being expensive).

tldr I think this is ok as an interim solution, I'm still favouring supporting a few separate nuke-everything commands to streamline the development:

// can be less verbose
// the separate commands for the templates can probably be made into cli args as well.
"buildAndDevDocs": "npm run clean && npm run build:backend && node ...index.js s -d -o thedocs",
"buildAndDevDefaultTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o defaulttemplate",
"buildAndDevMinimalTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o minimaltemplate",
// can be less verbose
"watchAndDevDocs": "npm run clean && run the tsc watcher ... && node ...index.js s -d -o thedoc",
"watchAndDevDefaultTemplate": "...",
"watchAndDevMinimalTemplate": "...",
...

Good points here 👍 would defer to you to put up a tracking issue whenever you are free since I am not entirely sure of any additional details/requirements of the solution you have in mind

[ang-zeyu]

🙆‍♂️

[tlylt]

What is the purpose of this pull request?

• Documentation update
• Bug fix
• Feature addition or enhancement
• Code maintenance
• DevOps
• Improve developer experience
• Others, please explain:

Overview of changes:
Related to discussions in #1934

• a convenient fix to improve developer experience around the need to invoke npm run build:backend every time after checking out to a branch, until an alternative is implemented (see comments in Discontinue the use of TypeScript project references #1934 for details)

Anything you'd like to highlight/discuss:
Post checkout hook inputs reference: https://www.atlassian.com/git/tutorials/git-hooks#:~:text=your%20continuous%20integration.-,Post%2DCheckout,-The

Testing instructions:

• Checkout to this PR branch, the following should be shown
  
• Afterwards, can cd docs and markbind serve -d to see that the docs can be served
• Try modifying the "README.md" file, and discard it via git commit -- README.md, the post checkout hook should not be triggered

Proposed commit message: (wrap lines at 72 characters)
Update post-checkout hook to auto build backend

---

Checklist: ☑️

• Updated the documentation for feature additions and enhancements
• Added tests for bug fixes or features
• Linked all related issues
• No unrelated changes

[jonahtanjz]

Thanks @tlylt 👍

Just one suggestion :)

[jonahtanjz]

LGTM 👍

[ang-zeyu]

Not sure if I mentioned this in #1934 as well, but if not then take it as a new point. This tackles only a very small subset of cases if the intention is to streamline the development experience.

Collaborative ones:

• Fresh repo clone
• git pull
• git merge master

Individual ones:

• git stash pop
• copy pasting file from some other place on your PC
• ❔ git is powerful. there are probably a lot more cases where source files can change not related to a checkout

Again, I think we should be providing separate commands that does the build by default to account for all of these. I emphasize separate, so if you don't need to rebuild the typescript files, you don't need to run a watcher -- just build the files once, or not at all, we can let the developer decide based on their individual preferences, workflow (did you do a git stash? merge? ...), PC capabilities (referring the point on tsc watcher being expensive).

While post-checkout is handy, I do not believe we should be relying solely (or at all, for the sake of consistency ("magic" 🎁 that sometimes works but sometimes dosen't)) on it to produce the build artifacts (typescript / anything else) necessary for development. The same goes for cleaning up artifacts in clean.jsvia post-checkout (I only realised this one in retrospect), which does not account for git pull / merge / ....

It also triggers many unnecessary rebuilds / cleans (e.g. checkout to another branch whose HEAD is referencing the same commit).

tldr I think this is ok as an interim solution, I'm still favouring supporting a few separate nuke-everything commands to streamline the development:

// can be less verbose
// the separate commands for the templates can probably be made into cli args as well.
"buildAndDevDocs": "npm run clean && npm run build:backend && node ...index.js s -d -o thedocs",
"buildAndDevDefaultTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o defaulttemplate",
"buildAndDevMinimalTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o minimaltemplate",
// can be less verbose
"watchAndDevDocs": "npm run clean && run the tsc watcher ... && node ...index.js s -d -o thedoc",
"watchAndDevDefaultTemplate": "...",
"watchAndDevMinimalTemplate": "...",
...

[tlylt]

Thanks @ang-zeyu for the detailed comment. Think I should have mentioned more clearly that this is indeed an interim fix in the hope of improving the developer experience.

While not capturing all the cases, especially the unnecessary rebuild when checking out to a new branch whose HEAD is referencing the same commit, it solves most of the issues I faced in the past few weeks of somewhat active development and code review here. For some of the cases listed, they are certainly not in the purview of this PR which makes use of "post-checkout" (and not pull, or merge hooks) that hopefully addresses the case of.......checkout. On the point of "magic", I was thinking that the CLI output of the githook gives quite a bit of hint as to what commands are executed, so it alludes to the underlying working of the script. Of course, this does not replace the details in our DG.

Again, I think we should be providing separate commands that does the build by default to account for all of these. I emphasize separate, so if you don't need to rebuild the typescript files, you don't need to run a watcher -- just build the files once, or not at all, we can let the developer decide based on their individual preferences, workflow (did you do a git stash? merge? ...), PC capabilities (referring the point on tsc watcher being expensive).

tldr I think this is ok as an interim solution, I'm still favouring supporting a few separate nuke-everything commands to streamline the development:

// can be less verbose
// the separate commands for the templates can probably be made into cli args as well.
"buildAndDevDocs": "npm run clean && npm run build:backend && node ...index.js s -d -o thedocs",
"buildAndDevDefaultTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o defaulttemplate",
"buildAndDevMinimalTemplate": "npm run clean && npm run build:backend && node ...index.js s -d -o minimaltemplate",
// can be less verbose
"watchAndDevDocs": "npm run clean && run the tsc watcher ... && node ...index.js s -d -o thedoc",
"watchAndDevDefaultTemplate": "...",
"watchAndDevMinimalTemplate": "...",
...

Good points here 👍 would defer to you to put up a tracking issue whenever you are free since I am not entirely sure of any additional details/requirements of the solution you have in mind

[ang-zeyu]

🙆‍♂️