You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The first step is to fork this repository to your own GitHub account. This will allow you to make changes to the code without affecting the original repository.
3
-
4
-
Now head back over to your newly created repo. Everything in the `main` repo is not needed, so we do a few things:
5
-
6
-
**Change the default branch**
7
-
8
-
- Head to the Repo Settings
9
-
- There is a heading called "Default Branch"
10
-
- Click on the two arrow icon and change the default branch to `basic`
1
+
## Setting up Pods
11
2
12
-
**Delete the `main` branch**
3
+
`Pods` is our teaching platform for hands-on programming. It standardises the training workshop by giving everyone an identical Docker container and operating system, so we avoid the classic “this doesn’t work on my machine” problem.
4
+
That said, if you run into any issues, please feel free to raise your hand. The steps for setup will be outlined in the early stages of the workshop, but they are included below too:
13
5
14
-
- Head back to the Code tab
15
-
- Locate the branch dropdown and click on the thing to the right of it (it should say `4 branches`)
16
-
- Find the `main` branch and delete it
6
+
1. Head to [pods.acceleratescience.co.uk](https://pods.acceleratescience.co.uk)
7
+
2. Username = [CRSid], password will be provided in the workshop
17
8
18
-
**Rename the `basic` branch to `main`**
9
+
19
10
20
-
- In the same page for the `basic` branch, next to the trash can, click on the three dots
21
-
- Click on "Rename branch"
22
-
- Change the name to `main`
23
-
24
-
**Rename the repo**
25
-
26
-
- Head back over to the Settings tab
27
-
- At the top, you can change the name of the repo to whatever you want
28
-
- Rename it to `cancer-prediction-<your-crsid>`
29
-
30
-
Now open Codespaces on `main`:
31
-
32
-
33
-
34
-
You should now be in the browser version of VSCode.
35
-
36
-
This is the absolute most basic version of code being submitted to GitHub. But we can do better...
37
-
38
-
!!! note
39
-
40
-
Even though we are using Codespaces, the general packaging process will still work with regular VSCode on your desktop.
11
+
3. You should see a screen like above. Click VSCode/JupyterLab to open the IDE in your browser!
41
12
42
13
## Create a new branch
14
+
We are going to start by initialising a git repository in our directory
15
+
```bash
16
+
git init
17
+
```
18
+
We also need to create and set an `origin` for our git repository, that is a repository hosted on GitHub that we can push our changes to. The first step is to head to GitHub and create a new repository with the name:
19
+
```
20
+
cancer-prediction-<your-CRSId>
21
+
```
22
+
If we now return to our IDE and ask for the remote repository
23
+
```bash
24
+
git remote -v
25
+
```
26
+
nothing is returned. To set this to our newly created GitHub repository, simply run:
It is good practice to do development work on a new branch, but first we should set up a virtual environment and install any dependencies.
44
36
45
37
Set up the new virtual environment with,
@@ -74,15 +66,6 @@ and populate it with boiler plate text. If you have Copilot, it will do it for y
74
66
75
67
Once you update, all the additional files should vanish from the staging area. Once this is done, commit the changes, and sync the remote version with the local version.
76
68
77
-
Now create a new branch using the UI or using the git CLI.
78
-
```bash
79
-
git checkout -b dev
80
-
```
81
-
82
-
This will automatically create and move over to a new branch called `dev`. The environment and all the packages we installed should also be moved along with it.
83
-
84
-
In the source control tab, hit "Publish Branch".
85
-
86
69
When you see this symbol:
87
70
88
71
<br>
@@ -91,6 +74,15 @@ When you see this symbol:
91
74
92
75
it means that you should commit and push your changes to the repository. They indicate key checkpoints in the workshop.
93
76
77
+
In the source control tab, hit "Publish Branch".
78
+
79
+
Now create a new branch using the UI or using the git CLI.
80
+
```bash
81
+
git checkout -b dev
82
+
```
83
+
84
+
This will automatically create and move over to a new branch called `dev`. The environment and all the packages we installed should also be moved along with it. We will use this for developing new features in the codebase. Publish this branch using the same method as before.
85
+
94
86
## Further reading
95
87
<divclass="grid cards"markdown>
96
88
@@ -99,4 +91,51 @@ it means that you should commit and push your changes to the repository. They in
99
91
---
100
92
Information on Git/GitHub, Codespaces, VSCode
101
93
102
-
</div>
94
+
</div>
95
+
96
+
## Setting up Codespaces (*Legacy*)
97
+
98
+
!!! warning
99
+
100
+
We no longer use CodeSpaces in our workshops, and instead make use of our shiny new platform `Pods`. This is included here purely as a fallback option.
101
+
102
+
103
+
The first step is to fork this repository to your own GitHub account. This will allow you to make changes to the code without affecting the original repository.
104
+
105
+
Now head back over to your newly created repo. Everything in the `main` repo is not needed, so we do a few things:
106
+
107
+
**Change the default branch**
108
+
109
+
- Head to the Repo Settings
110
+
- There is a heading called "Default Branch"
111
+
- Click on the two arrow icon and change the default branch to `basic`
112
+
113
+
**Delete the `main` branch**
114
+
115
+
- Head back to the Code tab
116
+
- Locate the branch dropdown and click on the thing to the right of it (it should say `4 branches`)
117
+
- Find the `main` branch and delete it
118
+
119
+
**Rename the `basic` branch to `main`**
120
+
121
+
- In the same page for the `basic` branch, next to the trash can, click on the three dots
122
+
- Click on "Rename branch"
123
+
- Change the name to `main`
124
+
125
+
**Rename the repo**
126
+
127
+
- Head back over to the Settings tab
128
+
- At the top, you can change the name of the repo to whatever you want
129
+
- Rename it to `cancer-prediction-<your-crsid>`
130
+
131
+
Now open Codespaces on `main`:
132
+
133
+
134
+
135
+
You should now be in the browser version of VSCode.
136
+
137
+
This is the absolute most basic version of code being submitted to GitHub. But we can do better...
138
+
139
+
!!! note
140
+
141
+
Even though we are using Codespaces, the general packaging process will still work with regular VSCode on your desktop.
Copy file name to clipboardExpand all lines: docs/4_Testing.md
+7-1Lines changed: 7 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -69,6 +69,9 @@ if __name__ == '__main__':
69
69
```
70
70
</details>
71
71
72
+
!!! warning
73
+
Remember to update your import to be from package `cancer_prediction_<your-CRSId>`, as opposed to the generic `cancer_prediction` we have here.
74
+
72
75
## Running tests
73
76
### In the VSCode UI
74
77
To run the tests, we click on the "Testing" tab on the sidebar, and then "Configure Python Tests". The order of clicks is as follows:
@@ -95,13 +98,16 @@ OK
95
98
96
99
You can try changing part of the test code to force them to fail, and check the output. Now that the tests have run succesfully, it's time to commit and push the changes.
97
100
101
+
!!! note
102
+
If the tests fail due to an import error of your `cancer_prediction_<your-CRSId>.cancer_model` file, try running `uv sync` then re-running the test command.
103
+
98
104
<br>
99
105
![Dark Souls Bonfire](../imgs/dark-souls-bonfire.gif"Commit your changes and rest, weary traveller"){ width="50" .center }
100
106
<br>
101
107
102
108
!!! note
103
109
104
-
For some reason Codespaces is not discovering the tests. Just run them in the terminal for now. But VSCode run locally should work fine.
110
+
If for some reason the VSCode UI is not discovering the tests, try refreshing the VSCode window. If you're still having trouble, just run them in the terminal for now.
echo "Error: Tag must be created on master branch"
30
30
exit 1
31
31
fi
32
32
@@ -79,15 +79,15 @@ In addition, since we are using some tools, we should let everyone know! So we c
79
79
which should display as the following:
80
80
81
81
82
-
Before we push these changes, we will configure GitHub Pages so that our documentation will create a url for people to visit. Go to the repo Settings -> Pages, and pick a branch to deploy from, in this case 'gh-pages'. So now when we push these changes and merge them to `main`, the documentation will be published and the badges will be displayed on the README!
82
+
Before we push these changes, we will configure GitHub Pages so that our documentation will create a url for people to visit. Go to the repo Settings -> Pages, and pick a branch to deploy from, in this case 'gh-pages'. So now when we push these changes and merge them to `master`, the documentation will be published and the badges will be displayed on the README!
83
83
84
84
!!! tip
85
85
86
86
You can in principle delete the 'dev' branch whenever you build your package. But if for whatever reason you decide to keep it, be sure to do the following
87
87
```bash
88
88
git checkout dev
89
89
git fetch origin
90
-
git merge origin/main
90
+
git merge origin/master
91
91
```
92
92
93
-
This will ensure that the 'dev' branch is up to date with the 'main' branch. Do this BEFORE you make any changes to the 'dev' branch, otherwise you have to merge the changes manually.
93
+
This will ensure that the 'dev' branch is up to date with the 'master' branch. Do this BEFORE you make any changes to the 'dev' branch, otherwise you have to merge the changes manually.
Copy file name to clipboardExpand all lines: docs/CICD/publishing.md
+24-24Lines changed: 24 additions & 24 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,13 +1,13 @@
1
1
Finally, we will automate the publishing of our package to PyPI and the release of the documentation.
2
2
3
3
## Pull requests
4
-
When do we want to publish our package and documentation? We don't want to publish when we push changes to `dev`, because there might be some experimental changes that we've made that could break our package. Instead we should restrict publishing only when there are pushes made to `main`. However, we don't just want to push changes to main directly.
4
+
When do we want to publish our package and documentation? We don't want to publish when we push changes to `dev`, because there might be some experimental changes that we've made that could break our package. Instead we should restrict publishing only when there are pushes made to `master`. However, we don't just want to push changes to `master` directly.
5
5
6
6
Head over to the repo and submit a pull request. It should look something like this:
7
7
8
8
9
9
10
-
You should make sure that the `compare` branch is `dev` and the `base` branch is `main`.
10
+
You should make sure that the `compare` branch is `dev` and the `base` branch is `master`.
11
11
12
12
!!! warning
13
13
@@ -19,11 +19,11 @@ There are no conflicts so I can merge these branches without any issues. If ther
19
19
20
20
Notice that there are some checks happening. We want to avoid hitting that Merge pull request button as long as those checks have not passed. We can actually enforce this, but for now we can just manually make sure that the checks have passed.
21
21
22
-
Now head over to the Code tab and click on the branches. Delete the `dev` branch. We don't need it anymore. When you head back into codespaces, checkout the `main` branch and pull any changes by running these commands:
22
+
Now head over to the Code tab and click on the branches. Delete the `dev` branch. We don't need it anymore. When you head back into codespaces, checkout the `master` branch and pull any changes by running these commands:
23
23
24
24
```bash
25
-
git checkout main
26
-
git pull origin main
25
+
git checkout master
26
+
git pull origin master
27
27
```
28
28
29
29
We will create a new branch for adding our publishing workflow:
echo "Error: Tag must be created on master branch"
126
126
exit 1
127
127
fi
128
128
```
129
129
130
-
This does exactly what you think it does! It checks if the tag is on the `main` branch. If it is not, it will throw an error and the workflow will stop.
130
+
This does exactly what you think it does! It checks if the tag is on the `master` branch. If it is not, it will throw an error and the workflow will stop.
131
131
132
132
The next interesting part is
133
133
```yaml
@@ -173,37 +173,37 @@ The final section builds the package and releases it to GitHub and to Test PyPI.
173
173
There are two main schools of development on git: Git Flow, and trunk-based development.
174
174
175
175
#### Git Flow
176
-
In Git Flow you have two long-running branches `main` and `dev`. Workers will usually branch off of `dev`, make some feature change, then submit a PR. The PR is accepted (or not) and merged to `dev`. When we are happy, we create a release branch, do some tests, and then merge this branch into `main` and tag it with a release. This style is very suitable to open-source projects, where you can't trust random people trying to make changes to your code.
176
+
In Git Flow you have two long-running branches `master` and `dev`. Workers will usually branch off of `dev`, make some feature change, then submit a PR. The PR is accepted (or not) and merged to `dev`. When we are happy, we create a release branch, do some tests, and then merge this branch into `master` and tag it with a release. This style is very suitable to open-source projects, where you can't trust random people trying to make changes to your code.
177
177
178
178
#### Trunk
179
-
In Trunk-based development, you work from a single `main` branch. Usually you work from it directly, and make short changes, and make small `feature` branches. Development is fast and continuous. When you are happy, you create a separate `release` branch which is pushed to PyPI (or wherever). This is a great option for small, speedy projects, and is the approach that we use here.
179
+
In Trunk-based development, you work from a single `master` branch. Usually you work from it directly, and make short changes, and make small `feature` branches. Development is fast and continuous. When you are happy, you create a separate `release` branch which is pushed to PyPI (or wherever). This is a great option for small, speedy projects, and is the approach that we use here.
180
180
181
181
!!! tip
182
182
183
-
If you find yourself working on a feature, and somebody has made changes to the main branch, you can update yours by running
183
+
If you find yourself working on a feature, and somebody has made changes to the master branch, you can update yours by running
184
184
```bash
185
185
git checkout dev
186
-
git merge origin/main
186
+
git merge origin/master
187
187
```
188
-
This will update your `dev` branch with the changes from `main`.
188
+
This will update your `dev` branch with the changes from `master`.
189
189
190
190
## Actually publishing
191
-
Submit a PR, and merge the changes into main. If we've done everything correct, the workflow should not run.
191
+
Submit a PR, and merge the changes into master. If we've done everything correct, the workflow should not run.
192
192
193
-
Back in Codespaces, checkout the `main` branch and pull any changes:
193
+
Back in Codespaces, checkout the `master` branch and pull any changes:
194
194
195
195
```bash
196
-
git checkout main
197
-
git pull origin main
196
+
git checkout master
197
+
git pull origin master
198
198
```
199
199
200
-
Bump the version (because if we try to push this versoin again, it will fail), and push the changes:
200
+
Bump the version (because if we try to push this version again, it will fail), and push the changes:
201
201
202
202
```bash
203
203
uv version patch
204
204
git add pyproject.toml
205
205
git commit -m "Bump version to $(uv version --short)"
0 commit comments