Skip to content

Commit 7d36268

Browse files
lwasserlwasser
committed
add: detailed codespaces instructions
1 parent 77591ee commit 7d36268

File tree

1 file changed

+92
-51
lines changed

1 file changed

+92
-51
lines changed

‎_posts/events/2025-06-24-scipy25-create-python-package.md‎

Lines changed: 92 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ Before the workshop, please create and log into the following accounts:
5050
> <i class="fa-solid fa-lock"></i> **Important:** To follow along when we publish to Test PyPI, you must enable **two-factor authentication (2FA)** on your Test PyPI account. We strongly recommend doing this **before** the workshop!
5151
{: .notice .notice-important}
5252

53-
### 2a. Setup for working locally on your laptop
53+
## 2a. Setup for working locally on your laptop
5454

5555
We recommend using GitHub Codespaces (see next section) to avoid issues with environment setup. However, if you prefer to work locally, please ensure your environment is set up and ready before the workshop.
5656

@@ -75,94 +75,135 @@ We strongly suggest that you use our curated [GitHub Codespace](https://codespac
7575

7676
### Before the workshop do the following
7777

78-
1. [Fork our workshop repository](https://github.com/pyOpenSci/pyopensci-scipy25-create-python-package) and
79-
2. Launch the codespace from your fork, BEFORE the workshop begins. This ensures that it’s ready for you to use during the workshop.
80-
81-
82-
## How to open a codespace
78+
* Go to GitHub.com and [Fork the workshop repository](https://github.com/pyOpenSci/pyopensci-scipy25-create-python-package)
8379

80+
<figure>
81+
<picture>
82+
<img src="{{ site.baseurl }}/images/github/codespaces/scipy-fork-repo.gif" alt=".">
83+
</picture>
84+
</figure>
8485

85-
### What is a codespace
86+
* **Create a branch** in your fork to work on during the workshop.
87+
* **Launch the repository codespace from your fork, BEFORE the workshop begins**. The initial spin-up for a codespace can take up to 15 minutes or longer. Once it's been created, it will be quicker to relaunch.
8688

87-
GitHub Codespaces are a cloud-based development environment integrated into GitHub. Codespaces provide fully configured, container-based environments that you can use to modify files in a GitHub repository. Codespaces are customizable, allowing users to define their environment using `.devcontainer` configuration files. The codespaces set up for this workshop run Visual Studio Code by default; you can set them up however to use the IDE (Integrated Development Environment) of your choice. Codespaces allow you to work on activities during a workshop in the cloud without needing to setup a local environment.
89+
<figure>
90+
<picture>
91+
<img src="{{ site.baseurl }}/images/github/codespaces/scipy-open-codespace.gif" alt=".">
92+
</picture>
93+
</figure>
8894

89-
You can learn more about GitHub Codespaces [here](https://docs.github.com/en/codespaces/overview).
9095

91-
Important: GitHub Codespaces are free to run on a Free GitHub account for up to 60 hours a month. Given you have limited hours, be sure to shut down your CodeSpace after the workshop ends to ensure that you don’t run out of credits.
96+
## <i class="fa-solid fa-cloud"></i> About GitHub Codespaces: Working in the cloud
9297

9398

94-
### View & manage open codespaces
99+
## What is a codespace
95100

96-
You can view open Codespaces associated with your account here:
101+
GitHub Codespaces are cloud-based development environments that let you
102+
code directly in your browser—no local setup needed. They provide fully
103+
configured, container-based environments connected to your GitHub
104+
repository.
97105

106+
You can customize Codespaces with `.devcontainer` files to match your
107+
development setup. The Codespace for this workshop opens in Visual Studio
108+
Code by default, but you can configure it to use any IDE you prefer.
98109

99-
* [https://github.com/codespaces](https://github.com/codespaces)
110+
Learn more in the [GitHub Codespaces docs](https://docs.github.com/en/codespaces/overview).
100111

101-
When you delete a running codespace, you are deleting an active session. However, the codespace configuration is always available for you to use and reopen a new codespace.
112+
Codespaces are free for up to 60 hours/month on GitHub’s free plan. Be sure
113+
to shut yours down after the workshop to conserve your allocated time.
114+
{: .notice}
102115

103116

104117
### How to open a codespace
105118

106-
Codespaces are associated with each GitHub user’s account (they are not associated with pyOpenSci / our GitHub organization. If you see the screenshot below, you haven’t launched a codespace from this repository before. In this case, click on `Create Codespace on main`. This will create a codespace for you using the configuration file provided in the main branch of our organization.
107-
108-
109-
110-
* You can use the CodeSpaces that pyOpenSci has already setup for you in our workshop repository..
111-
* [ff-2024-create-python-package Codespace](https://codespaces.new/pyOpenSci/ff-2024-create-python-package?quickstart=1) **UPDATE THIS**
112-
* **https://github.com/pyOpenSci/scipy-2025-create-python-package**
113-
* If you have never used a codespace before, you might see the image below that says “No Codespaces”. That just means that you need to open a new CodeSpace. To do that, click on the green button that says: **Create codespace on main**.
114-
* This will create a codespace running on the main branch of your repository. If you are in an actual development workflow, you would likely want to create a codespace working on a different branch so you can submit a pull request using best practices (not from main branch).
115-
119+
To open a Codespace,
120+
121+
* Go to your forked SciPy 2025 workshop repository on GitHub,
122+
* Switch to a branch that you want to work on during the workshop,
123+
* Click the code drop-down button (where you'd find a link to clone a repo)
124+
* Click on the Codespaces tab in the drop-down.
125+
126+
Within the Codespaces tab you will see a button: <kbd style="background-color: #2da44e; color: white; padding: 2px 6px; border-radius: 4px;">
127+
Create codespace on main
128+
</kbd>. This button launches a Codespace from the currently active branch. It will default to the
129+
`main` branch if you haven't changed your branch yet.
130+
131+
<figure style="width: 55%; margin: 0 auto;">
132+
<picture>
133+
<source srcset="{{ site.baseurl }}/images/github/codespaces/create-github-codespace-main.webp"
134+
type="image/webp">
135+
<img src="{{ site.baseurl }}/images/github/codespaces/create-github-codespace-main.png"
136+
alt="Create codespace on main button">
137+
</picture>
138+
</figure>
116139

140+
> <i class="fa-solid fa-circle-info"></i> To follow GitHub best practices, always create a new branch before making
141+
> changes. Avoid working directly on the `main` branch.
117142
143+
If you switch branches in GitHub, Codespaces will launch from the
144+
selected, active branch.
118145

119146
<figure>
120-
<picture>
121-
<source srcset="{{ site.baseurl }}/images/github/codespaces/create-github-codespace-main.webp" type="image/webp">
122-
<img src="{{ site.baseurl }}/images/github/codespaces/create-github-codespace-main.png" alt=".">
123-
</picture>
147+
<picture>
148+
<img src="{{ site.baseurl }}/images/github/codespaces/scipy-open-codespace.gif"
149+
alt="GIF showing Codespace launch process">
150+
</picture>
124151
</figure>
125152

126-
<p id="gdcalert1" ><span style="color: red; font-weight: bold">>>>>> gd2md-html alert: inline image link here (to images/image1.png). Store image on your image server and adjust path/filename/extension if necessary. </span><br>(<a href="#">Back to top</a>)(<a href="#gdcalert2">Next alert</a>)<br><span style="color: red; font-weight: bold">>>>>> </span></p>
127-
128-
129-
![alt_text](images/image1.png "image_tooltip")
130-
131-
* If you have already opened and used a Codespace in your repository, GitHub will find it and ask if you want to resume using the existing Codespace in your account.
132-
* Select Resume This Codespace. You don’t need to create a new codespace!!
133-
134-
135-
136-
<p id="gdcalert2" ><span style="color: red; font-weight: bold">>>>>> gd2md-html alert: inline image link here (to images/image2.png). Store image on your image server and adjust path/filename/extension if necessary. </span><br>(<a href="#">Back to top</a>)(<a href="#gdcalert3">Next alert</a>)<br><span style="color: red; font-weight: bold">>>>>> </span></p>
137153

154+
> Codespaces are associated with your **personal GitHub account**, even if
155+
you open one from the pyOpenSci repository. The usage counts toward your
156+
own GitHub credits.
157+
{: .notice }
138158

139-
![alt_text](images/image2.png "image_tooltip")
140-
141-
* How to relaunch a codespace
142-
* How to commit changes to your fork after making them in a codespace.
143159

144-
<p id="gdcalert3" ><span style="color: red; font-weight: bold">>>>>> gd2md-html alert: inline image link here (to images/image3.png). Store image on your image server and adjust path/filename/extension if necessary. </span><br>(<a href="#">Back to top</a>)(<a href="#gdcalert4">Next alert</a>)<br><span style="color: red; font-weight: bold">>>>>> </span></p>
160+
### View & manage open codespaces
145161

162+
Once you've opened a Codespace, you can return to it later without needing
163+
to start from scratch. GitHub will reuse the environment, making it launch
164+
significantly faster the second time.
146165

147-
![alt_text](images/image3.png "image_tooltip")
166+
If possible, resume the **same Codespace** you started in, rather than
167+
creating a new one in your fork.
148168

169+
<figure>
170+
<picture>
171+
<img src="{{ site.baseurl }}/images/github/codespaces/scipy-open-codespace.gif"
172+
alt="Animated gif of GitHub Codespace launch names">
173+
</picture>
174+
</figure>
149175

150-
<p id="gdcalert4" ><span style="color: red; font-weight: bold">>>>>> gd2md-html alert: inline image link here (to images/image4.png). Store image on your image server and adjust path/filename/extension if necessary. </span><br>(<a href="#">Back to top</a>)(<a href="#gdcalert5">Next alert</a>)<br><span style="color: red; font-weight: bold">>>>>> </span></p>
176+
<i class="fa-solid fa-link"></i>
177+
[View all active Codespaces associated with your account](https://github.com/codespaces)
151178

179+
{: .notice}
180+
> <i class="fa-solid fa-circle-info"></i> When you delete a Codespace, you're
181+
> ending the session, but the configuration remains available so you can
182+
> launch a new one anytime.
183+
> [Learn more in the GitHub docs](https://docs.github.com/en/codespaces/developing-in-a-codespace/stopping-and-starting-a-codespace)
152184
153-
![alt_text](images/image4.png "image_tooltip")
154185

155-
<p id="gdcalert5" ><span style="color: red; font-weight: bold">>>>>> gd2md-html alert: inline image link here (to images/image5.png). Store image on your image server and adjust path/filename/extension if necessary. </span><br>(<a href="#">Back to top</a>)(<a href="#gdcalert6">Next alert</a>)<br><span style="color: red; font-weight: bold">>>>>> </span></p>
186+
As you can see in the animated gif below, GitHub codespaces always have fun names.
156187

157188

158-
![alt_text](images/image5.png "image_tooltip")
189+
### How to relaunch a codespace
159190

191+
To relaunch a Codespace:
160192

161-
<p id="gdcalert6" ><span style="color: red; font-weight: bold">>>>>> gd2md-html alert: inline image link here (to images/image6.png). Store image on your image server and adjust path/filename/extension if necessary. </span><br>(<a href="#">Back to top</a>)(<a href="#gdcalert7">Next alert</a>)<br><span style="color: red; font-weight: bold">>>>>> </span></p>
193+
1. Go to your fork of the workshop repository.
194+
2. Click the **Code** dropdown (same as when you first created the Codespace).
195+
3. Select the **Codespaces** tab to view existing environments.
196+
4. If GitHub finds a matching Codespace, it will prompt you to:
162197

198+
<i class="fa-solid fa-play"></i> **Resume this Codespace**
163199

164-
![alt_text](images/image6.png "image_tooltip")
165200

201+
<figure>
202+
<picture>
203+
<img src="{{ site.baseurl }}/images/github/codespaces/reopen-codespace.gif"
204+
alt="GIF showing how to reopen a GitHub Codespace">
205+
</picture>
206+
</figure>
166207

167208
<div class="notice" markdown="1">
168209

0 commit comments

Comments
 (0)