Skip to content

Commit 286f29a

Browse files
committed
docs: improvements to the getting-started tutorial
This does two things: 1. Removes mentions of the communitytc instance. We don't want to direct new projects over to the community instance at this time. 2. Re-orders the steps. Previously the tutorial said to connect your repo to Taskcluster *and then* add tasks, but this is the wrong order because the repo needs to have a `tc.yml` file in order for fxci-config generation to succeed. So the order is now: a. Create tasks b. Request Scopes c. Connect to Github
1 parent 059d160 commit 286f29a

File tree

1 file changed

+51
-57
lines changed

1 file changed

+51
-57
lines changed

docs/tutorials/getting-started.rst

Lines changed: 51 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -13,91 +13,85 @@ with your repo in as few steps as possible.
1313

1414
There are three steps to getting running tasks:
1515

16-
1. Install Taskcluster Github
16+
1. Define Tasks
1717
2. Request Permissions
18-
3. Define Tasks
18+
3. Install Taskcluster Github
1919

2020
Let's dive into each!
2121

22-
Install Taskcluster Github
23-
--------------------------
22+
Create Tasks
23+
------------
2424

25-
.. note::
25+
The first step is to define your tasks. You'll need:
2626

27-
If you are not using Github, skip to the next section.
27+
1. A :term:`Decision Task` defined in ``.taskcluster.yml``
28+
2. A Taskgraph setup in the ``taskcluster`` directory
29+
Luckily Taskgraph provides an ``init`` command that can generate both of these
30+
things automatically! Run:
2831

29-
Each Taskcluster deployment has an associated Github app that needs to be added
30-
to your repo. Some apps for known Taskcluster deployments are as follows:
32+
.. code-block:: shell
3133
32-
.. list-table:: Taskcluster Github Apps
33-
:widths: 20 60
34-
:header-rows: 1
34+
$ pip install taskcluster-taskgraph
35+
$ taskgraph init
3536
36-
* - Instance
37-
- Github App
38-
* - `Firefox-CI <https://firefox-ci-tc.services.mozilla.com>`_
39-
- https://github.com/apps/firefoxci-taskcluster
40-
* - `Community <https://community-tc.services.mozilla.com>`_
41-
- https://github.com/apps/community-tc-integration
37+
This will automatically generate all the necessary files. Commit what was
38+
generated:
4239

43-
Follow the link to the Github app for your deployment and click ``Configure``
44-
near the top right. Then select the repository you'd like to enable. If you are
45-
not an admin of the organization you are enabling the repo for, this will send
46-
a request to your Github administrators.
40+
.. code-block:: shell
4741
48-
.. note::
42+
$ git add .
43+
$ git commit -m "Add Taskcluster files"
4944
50-
If you do not see a ``Configure`` button, contact your Github administrators
51-
for assistance.
45+
Land your changes on the default branch (typically ``main``). Nothing will
46+
happen yet, but we need that ``.taskcluster.yml`` file to exist at the root of
47+
the repository for the next step.
5248

5349
Request Permissions
5450
-------------------
5551

56-
Your repository is now connected to Taskcluster, but it won't have permission
57-
to run anything. In the Taskcluster world, permissions are also known as
58-
:term:`scopes <Scope>`. So the next step is to contact your Taskcluster
59-
administrators and request scopes for your project so that it has access to the
60-
resources it needs to run tasks.
61-
62-
Each Taskcluster instance can be managed differently, but here are the processes
63-
to request scopes for some known Taskcluster deployments:
52+
Your repository now has some tasks defined, but it won't have permission to run
53+
anything. In the Taskcluster world, permissions are also known as :term:`scopes
54+
<Scope>`. So the next step is to contact your Taskcluster administrators and
55+
request scopes for your project so that it has access to the resources it needs
56+
to run tasks.
6457

65-
.. list-table:: Taskcluster Github Apps
66-
:widths: 20 60
67-
:header-rows: 1
58+
.. note::
6859

69-
* - Instance
70-
- Process
71-
* - `Firefox-CI <https://firefox-ci-tc.services.mozilla.com>`_
72-
- `File a Bug <https://bugzilla.mozilla.org/enter_bug.cgi?product=Release%20Engineering&component=Firefox-CI%20Administration>`_
73-
* - `Community <https://community-tc.services.mozilla.com>`_
74-
- `File an Issue <https://github.com/taskcluster/community-tc-config/issues/new>`_
60+
For Mozilla's `Firefox-CI <https://firefox-ci-tc.services.mozilla.com>`_ instance,
61+
file a bug under `Release Engineering :: Firefox-CI Administration
62+
<https://bugzilla.mozilla.org/enter_bug.cgi?product=Release%20Engineering&component=Firefox-CI%20Administration>`_
7563

76-
Use a title such as: *Please setup `org/my-repo` with Taskcluster*.
64+
Use a title such as: *Please setup `org/my-repo` with Taskcluster*.
7765

78-
Create Tasks
79-
------------
66+
Install Taskcluster Github
67+
--------------------------
8068

81-
The last step is to define your tasks. You'll need:
69+
.. note::
8270

83-
1. A :term:`Decision Task` defined in ``.taskcluster.yml``
84-
2. A Taskgraph setup in the ``taskcluster`` directory
71+
If you are not using Github, skip this section and reach out to your
72+
Taskcluster administrators, there may be other steps to integrate your
73+
repository.
8574

86-
Luckily Taskgraph provides an ``init`` command that can generate both of these
87-
things automatically! Run:
75+
Each Taskcluster deployment has an associated Github app that needs to be added
76+
to your repo. If you are unsure which app your deployment uses, ask your
77+
Taskcluster administrators.
8878

89-
.. code-block:: shell
79+
.. note::
9080

91-
$ pip install taskcluster-taskgraph
92-
$ taskgraph init
81+
The Github app for Mozilla's `Firefox-CI
82+
<https://firefox-ci-tc.services.mozilla.com>`_ instance can be found here:
83+
84+
https://github.com/apps/firefoxci-taskcluster
9385

94-
This will automatically generate all the necessary files. Commit what was
95-
generated:
86+
Open the page of the Github app for your deployment and click ``Configure``
87+
near the top right. Then select the repository you'd like to enable. If you are
88+
not an admin of the organization you are enabling the repo for, this will send
89+
a request to your Github administrators.
9690

97-
.. code-block:: shell
91+
.. note::
9892

99-
$ git add .
100-
$ git commit -m "Add Taskcluster files"
93+
If you do not see a ``Configure`` button, contact your Github administrators
94+
for assistance.
10195

10296
Now when you push, you should have a working Decision task that generates a
10397
``hello-world`` task as well as a ``docker-image`` task that it depends on!

0 commit comments

Comments
 (0)