Skip to content

Commit 373f647

Browse files
mikej888mikej888
committed
Updated and expanded TravisCI HelloWorld.md
1 parent ce208cf commit 373f647

File tree

1 file changed

+149
-47
lines changed

1 file changed

+149
-47
lines changed

‎travis/HelloWorld.md

Lines changed: 149 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -12,98 +12,200 @@ If you already have an account, then visit [GitHub](https://github.com) and sign
1212

1313
In the following text, replace `USERNAME` with your GitHub user name.
1414

15-
Fork this repository on GitHub
16-
------------------------------
17-
18-
* Visit https://github.com/softwaresaved/build_and_test_examples.
19-
* Click Fork.
20-
* If asked "Where should we fork this repository?", select your account.
21-
22-
Sign in to Travis CI
23-
--------------------
15+
Create a new repository on GitHub
16+
---------------------------------
2417

25-
Once you have an account on GitHub, you can use this to sign in to Travis CI:
18+
Visit https://github.com/USER.
2619

27-
* Visit [Travis CI](https://travis-ci.org).
28-
* Click on Sign in with GitHub.
20+
Click **Repositories** tab.
2921

30-
Enable your repository on Travis CI
31-
-----------------------------------
22+
Click **New**.
3223

33-
Now, tell Travis CI to check for changes in your repository:
24+
Enter Repository name: `travis-lab`
3425

35-
* Click on your name on the top-right of the Travis CI page.
36-
* This page shows a list of your GitHub repositories that Travis CI knows about.
37-
* If you cannot see `USERNAME/build_and_test_examples`, then click the Sync button.
38-
* Once you can see `USERNAME/build_and_test_examples`, then click on the repository switch (the X button) so that Travis CI knows to check that repository for changes.
26+
Click **Create repository**.
3927

4028
Clone your fork locally
4129
-----------------------
4230

43-
* Within a command-line shell, clone your fork:
31+
Within a terminal window, clone your forked repository:
4432

4533
```
46-
$ git clone https://github.com/USERNAME/build_and_test_examples
47-
$ cd build_and_test_examples
34+
$ git clone https://[email protected]/USERNAME/travis-lab
35+
Cloning into 'travis-lab'...
36+
warning: You appear to have cloned an empty repository.
37+
Checking connectivity... done.
38+
$ cd travis-lab
4839
```
4940

50-
Create a "hello world" `.travis.yml` job file
51-
---------------------------------------------
41+
The warning is expected. We'll now add some content.
5242

53-
Travis CI looks for a file called `.travis.yml` in a Git repository. This file tells Travis CI how to build and test your software. In addition, this file can be used to specify any dependencies you need installed before building or testing your software. So, let's try a simple example:
43+
Create a "hello world" program
44+
------------------------------
5445

55-
* Create a short Python script, `hello.py` in your repository, with the content:
46+
Create a short Python script, `hello.py`, in your repository, with the content:
5647

5748
```
58-
print("Hello world from Travis CI")
49+
print("Hello world!")
50+
````
51+
52+
Run it:
53+
54+
```
55+
$ python hello.py
56+
Hello world!
5957
```
6058
61-
* Create `.travis.yml`, with the content:
59+
Add and commit this file to your repository and push the changes to GitHub:
60+
61+
```
62+
$ git add hello.py
63+
$ git commit -m "Added Python hello world script" .
64+
$ git push origin master
65+
```
66+
67+
Visit https://github.com/USERNAME/travis-lab and check that the repository now contains `hello.py`.
68+
69+
Sign in to Travis CI
70+
--------------------
71+
72+
Once you have an account on GitHub, you can use this to sign in to Travis CI, so go to Travis CI, https://travis-ci.org/.
73+
74+
Click on Sign in with GitHub.
75+
76+
Enable your repository on Travis CI
77+
-----------------------------------
78+
79+
Now, you need to tell Travis CI to check for changes in your repository, so click on your name on the top-right of the Travis CI page and select **Accounts**.
80+
81+
This will take you to a page, https://travis-ci.org/profile/USERNAME, which shows a list of your GitHub repositories that Travis CI knows about.
82+
83+
If you cannot see `USERNAME/travis-lab`, then click the **Sync account** button which tells Travis CI to check your current repositories on GitHub.
84+
85+
When you can see `USERNAME/travis-lab`, then click on the button next to it to instruct Travis CI to monitor that repository for changes. The X icon should change to a check/tick icon.
86+
87+
Create a `.travis.yml` job file
88+
-------------------------------
89+
90+
Travis CI looks for a file called `.travis.yml` in a Git repository. This file tells Travis CI how to build and test your software. In addition, this file can be used to specify any dependencies you need installed before building or testing your software. So, let's add one.
91+
92+
Create `.travis.yml` with the content:
6293
6394
```
6495
language: python
6596

6697
python:
98+
6799
- "2.7"
68100

69101
script:
102+
70103
- python hello.py
71104
```
72105
73-
* This says we want Travis CI to set up a Python 2.7 environment, then run our `hello.py` script.
74-
* Add and commit these files to your repository and push the changes to GitHub:
106+
This says we want Travis CI to set up a Python 2.7 environment, then run our hello.py script.
107+
108+
Add and commit this file to your repository and push the changes to GitHub:
75109
76110
```
77-
$ git add hello.py .travis.yml
78-
$ git commit -m "Python hello world script and Travis CI job file" .
111+
$ git add .travis.yml
112+
$ git commit -m "Added Travis CI job file" .
79113
$ git push origin master
80114
```
81115
116+
Visit https://github.com/USERNAME/travis-lab and check that the repository now contains `.travis.yml`.
117+
82118
Explore the Travis CI job information
83119
-------------------------------------
84120
85-
Travis CI provides a page summarising the most recent jobs run for your repositories:
121+
Visit https://travis-ci.org/USERNAME. You should see a job called `travis-lab`. Jobs are named after the corresponding repositories.
122+
123+
Click on `travis-lab`.
86124
87-
* Visit https://travis-ci.org/USERNAME.
88-
* You should see a job called `build_and_test_examples` - jobs are named after the corresponding repositories.
89-
* The job should be coloured green and with a tick mark meaning the build succeeded.
90-
* Click on this job.
125+
This will take you to a page, https://travis-ci.org/USERNAME/travis-lab, which shows information about the run of your Travis CI job.
91126
92-
For each repository it knows about, Travis CI provides a page summarising information about the jobs that have been run for that repository, including information on the current build and the build history:
127+
The job should be coloured green and with a check/tick icon which means that the job succeeded.
93128
94-
* The summary page has a URL of the form `https://travis-ci.org/USERNAME/JOB` e.g. https://travis-ci.org/trungdong/prov.
95-
* An icon shows the current status of the build. This has a URL of form `https://travis-ci.org/USERNAME/JOB.svg` e.g. https://travis-ci.org/trungdong/prov.svg. The status image is often embedded into other web pages, for example, README files in GitHub (for example, see https://github.com/trungdong/prov/blob/master/README.rst).
96-
* By default, information on the Current build is shown, including the log created by Travis CI as it ran this job.
97-
* The important part of our first `.travis.yml` file are the lines which ran our script:
129+
Information on your Git repository, including the commit ID and branch is also displayed i.e. the commit that triggered the job to run.
130+
131+
Under the **Current** tab you should see the Travis CI output from running your job. Most of the content is Travis CI-specific configuration, relating to how it configures its environment to build and test your code. Scroll to the bottom and you'll see what Travis CI does after it clones your repository:
98132
99133
```
100-
$ python hello.py
101-
Hello world from Travis CI
134+
$ git clone --depth=50 --branch=master https://github.com/USERNAME/travis-lab.git USERNAME/travis-lab
135+
$ source ~/virtualenv/python2.7/bin/activate
136+
$ python --version
137+
Python 2.7.13
138+
$ pip --version
139+
pip 9.0.1 from /home/travis/virtualenv/python2.7.13/lib/python2.7/site-packages (python 2.7)
140+
Could not locate requirements.txt. Override the install: key in your .travis.yml to install dependencies.
141+
```
102142
103-
The command "python hello.py" exited with 0.
143+
Certain lines are hidden, usually those concerned with setting up the environment for the job. Hidden lines are denoted by an arrow to the left of the line number. Click on these arrows to see the hidden lines.
144+
145+
At the very bottom, is the content of most interest, Travis CI's execution of our script:
104146
147+
```
148+
$ python hello.py
149+
Hello world!
150+
The command "python hello.py" exited with 0.
105151
Done. Your build exited with 0.
106152
```
107153
108-
* If any command were to exit with a non-zero result then Travis CI would consider the build to have failed, it would be coloured red and marked with a cross in the jobs summary page.
109-
* Certain lines are hidden, usually those concerned with setting up the environment for the job. Hidden lines are denoted by an arrow to the left of the line number. Click on these arrows to see the hidden lines.
154+
If a job completes with an exit code of 0 then the job is coloured green and with a check/tick icon, which means that the job succeeded.
155+
156+
If it completes with a non-zero exit code then the job is coloured red and with an X icon, which means that the job failed e.g. either the build failed or the tests failed.
157+
158+
Jobs still running are coloured yellow.
159+
160+
Add a `README.md` file with a build status icon
161+
-----------------------------------------------
162+
163+
Each job has an associated status icon e.g. https://travis-ci.org/USERNAME/travis-lab.svg?branch=master. This can be embedded into a `README.md` file in a Git repository, so the current status of the build is always shown when viewing the Git repository via GitHub's web interface.
164+
165+
Create a `README.md` file e.g.:
166+
167+
```
168+
# README for travis-lab
169+
170+
[![Build status](https://travis-ci.org/USERNAME/travis-lab.svg?master)](https://travis-ci.org/USERNAME)
171+
```
172+
173+
This is MarkDown syntax and specifies a hyperlink to https://travis-ci.org/USERNAME that is rendered as an SVG image, whose source is at https://travis-ci.org/USERNAME/travis-lab.svg?master.
174+
175+
Add `README.md` to your repository, commit it and push it.
176+
177+
As you have committed a change to your repository, this will trigger a new run of your job on Travis CI. On the page https://travis-ci.org/USERNAME/travis-lab, click **Build History**. You may see your build in progress.
178+
179+
Visit https://github.com/USERNAME/travis-lab and look for your icon in your `README.md` file. This feature exploits the fact that GitHub's web interface renders MarkDown-formatted files as HTML.
180+
181+
Explore a "real world" example
182+
------------------------------
183+
184+
https://github.com/softwaresaved/recipy is a fork of recipy, https://github.com/recipy/recipy, a framework for logging provenance about the environments under which Python scripts for research are run.
185+
186+
Look at its Travis CI icon at the bottom of its `README.md` file.
187+
188+
Look at its `.travis.yml` script at https://github.com/softwaresaved/recipy/blob/master/.travis.yml. This is a more complex script:
189+
190+
* It runs under both Python 2.7 and 3.4 (`python` section).
191+
* It does some Python version-specific configuration and installation and updates environment variables (`before_install` section).
192+
* It installs many Python packages needed to run recipy's tests (`install` section).
193+
* It runs the tests using py.test (`script` section). py.test is run in verbose mode (`-v`) and it is requested to show extra test information (`-r`) and to ouput to the terminal (`-s`).
194+
195+
Look at its Travis CI status information at https://travis-ci.org/softwaresaved/recipy, browse the output and see the download script. Note how specifying two language versions triggers two sub-jobs, one for Python 2.7 and one for Python 2.4. Note also how using the py.test flags ensures that information about individual test functions that are run is displayed within the script.
196+
197+
Change your code
198+
----------------
199+
200+
Make changes to your `hello.py` Python script then commit your changes and push them to GitHub. Watch how Travis CI regularly triggers new jobs.
201+
202+
Create a Python file with some functions, and an associated test file with some unit tests. Update the `script` section of `.travis.yml` to run the tests using py.test.
203+
204+
Explore other languages
205+
-----------------------
206+
207+
Fork and clone https://github.com/softwaresaved/build_and_test_examples.
208+
209+
Enable your fork on Travis CI.
210+
211+
Follow https://github.com/softwaresaved/build_and_test_examples/blob/master/travis/Languages.md to create a Travis CI job for a program in another language.

0 commit comments

Comments
 (0)