README: clarify how to start working on this site locally #1890
Conversation
dscho
force-pushed
the
explain-better-how-to-develop-this-site-with-sparse-checkouts
branch
from
d75da14 to
e98a823
Compare
This comment was marked as off-topic.
This comment was marked as off-topic.
README.md
Outdated
| ## Local development setup | ||
|
|
||
| It is highly recommended to clone this repository using [`scalar`](https://git-scm.com/docs/scalar); This allows to work only on the parts of the repository relevant to your interests. You can select which directories are checked out using the [`git sparse-checkout add <directory>...`](https://git-scm.com/docs/git-sparse-checkout) command. The relevant directories are: | ||
| It is highly recommended to clone this repository using [`scalar`](https://git-scm.com/docs/scalar); This allows to work only on the parts of the repository relevant to your interests. You can select which directories are checked out using the [`git sparse-checkout add <directory>...`](https://git-scm.com/docs/git-sparse-checkout) command. Typically, you will want to start like this: |
There was a problem hiding this comment.
sorry, i've not been looking a lot into all the changes, and this is a bit out of scope, but: why are we recommending new contributors to use yet another (advanced) tool?
Scalar is a repository management tool that optimizes Git for use in large repositories
when the website was just a rails app it was "simple" enough for no one even think about that. now that we have a static website do we really need scalar? I'd expect git to be able to cope with this simple repo without any issue
There was a problem hiding this comment.
most of the past contributors are new users who still struggle with branches and commits. adding references to scalar seems to just increase the entry barrier
There was a problem hiding this comment.
For what it's worth, I had the same thought and agree with @pedrorijo91, but decided against bringing it up in my initial review (for whatever reason, I'm not sure!).
There was a problem hiding this comment.
The problem that using scalar (or: partial & sparse clones, really) solves is that running Hugo and particularly Pagefind takes a really long time. In CI, Hugo spends 30+ seconds, Pagefind even 2+ minutes, to process the 25k pages (plus 45k redirects). As a contributor who wants to fix only a style issue or a typo, I find this daunting. I may be quite impatient...
There was a problem hiding this comment.
when the website was just a rails app it was "simple" enough for no one even think about that. now that we have a static website do we really need scalar? I'd expect git to be able to cope with this simple repo without any issue
For the record: I never got the Rails app to work locally, not to the extent that it would render anything interesting, at least.
And yes, Git would cope with this simple, if large, repo just fine. The complete site has a lot of content, is all... last time I looked, my full public/ folder weighed 1.2GB...
There was a problem hiding this comment.
I've updated the instructions now.
There was a problem hiding this comment.
Funny thing, I read this instruction after I git-cloned the repo, so I didn't bother to use scalar (confession, I've never used it). So my thought were "hey, but I've cloned it already, what now??"
There was a problem hiding this comment.
Yes, Hugo does not really work incrementally, and Pagefind cannot work incrementally.
@dscho Isn't that what hugo serve -w does? When I start that it takes ~30s to build the site, and when I change a page only ~5s to update.
There was a problem hiding this comment.
Funny thing, I read this instruction after I
git-cloned the repo, so I didn't bother to usescalar(confession, I've never used it). So my thought were "hey, but I've cloned it already, what now??"
That's a good point @To1ne. How about something along these lines:
Note
If you already have a full clone and wish to accelerate development by focusing only on a small subset of the pages, you may want to run the git sparse-checkout set [...] command mentioned above.
Yes, Hugo does not really work incrementally, and Pagefind cannot work incrementally.
@dscho Isn't that what
hugo serve -wdoes?
Well, yes and no. It starts out with a full build, always, and then updates incrementally while running whenever the files are changed. But the initial build is never incremental, that's why I said not really ;-)
When I start that it takes ~30s to build the site, and when I change a page only ~5s to update.
Right. But that misses updates required for the Pagefind index.
Therefore, for practical purposes, I consider the build non-incremental.
There was a problem hiding this comment.
How about something along these lines:
Note
If you already have a full clone and wish to accelerate development by focusing only on a small subset of the pages, you may want to run the
git sparse-checkout set [...]command mentioned above.
Updated accordingly.
dscho
force-pushed
the
explain-better-how-to-develop-this-site-with-sparse-checkouts
branch
from
e67353e to
459cf48
Compare
The information was all there, but a couple of concrete commands that can be copy/pasted go a long way to be even more helpful. Co-authored-by: Taylor Blau <[email protected]> Signed-off-by: Johannes Schindelin <[email protected]>
There might be setups where Scalar is _not_ included in the default installation; Let's provided helpful instructions for those scenarios, too, even if it is unclear how common such setups are. Signed-off-by: Johannes Schindelin <[email protected]>
The advice to use Scalar comes too late for contributors who already have obtained a (full) clone. To help them, let's just suggest to convert the checkout into a sparse one. Suggested-by: Toon Claes <[email protected]> Signed-off-by: Johannes Schindelin <[email protected]>
dscho
force-pushed
the
explain-better-how-to-develop-this-site-with-sparse-checkouts
branch
from
459cf48 to
643b333
Compare
|
I'll go ahead and merge, as it is better to have the changes than not. Should it need more work, I will happily work on that in a separate PR. |
dscho
deleted the
explain-better-how-to-develop-this-site-with-sparse-checkouts
branch
Changes
The README was changed to start with the exact commands to start local development.
Context
When I tried to run through those steps to get a clean local setup, I thought I understood what I had written there, and still I had to work through a couple of failed attempts until I got all those commands right and could run
hugosuccessfully.Based on this experience, I expect that the DX was quite frustrating. Let's hope that these improvements help in the future.