tektoncd / website

Tekton Website

TektonCD Website

This repo contains the code behind the Tekton org's website at tekton.dev.

For more information on the Tekton Project, see the community repo.

For more information on contributing to the website see:

• CONTRIBUTING.md
• DEVELOPMENT.md

website's Issues

Getting started guides for project

We need better "Getting started guide" for the tekton projects.

• They should be on the docs/ folder of each of those project (like docs/getting-started/…)
• Repositories to tackle
  • tektoncd/pipeline
  • tektoncd/triggers — the existing one needs enhancement
  • tektoncd/cli
  • tektoncd/dashboard

/kind docs

Setup a periodic job to update the docs

Expected Behavior

We should run the sync daily and pull updates to the docs in automatically.
The main website should track the latest release for each project.
To be defined how to update what the latest release is - manually probably.

Actual Behavior

It's a manual process right now

Additional Info

I would like to do this using a Tekton task/pipeline and automate it using Tekton.

Update Note on Docs page

Expected Behavior

update Note for accuracy and correct spelling error...

Actual Behavior

Current Text:
"Note:
Tekton provides a nunmber of interactive tutorials at try.tekton.dev for developers to get hands-on experience with the project."
Change to something like,
"Note: Tekton provides interative tutorials at tekton-dev.com/try/ for developers to get hands-on experience with the project"
Since first release may only have one tutorial or so, let's remove "the number of" and/or at least correct the typo/spelling and correct to the latest URL for the try page. This assumes the "nelify in the URL will not be needed once the new website is launched. Hotlink works, but text should match whatever the final URL will be? ie. is it try.tekton.dev or tekton.dev/try or tekton.dev.com/try?

Steps to Reproduce the Problem

1. Go here: https://tekton-dev.netlify.com/docs/
2. see the Note statement that shoulc perhaps be updated.

Additional Info

Remove placeholder icons from try page

Expected Behavior

Icons on the try page should link to tutorials that exist or ones that will be available very soon

Actual Behavior

There are many icons that are placeholders and may not be linked to tutorials. This may cause confusion. For example, the "Connect to Anthos platform" and "Connect to Jenkins/Jenkins X".

Additional Info

Some of these icons should perhaps be removed for now, and could be added back later if tutorials are added at a later date.

Should use "hero" Tekton image for preview instead of moon image

Currently we show the moon image when tekton.dev is previewed in twitter, slack etc. We should update this so we instead use the standard Tekton hero image.

Tekton Pipelines v0.11.0 incompatible with Katacoda k8s clusters

Expected Behavior

I expect to be able to use the latest version of Tekton Pipelines in a Katacoda tutorial.

Actual Behavior

Katacoda Kubernetes clusters use version v0.14.0 (check out this Katacoda Kubernetes playground). Unfortunately, the latest Tekton Pipelines release (v0.11.0) requires Kubernetes version v0.15.0.

🚨 Please also note that the minimum version of Kubernetes required to run Tekton is now 1.15.

So, installing the latest version of Tekton Pipelines on a Katacoda Kubernetes cluster now fails with the following error:

{"level":"fatal","logger":"tekton","caller":"sharedmain/main.go:149","msg":"Version check failed","commit":"8c64289","error":"kubernetes version \"v1.14.0\" is not compatible, need at least \"v1.15.0\" (this can be overridden with the env var \"KUBERNETES_MIN_VERSION\")","stacktrace":"github.com/tektoncd/pipeline/vendor/knative.dev/pkg/injection/sharedmain.MainWithConfig\n\tgithub.com/tektoncd/pipeline/vendor/knative.dev/pkg/injection/sharedmain/main.go:149\ngithub.com/tektoncd/pipeline/vendor/knative.dev/pkg/injection/sharedmain.MainWithContext\n\tgithub.com/tektoncd/pipeline/vendor/knative.dev/pkg/injection/sharedmain/main.go:114\nmain.main\n\tgithub.com/tektoncd/pipeline/cmd/controller/main.go:72\nruntime.main\n\truntime/proc.go:203"}

Steps to Reproduce the Problem

