Repository navigation
Initial revision of documentation for contributors - #13
Conversation
molinaro-m
left a comment
molinaro-m
left a comment
There was a problem hiding this comment.
I skimmed through the text.
I think that it is fine, at least for now.
Maybe a little too much for an entry user, but on Wdnesday we will have feedback on that.
gmantele
left a comment
gmantele
left a comment
There was a problem hiding this comment.
Maybe it would useful for the users to know a bit about the repository structure, and especially in which directory are the files to change or add (i.e. content/). I don't think we should invite them to change anything in layout/ for instance.
|
|
||
| ## Install Git | ||
|
|
||
| If you do not have it already, then you will need to [install git](https://github.com/git-guides/install-git) in order to work on the website locally. |
There was a problem hiding this comment.
There is a simpler alternative that may interest some users not familiar with Git: changes (with branch and PullRequest) can be done online on the GitHub website. This way, there is no need to install Git.
I propose this, but I rarely apply my changes on the GitHub/GitLab website, but I know it is possible. Do you think it would worth saying this is also possible?
There was a problem hiding this comment.
Editing files directly in Github seems okay for minor changes like fixing mispellings. I would not encourage it for anything major like adding new pages or major rewrites of pages.
Probably I wouldn't include it in the contributing doc as an option. I would still prefer the PR procedure, even for small changes.
There was a problem hiding this comment.
I agree, it is not ideal as not really an as complete solution as a clone of the repository. Although, creating a new page is not that complicating or risky, but ok, let's already start with the clone solution.
|
|
||
| Hugo is required for building the site locally to check and preview your changes. You may follow the [installation instructions](https://gohugo.io/installation/) for your platform. | ||
|
|
||
| A quick procedure to download Hugo on Linux from the [release page](https://github.com/gohugoio/hugo/releases) is: |
There was a problem hiding this comment.
For our website, I wrote a Makefile which lets start a local preview of the current website. Before starting this preview, it checks whether Hugo is installed in the current local directory. If not, it download it from the GitHub Release page and "install" it. This is quite transparent, and also allows me to upgrade Hugo on the users side without having to ask them to do so.
This Makefile works really well on Linux, maybe on MacOS (as it is Unix based ; one may have to test it sometime), not at all on Windows.
Do you think it could be something interesting to share in this repo?
There was a problem hiding this comment.
Yes, I think that could be useful. A make build to execute hugo -D would be nice and also maybe make run or something like that to start the server.
There was a problem hiding this comment.
I'll try to prepare some PR then.
Agreed - I'll try to add some additional text indicating where the content pages should go. |
I agree that it could be overwhelming for an entry level user. I am thinking that the sections on Git and Github could be streamlined by pointing to some existing external documentation, e.g., the parts on how to make a PR and the It's also possible that the local |
This is the initial version of documentation for contributors.