Github actions build & PR preview #46
Conversation
This is required for when the site is built with a different base url.
Adds github actions to build site, build PR previews and delete closed PR previews.
|
Thanks for this! Yes, that's exactly what we need. How do I test it out? |
I'm going to see if I can merge into the master of my fork and demonstrate a working build and PR. |
|
Thank you @LKedward! Once you nail down the workflow, please document each step from a developer's point of view, either in a "How to contribute" section in README.md, or in CONTRIBUTING.md. I also don't know how this works. |
Ah yes good point, I'll make sure to document this. |
closePR action runs when a pull request comment contains '#delete_preview' and will delete pr site files from gh-pages branch. This avoids a potential race condition on gh-pages branch when merging a pull request.
When a PR preview is built, a banner is appended to nav.html to indicate preview build with link to github pull request.
Initially just detailing pull request workflow and information for pull request previews.
|
To test this out I have merged into my personal fork:
The rendered site files (for both the normal site and for PRs) are pushed to the 'gh-pages' orphan branch https://github.com/LKedward/fortran-lang.github.io/tree/gh-pages. Before this can be merged, a 'gh-pages' branch needs to be created in this main repository by an admin as an orphan branch |
If pull request description contains '#no_preview' then the github action will not build a preview.
|
Sounds good, I'll go ahead and create the orphan branch. |
|
@milancurcic if you have time to set this up, please go ahead! I am quite busy today. |
|
@LKedward done. Is this PR ready to merge? |
Cheers @milancurcic, yep I'm happy with it - ready to merge! |
|
Okay, just merged. Do we now need to have a dummy PR to trigger the build? Notice that the site is currently broken. |
No, it's been built and pushed okay. Can you check in the repo settings that the github pages are pointing to 'gh-pages' branch. |
|
Oh no, I think we can't use the gh-pages branch on github.io repos! |
|
I just realized it too:
|
|
Okay I just reverted this PR. Regarding a possible solution, could we:
|
Thanks. |
By this I just mean that all contributors will have to checkout a different repository. Regarding the github action workflows I've put together here: there is very little that needs changing, I only need to change the repository that it pushes to. |
|
That was a mistake of using a repo and serving it directly. A better approach is to have a repository with the sources, and the CI then builds the page from master and pushes it somewhere else to be served. Second, the name of this repository fortran-lang.github.io is misleading anyway because it is actually serves at fortran-lang.org. So how about we rename this repository to fortran-lang.org, to keep all the history, stars, issues, etc. Then we create a new repository that would actually serve fortran-lang.org. So that it is not confusing, perhaps it can be called fortran-lang.org.deploy or something like that. And then setup a CI at fortran-lang.org that checks each PR (it builds it and pushes somewhere to be looked at, not at fortran-lang.org), and then every master will get built and pushed into fortran-lang.org.deploy to be served at fortran-lang.org. |
|
Now when I think about it, let's just keep https://github.com/fortran-lang/fortran-lang.github.io as is, if GitHub allows it, but it will become the source repository. The fortran-lang.org domain will be served from the new repository, say fortran-lang.org.deploy. The same setup from my previous comment, but we don't need to rename this repository, so people don't need to update their setup. |
I disagree here, this approach, of using the 'gh-pages' branch is quite standard for so-called project sites, see here. Unfortunately I didn't realise github doesn't allow this approach for so-called organisation sites. (I can see no actual reason why it is disallowed here)
We have to keep the rendered html at fortran-lang.github.io since this is a so-called organisation site which serves the site at See here for full explanation: My proposition is similarly based on a two repository approach, but the unbuilt source (current repo contents) is moved to a new repository and fortran-lang.github.io is used for deployment via CI for the reasons mentioned above. Unfortunately as I said, and as you point out, it is an upheaval meaning stars, issues etc are effectively lost. |
No, I did it on purpose as an org page so that repository pages like stdlib automatically inherit the top-level domain. I'm okay with either approach. For the site in production repository name, just fortran-lang.org is my preference. |
|
To lay out my proposed solution more formally:
|
|
@LKedward that's fine, this will work. Note that I routinely deploy from a deploy repository, e.g. https://www.theoretical-physics.com/, is served by https://github.com/certik/tfc-deploy and pushed into it from the https://gitlab.com/certik/theoretical-physics/ source repository. But perhaps it's different if we are part of an organization? I don't know. |
|
The only reason the original workflow didn't work here is because github allows the workflow for project sites but not for organisation/user sites. (I had the workflow working in my fork, but because it was a fork it was a project site not an organisation site.) |
|
We don't have to use an organization page. I chose that because of 2 benefits:
I don't think there are any other advantages. The obvious downside is that you can't do what we're now trying to do here, and we want to do it. If the repo is called However, this doesn't mean that fortran-lang.github.io (this repo) must be an org page. If you disable serving in the settings, it's not a page anymore. There's a number of solutions here that preserve repo metadata (stars, issues, etc.). My favorite actually is to:
But deploying to master of another repo is okay too. It just seems like unnecessary added complexity of carrying a separate repo for deployment. |
@LKedward I don't think this matters at all because GitHub will redirect |
|
It's a clean approach to just have a repository with the sources. But I am fine either way.
What do you mean by inherit top level domain? I think one can always serve to subdomains such as docs.fortran-lang.org with different repositories.
…On Sun, May 3, 2020, at 3:53 PM, Milan Curcic wrote:
We don't have to use an organization page. I chose that because of 2 benefits:
1. You don't need to maintain a production repo (the one being
served), it's done automatically and under the hood by GitHub;
2. Project pages inherit top-level domain.
I don't think there are any other advantages. The obvious downside is
that you can't do what we're now trying to do here, and we want to do
it.
If the repo is called .github.io *and* you chose to serve a page from
it, then it's an org page (and ditto for ).
However, this doesn't mean that fortran-lang.github.io (this repo) must
be an org page. If you disable serving in the settings, it's not a page
anymore.
There's a number of solutions here that preserve repo metadata (stars,
issues, etc.).
My favorite actually is to:
1. Rename this repo so it's not an org page (preserves metadata);
2. Deploy to gh-pages branch.
But deploying to master of another repo is okay too. It just seems like
unnecessary added complexity of carrying a separate repo for deployment.
—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
<#46 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAFAWHGDBV5AFWVF5CU4WTRPXRWZANCNFSM4MXXO3AQ>.
|
Example: https://fortran-lang.org/stdlib/. That page is served from the fortran-lang/stdlib repo. It's just a convenience feature, nothing major. Yes, we can easily serve other project pages as subdomains, it's just a matter of adding a CNAME record. I defer the choice of final implementation for this to you and Laurence. What matters to me is that we have automatic previews and preserve metadata, for both of which it looks like we have solutions. |
|
I see. I think we should not use this master domain feature. Rather, I would serve the whole webpage as a single generated page from a single repo. I feel that's cleaner. We can still pull out docs from other repos.
…On Sun, May 3, 2020, at 4:38 PM, Milan Curcic wrote:
> What do you mean by inherit top level domain? I think one can always serve to subdomains such as docs.fortran-lang.org with different repositories.
Example: https://fortran-lang.org/stdlib/. That page is served from the
fortran-lang/stdlib repo. It's just a convenience feature, nothing
major.
Yes, we can easily serve other project pages as subdomains, it's just a
matter of adding a CNAME record.
I defer the choice of final implementation for this to you and
Laurence. What matters to me is that we have automatic previews and
preserve metadata, for both of which it looks like we have solutions.
—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
<#46 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAFAWBHYTPCQZ7VVOBLII3RPXW4ZANCNFSM4MXXO3AQ>.
|
Ah okay, yep you are right here.
I agree this is by far the simplest and least-disruptive solution. Does anyone know how this will affect existing forks? Update: I've never renamed a repository before but it seems github is very accommodating to renaming repositories: the original repository url will redirect all web traffic and git operations to the new one (assuming we don't create another |
|
I've reopened this PR in #54 for when the repo has been renamed. |
|
I agree. @certik what do you think? |
|
Yes.
…On Thu, May 7, 2020, at 6:41 AM, Milan Curcic wrote:
I agree. @certik <https://github.com/certik> what do you think?
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#46 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAFAWDVAQYBOWH3NYIFG2DRQKT7TANCNFSM4MXXO3AQ>.
|
|
Okay, I'm gonna rename the repo now. |
|
The rename seems like it worked. The website had about 1 minute of downtime while I was applying the custom domain in the settings. It is now served from gh-pages. I think we can now move forward and merge #54 |
|
Sounds good! |
This PR aims to resolve #41.
The approach here is to use github actions to explicitly build the site on push as opposed to the automatic github Jekyll build used currently; this action builds the site using Jekyll on the master branch and pushes to the 'gh-pages' branch. (Repo settings will therefore need to be changed by admin here to point to 'gh-pages' branch).
Additional actions are added for pull requests which are built and pushed to the 'gh-pages' branch under the path 'pr/<pr_number>'; therefore pull requests can be previewed at fortran-lang.org/pr/46/ for example.
To enable the 'pr/<pr_number>' sub-path, the site source has been updated such that all internal site links and references are prepended with
{{site.baseurl}}, see here for explanation.I'm not an expert on github actions so if anyone has more experience and feedback then let me know!
This has been tested on a private repo, but I'm not sure if any extra steps are required for this organisation repo.