1. Open a Katacoda Kubernetes environment (like this one)
2. Install the latest version of Tekton Pipelines (kubectl apply --filename https://storage.googleapis.com/tekton-releases/pipeline/latest/release.yaml)
3. Watch the Tekton Pipeline pods crash because the Kubernetes version is too low (kubectl get pods --namespace tekton-pipelines --watch)

Additional Info

It looks like I can set the KUBERNETES_MIN_VERSION environment variable to get around the Tekton Pipelines version constraint. However, this is not ideal, and I don't know if this will break something with Tekton Pipelines.

Concepts

Expected Behavior

The whole section of "Input and output resources" looks like they need to be changed to "Pipeline Resources".
Pipeline resources
Each task and pipeline may have its own inputs and outputs, known as input and output resources in Tekton. A compilation task, for example, may have a git repository as input and a container image as output: the task clones the source code from the repository, runs some tests, and at last builds the source code into an executable container image.

Tekton supports many different types of resources, including:

git: A git repository
Pull Request: A specific pull request in a git repository
Image: A container image
Cluster: A Kubernetes cluster
Storage: An object or directory in a blob store, such as Google Cloud Storage
CloudEvent: A CloudEvent
Pipeline Resources are specified as custom resources in a Kubernetes cluster.

Actual Behavior

Input and output resources
Each task and pipeline may have its own inputs and outputs, known as input and output resources in Tekton. A compilation task, for example, may have a git repository as input and a container image as output: the task clones the source code from the repository, runs some tests, and at last builds the source code into an executable container image.

Tekton supports many different types of resources, including:

git: A git repository
Pull Request: A specific pull request in a git repository
Image: A container image
Cluster: A Kubernetes cluster
Storage: An object or directory in a blob store, such as Google Cloud Storage
CloudEvent: A CloudEvent
Resources are specified as custom resources in a Kubernetes cluster.

Steps to Reproduce the Problem

Additional Info

Title blue on black is not readable.

Configure Google Analytics for the website

Expected Behavior

The website should report information about views and visitors through an analytics platform.

Actual Behavior

We appear to have Google Analytics already configured for the website but it's unclear whose account the ID is tied to, and therefore where to go to see the current stats. We also probably need to figure out some way for these analytics to be shared with the wider group.

Additional Info

See config.toml for the current configuration.

Is there anyone know about the katacoda for tekton?

I found a tutorial at here https://www.katacoda.com/ratrosyu/scenarios/playground

I want to provide a Chinese version against it if anyone can give me a hint about the place of its source code.

I search them in Github. Found out a git commit history from @chenyumic. If you know something about this, please help me to move forward. Thanks.

Move dashboard tutorial to Tektoncd/website repo + add license file

Expected Behavior

The preferred location for tekton tutorials, in particular those displayed/referenced on https://tekton.dev/try/ should be located within the tekton github repo
Desired changes to consider:

1. Move tutorial from https://github.com/ncskier/katacoda/ to a tutorial folder on the https://github.com/tektoncd/website
2. Use a Tekton Id with the katacoda
3. Add appropriate license file
   • reference ncskier/katacoda#2 (comment)
4. consider where to store translation copy

Actual Behavior

tutorial opens in personal repo

Steps to Reproduce the Problem

Additional Info

Doc bug:

Links from: https://tekton.dev/docs/triggers/

In the bottom: Getting Started Tasks, links 404

https://tekton.dev/docs/triggers/create-webhook.yaml
https://tekton.dev/docs/triggers/create-ingress.yaml

Add Dashboard Tutorial to the Website

Expected Behavior

I expect the website's tutorial page to have a tutorial for using the Dashboard.

Based on a discussion in the Docs & Website meeting, I created a Tekton Dashboard tutorial in Katacoda: https://www.katacoda.com/ncskier/scenarios/tekton-dashboard. The intent of this tutorial is to have the website's Monitor with Tekton dashboard tutorial link to my Katacoda tutorial.

Please let me know if there are any updates/improvements I should make to my Katacoda tutorial; for example, to improve consistency across tutorials.

Actual Behavior

The Monitor with Tekton dashboard tutorial does not link to anything.

Additional Info

FYI
@bobcatfish
@michaelawyu

Getting started with tekton

Based on/Linked with #16, we should have a general getting started on tekton that brings together the key components of Tekton in a digestable, easy getting started guide.

Most likely based on something similar to tutorial.md but using the cli and triggers most likely.

As part of the “Getting started with Tekton” we need to identify the documentation entry point (where to start reading) and include a link to it from Triggers, Pipelines, experimental, etc.

/kind documentation

Both of the getting started links on the triggers page are dead

Expected Behavior

Click on a getting started link (e.g. create a github webhook), see documentation.

Actual Behavior

Click on a getting started link, get a 404.

Steps to Reproduce the Problem

1. Start browser
2. Visit documentation
3. Haz sad.

Additional Info

https://tekton.dev/docs/triggers/

Add Tekton robotic cat (in color) image to tekton.dev

Expected Behavior

We want to see the familiar colored robotic cat image similar to the sticker available from cd.foundation or the image currently on the existing tekton.dev site

Actual Behavior

The only robotic cat is a very tiny white on black version in the masthead.

Additional Info

See https://cd.foundation/projects/ and https://tekton.dev/ for images requested.

Too many repos are named with 'website'

Please consider using a different repo name. Like tektoncd-website or others.

Topic: Authoring a Pipeline

• A guide on the Pipeline contract from an author perspective
• Best practices on development loops and debugging

Should be in tektoncd/pipeline

/kind documentation

Got error when executing Hugo server

Output is here:

Building sites … WARN 2019/04/14 18:34:32 Page's .Hugo is deprecated and will be removed in a future release. Use the global hugo function.
ERROR 2019/04/14 18:34:32 error: failed to transform resource: SCSS processing failed: file "stdin", line 11, col 1: File to import not found or unreadable: bulma/sass/utilities/initial-variables.
Total in 8 ms
Error: Error building site: logged 1 error(s)

Hugo Static Site Generator v0.55.0/extended darwin/amd64 BuildDate: unknown

OS: Mac OS version 10.13.6

Topic: Scope of Tektoncd components

Document and make it clear what the scope of tektoncd is, and each components.

/kind documentation

ascii demo need to be done with v1beta1

The demo on the front page (using asciimedia ?) needs to be redone with v1beta1 APIs. Right now it is showing v1alpha1 😝

/kind documentation

Dashboard docs - add link or pointer to tutorial for reference

Expected Behavior

Let the user know there is a tutorial about the dashboard on the Try page

Actual Behavior

The dashboard documentation page does not mention the tutorial. I think it would be useful to mention that the tutorial is available from the try page, and perhaps add direct link?

Steps to Reproduce the Problem

1. https://tekton.netlify.com/docs/dashboard
2. read thru the page
3. no mention of existing tutorial to check out

Additional Info

Publish API references

As part of tekton.dev documentation, we should publish the API references of our APIs

See https://knative.dev/docs/reference/ and https://knative.dev/docs/reference/serving-api/ as an example

/kind documentation

Avoid downloading image from GCS when generating website

Expected Behavior

It should be possible to build and preview the website without requiring access to a GCS bucket for the background image.

Actual Behavior

The makefile commands used to build and run the website run sync.py which requires GCP credentials:

website/sync/sync.py

Lines 26 to 31 in 43e149b

	if GCP_NETLIFY_ENV_CRED:
	credentials = service_account.Credentials.from_service_account_info(json.loads(GCP_NETLIFY_ENV_CRED))
	gcs_client = storage.Client(project=GCP_PROJECT,
	credentials=credentials)
	else:
	gcs_client = storage.Client()

It seems like the reason is to grab the background image:

website/sync/sync.py

Lines 105 to 107 in 43e149b

	def download_background_image():
	blob = gcs_bucket.blob('featured-background.jpeg')
	blob.download_to_filename('./content/en/featured-background.jpeg')

Additional Info

Maybe we can commit the background image to the repo instead? I have a feeling I'm missing something here

The Rabbit in the Tekton and friends logo is barely visible

Expected Behavior

The logo with Tekton friends should be clearly visible.

Actual Behavior

The rabbit in the logo is barely visible as the purple/blue color with the black background makes it difficult to see.

Steps to Reproduce the Problem

See here: https://deploy-preview-24--tekton-dev.netlify.com/

Note: Strangely when you take a screenshot the rabbit gets highlighted but that's not what you see normally. Attaching a screenshot anyways.

Make "search this site" work or remove it

Expected Behavior

I don't really know how "search this site" should work but i think it should only return results from this site?

Actual Behavior

When I try searching for "tutorial" I get this:

Additional Info

Maybe it's hard coded to search tekton.dev, in which case we probably need to update the search logic to use a netlify environment variable to search the preview site.

Markdown formatting not being preserved

Expected Behavior

Markdown formatting in the docs should be preserved when synced to the website.

Actual Behavior

Some markdown formatting appears to be broken:

• List ordering is not preserved
• Other formatting broken in some cases

Steps to Reproduce the Problem

For example:

1. View Triggers install docs

Triggers repo:
https://github.com/tektoncd/triggers/blob/master/docs/install.md

Website:
https://tekton.netlify.com/docs/triggers/install/

Also notice the _See Role-based access control for more information_. after the second code block.

Additional Info

This might be the result of a stricter markdown processor being used for the website vs. GitHub.

Update docs synced to tekton-dev.netlify.dev

Expected Behavior

The docs at tekton-dev.netlify.dev for the tektoncd projects should be at the latest released versions:

• Pipelines: 0.11-rc3
• Triggers: 0.3.1 (0.4 end of march)
• CLI 0.8
• Dashboard 0.5.3 (0.6 will support beta, probably end of March?)

Actual Behavior

The docs are currently synced from:

• https://github.com/michaelawyu/pipeline
• https://github.com/michaelawyu/triggers

Additional Info

• The docs must include a header that is parsed by the doc generation code, which is why the docs are currently synced from forks, e.g.:

  ---
  title: "Triggers"
  linkTitle: "Triggers"
  weight: 0
  description: >
    Event Triggers
  ---
  

• In the long run we want #34 this is just an interim update.

Website CSS broken an certain screen sizes

Expected Behavior

For the the text to be centered on my monitor

Actual Behavior

The CSS flow breaks

Steps to Reproduce the Problem

1. Go to tekton.dev
2. Open the developers tools and go to mobile/responsive view
3. Change the resolution to 1920x1080

Additional Info

Two Possible Solutions:

1. Vertically Center the text
2. Make the text 100vw

Preview of Changes

website changes

"Edit this page" leads to 404 for sub pages

Expected Behavior

Clicking the 'Edit this page' link should bring me to the corresponding file in GitHub.

Actual Behavior

Sub-pages under 'Tasks and Pipelines' and 'Triggers' lead to a 404

Steps to Reproduce the Problem

1. Go to https://tekton.netlify.com/docs/pipelines/pipelineruns/
2. Click 'Edit this page' in the top right corner
3. Land on https://github.com/tektoncd/website//edit/master/content/en/docs/Pipelines/pipelineruns.md which gives a 404

Additional Info

Sub-pages for Pipelines and Triggers are being synced from the docs folder in their respective repos, so the 'Edit this page' links pointing to the website repo are wrong.

Publish CLI references

As part of tekton.dev documentation, we should publish the CLI references of tkn

See https://knative.dev/docs/reference/client/ and https://github.com/tektoncd/cli/tree/master/docs/cmd (reference docs are already generated, we just need to sync them and "present" them)

/kind documentation

Create versioned docs

Expected Behavior

We should have hosted and versioned Tekton docs, based on the markdown files we have in each repo, maybe starting with just Pipelines.

Actual Behavior

• Pipelines docs are always tracking head: https://github.com/tektoncd/pipeline/tree/master/docs
• Or you can go to a lot of trouble and view them at the tag https://github.com/tektoncd/pipeline/tree/v0.4.0/docs which probably no one ever does cuz it's a hassle

Relative Links are Broken.

Expected Behavior

I accept that when I click on Tekton Pipeline Link it should give me some type of documentation.

Actual Behavior

It sends me to the github documentation

Steps to Reproduce the Problem

1. Go to https://tekton.dev/docs/pipelines/
2. Click on pipeline metric
3. It should send you to https://tekton.dev/docs/pipelines/metrics

Additional Info

I think the scraper should change the absolute link to the relative link if the relative link does not return a 400 type error.

Topic: Authoring a Task

• A guide on the task contract from an author perspective
• What env cars get exposed, what paths can be expected, etc.
• Best practices on development loops and debugging

Should be in tektoncd/pipeline

/kind documentation

Dashboard - improve "which release should I use" reference

Expected Behavior

In "Important" section, please point to details for which release to use at this link https://github.com/tektoncd/dashboard#which-version-should-i-use

Actual Behavior

Currently points to releases page,https://github.com/tektoncd/dashboard/releases. The readme.md page would be a better choice to point directly to this section https://github.com/tektoncd/dashboard#which-version-should-i-use to quickly determine which version combination to use.

Steps to Reproduce the Problem

1. go to https://tekton-dev.netlify.com/docs/dashboard/
2. scroll down to important highlighted section.
3. See URL pointing to https://github.com/tektoncd/dashboard/releases

Additional Info

Link to Tekton presentations?

Expected Behavior

That I can find the good Tekton presentations, that I know exists (e.g. from KubeCon), from the website.

Actual Behavior

There are mostly static content on the website. It would be great to link to good Tekton presentations, unless there are valid reasons this is not done.

Updates for Try page

Expected Behavior

a richer tutorial / educational experience

Actual Behavior

We need more content on the https://tekton.dev/try/

Steps to Consider

1. Review original Try page structure to see if any of it should be restored now
2. Add Video section for more content
   For example: a new section something like " Additional references to learn from"
   Using theTekton Pipeline CLI: https://www.youtube.com/watch?v=9A2paWzvD10.3.

Additional Information

reference notes in the tekton docs meeting notes from April 29, 2020: https://docs.google.com/document/d/1nnJe4rWBFZORW9ScV9o-yk6BmvX419DDKKwIlORRhsY/

Change sync script to be more flexible.

Discussed this at the docs working group on April 22nd. With our current approach, switching the sync script to pull specific release tags instead of master means we wouldn't be able to publish updated docs between releases.

Current Issue:

• You can not patch version releases for doc updates if needed
• change sync script to be more flexible ???

This issue was taken from:
Originally posted by @AlanGreene in #90

These issues seem to be a blocker for this PR.

Topic: Authoring a PipelineResource

• A guide on the Resource contract from an author perspective

As this is not part of the beta API, this is lower priority

Should be in tektoncd/pipeline

/kind documentation

Tekton end user documentation organization

We need to decide and document where end-user documentation (getting started guide, advanced guide, …) are written into.

Proposal:

• Any documentation that is for a project only (like triggers, pipeline, …) should be in the docs/ folder of the project
• Any documentation that crosses project's boundaries (like a general getting-started guide, or some advanced topics…) should be in the docs/ folder of this project (tektoncd/website)

/kind documentation

Update tekton.dev content

Expected Behavior

Site should:

• Describe projects (not just pipelines)
• Link to docs for each project
• Link to install, mailing list (other community stuff)

Actual Behavior

Site only mentions pipelines and says it is under construction.

Additional info

Look at skaffold.dev for inspiration

Add Triggers Tutorial to Website Try Page

Here's a fun Triggers 101 Tutorial by @ncskier in article form. It might be a really nice scenario to put into Katacoda.
This tutorial as written is based on OpenShift. It could be reworked for Katacoda without OpenShift if necessary.

Or, alternatively, it could be just linked to as is.

Additional Info

Link to published tutorial article: https://developer.ibm.com/tutorials/tekton-triggers-101/

Audit and update tutorials

Expected Behavior

• Tutorials at the "try" link at https://tekton-dev.netlify.com/ should be accurate representations of how to use Tekton Pipelines.
• These tutorials should use v1beta1 Tekton Pipelines resources

Actual Behavior

• The tutorials use v1alpha1 resources at https://github.com/michaelawyu/tekton-examples
• Some of the tutorials aren't quite correct, e.g. the pipelines tutorial runs the two tasks in parallel and the built image is not used in the deploy

Automatically sync docs from Tekton repos to Website

Expected Behavior

Changes to the docs of a Tekton repo such as Pipeline should be reflected in the Website as soon as possible.

Actual Behavior

At the moment we have a script that syncs docs from a fork of Pipeline. The script expects a special table at the top of docs and during the initial review of the website this was deemed as a bit of an ugly addition given that it only served the syncing script.

TODO(sbwsg): Update this issue with details of the script and the table that's needed. Link to any PR discussion that was added around this.

Unable to access https://tekton.dev

Getting the following error if I'm trying to access it

Repo docs are kinda sparse 😅

We should add:

• CONTRIBUTING.md
• DEVELOPMENT.md
• Pull request + issue templates

We should probably have more in the README than we currently have:

( 🤣 d is for @dlorenc )

Update tekton.dev with proper Linux Foundation privacy, terms, and CDF logo

Expected Behavior

1. Place the following language
   "Copyright © {YYYY} The Linux Foundation®. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page. Linux is a registered trademark of Linus Torvalds. Privacy Policy and Terms of Use"

Privacy URL: https://www.linuxfoundation.org/privacy
Terms URL: https://www.linuxfoundation.org/terms/

2. Replace {YYYY} with current year
3. CDF Icon Logo - https://github.com/cdfoundation/artwork/tree/master/cdf/icon/color
   Other logos available - https://github.com/cdfoundation/artwork/tree/master/cdf

Additional Info

Example: https://www.spinnaker.io/ footer for reference

Topic: Authoring a Condition

• A guide on the condition contract from an author perspective
• What env cars get exposed, what paths can be expected, etc.
• Best practices on development loops and debugging

Should be in tektoncd/pipeline

/kind documentation

Add Triggers Tutorial to Website Try Page

Here's a fun Triggers 101 Tutorial by @ncskier in article form. It might be a really nice scenario to put into Katacoda.
This tutorial as written is based on OpenShift. It could be reworked for Katacoda without OpenShift if necessary.

Or, alternatively, it could be just linked to as is.

Additional Info

Link to published tutorial article: https://developer.ibm.com/tutorials/tekton-triggers-101/.

Update OWNERS list

Expected Behavior

https://github.com/tektoncd/website/blob/master/OWNERS should be a list of folks we expect to review PRs in this repo.

Actual Behavior

I think @vdemeester and I are the only ones on that list for whom that qualifies at the moment.