Staging environment for contributor guide / team page?

How do we want to develop our contributor guide and our team page?

To put a text unlinked into the main repository (as I did with the style guide) may be a workable way in exceptional cases. But as a regular procedure? That doesn’t seem reasonable to me.

Possible alternatives are

  • put our development pages on the public team page
  • develop on hackmd.io
  • create a staging environment for team page
  • additional options available?

I would prefer a staging environment. But I don’t know how much work that would take.

Text on hackmd.io could be a temporary solution. But we have no navigation bar, no context, formatting is different (and not all asciidoc options are available). Not optimal.

2 Likes

Do we know if any of the historical staging environment infrastructure can be salvaged? A long time ago, we had something that worked well but I don’t think the staging version of Fedora Docs was kept up with over time.

One possible workflow is to open a discussion about changes and improvements in Fedora Discussion, and then someone can lead on a first draft. The draft can be opened as a GitLab pull request and the team can weigh in with specific comments and feedback on the copytext there.

1 Like

We have docs.stg.fedoraproject.org that we can use. I believe that’s generally been used more for testing tooling changes, but there’s no reason we couldn’t use it for content preview, too. We’d just need to change the staging docs-fp-o config to point to a staging branch in our repos.

Agreed. In case of the contributor’s guide, I made a rough proposal in another thread. In a next step we could create a kind of prototype, i.e. for each intended page an “annotated ToC” and a navigation menu. That way you can assess the flow of arguments, the topics to be covered, etc. How want we to make them visible to the team?

If I remember correctly, darknao mentioned once ago, each repo includes a kind of “public preview”, similar to the local preview on one’s desktop. Maybe we don’t need a public address like docs.stg.fp.o/…/contributors-guide.html, but just create a stg branch. In an early stage, a public stg address may be considered as too public?

We can then discuss that prototype using PRs and/or discussion.

(I could volunteer to create such am “annotated ToC”.)

1 Like

Using docs.stg.fedoraproject.org for this is completely fine to me.
We also have Gitlab Pages deployed here Fedora Documentation Team :: Documentation Contributor's Guide
This is only enabled for the main branch and PRs, but I can set it up for a staging branch if needed.

  • docs.stg.fp-o is updated hourly and is the full docs website (useful to test inter component links)
  • Gitlab pages are updated instantly (or close to), but only contain the contribution guide.

A stg branch would be great. And maybe in the future even a stg2 branch if we want to compare 2 alternatives of it we want to evaluate something just in the team and not publicly available as docs stg. But probably for now we are happy to get something done in stg at all.

And in a first cut I think, for the team and contrib pages we would just need the gitlab preview and could spare the work so set up a stg line in docs.fp.o mindset section as well.

In that case, I would recommend using feature branches instead of a predefined stg, stg2
Opening a PR from these branches will automatically trigger a preview so you can compare both.
There is nothing specific to do. It should just work.

As I understood my web research, a feature branch is just a branch as any branch, but it is short-lived as you might delete it when your feature is completed?

So the workflow is:

  1. I create a branch and commit it to gitlab repo
  2. I create a fork from that branch
  3. I commit to the fork and create a PR for the branch
  4. A website opens magically, and I may have a look on the preview of my modifications and of the branch and compare?

And what if i want someone else to have a look at that branch and my modifications?

Exactly.

In your case, you can skip 2) and commit directly in the branch you created in 1).
The PR will use your new branch as source, and main as destination.
You can then continue to push any numbers of commit to this branch, and the PR will update automatically (that include the preview website).

This new branch is public, so anyone have access to it, same thing for the preview site associated to your PR.

Hmm… another similar case I pointed out to @duffy for headlines on the main page. I believe that this new templete of hers will give work