diff --git a/images/github/github-fork-repo.gif b/images/github/github-fork-repo.gif new file mode 100644 index 0000000..17e2af7 Binary files /dev/null and b/images/github/github-fork-repo.gif differ diff --git a/publish-share-code/activity-1-share-code.md b/publish-share-code/activity-1-share-code.md index 1b6624c..68b1bdb 100644 --- a/publish-share-code/activity-1-share-code.md +++ b/publish-share-code/activity-1-share-code.md @@ -12,31 +12,70 @@ kernelspec: --- # Share Your Code Activities +s +:::{note} -## Activity 1 - install a package from GitHub +If you are comfortable using Git and GitHub and have a Python package already on GitHub, you can use that package for this activity. Otherwise, we suggest that you fork the [pyospackage repository](https://github.com/pyOpenSci/pyosPackage) for this activity! -:::{note} +::: -If you are comfortable using Git and GitHub and have a Python package in mind, check the package's repo on GitHub or GitLab to ensure that the package structure and source code are correct. +## Activity 1: Install a package from GitHub -If you are working on this during a pyOpenSci workshop, you can use the package you created in our workshop! +1. Create & activate a Python environment that you wish to use for this activity. -If not, you can start with the [pyospackage repository](https://github.com/pyOpenSci/pyosPackage). -::: +`python -m venv pyosworkshop` + +If you are working on a Mac, A Linux machine or in the GitHub codespace that we setup, you can activate the environment using: + +`source pyosworkshop/bin/activate` + +If you are using Windows, use: + +`.\pyosworkshop\Scripts\activate` + + +2. After activating the environment, [install the pyosPackage package](install-github) in that repository using `pip`. +```bash +pip install git+https://github.com/pyopensci/pyospackage.git +``` + ++++ + +## Activity 2: Fork the repo and install a package from your fork + +Above, you installed a package from a pyOpenSci-owned GitHub repo. +Now, you will do the same thing, but instead, you will install your package from a fork that you own of the pro package. + +Because you own this fork, you can make any changes you wish to the code. 1. Fork the [pyospackage repository](https://github.com/pyOpenSci/pyosPackage) on GitHub. -2. This repository has a GitHub Codespace setup with VS Code. Optional: after you fork the repository, you can use a GitHub codespace to modify the source code and package name (if you wish). -3. Install the package in that repository from your fork. + + +:::{figure} ../images/github/github-fork-repo.gif +--- +alt: "alt here." +name: fork-github-repo +width: 700px +--- + +To begin, fork the pyospackage GitHub repository. +::: + +Now, you can install the same package into the same environment using the command below. IMPORTANT: be sure to modify the URL of the repo to represent your FORK. + +```bash +pip install git+https://github.com/YOUR-GITHUB-USERNAME-HERE/pyospackage.git +``` +++ -## Activity 2: Connect your Python package repo to Zenodo +## Activity 3: Connect your Python package repo to Zenodo -In this activity, you will connect the GitHub repository containing a Python package to [Zenodo to create a DOI (Digital Object Identifier)](zenodo) for your code. This will allow others to cite your work and give credit to contributors. +In this activity, you will connect the GitHub repository that you just forked containing a Python package to [Zenodo to create a DOI (Digital Object Identifier)](zenodo) for your code. This will allow others to cite your work and give credit to contributors. -If you completed **Activity 1** above, you should already have a GitHub repository set up. Now, we’ll take it a step further by setting up a citation for your project using Zenodo. +If you completed **Activity 2** above, you should already have a GitHub repository set up. Now, we’ll take it a step further by setting up a citation for your project using Zenodo. ### Steps to Connect Your Repository to Zenodo @@ -47,7 +86,7 @@ If you completed **Activity 1** above, you should already have a GitHub reposito 2. **Create a Release** - In your GitHub repository, navigate to the **Releases** section. Click on **Draft a new release**. - - Assign an available version number to the release (e.g., `v1.0.0`) and provide a title and description. + - Assign the release an available version number (e.g., `v1.0.0`) and provide a title and description. - Click on **Publish release**. This action will trigger Zenodo to generate a DOI for your code. 3. **Get the DOI Badge and Add It to Your README File** @@ -55,7 +94,33 @@ If you completed **Activity 1** above, you should already have a GitHub reposito IMPORTANT: When completing this step, be sure to grab the Zenodo badge for "all versions" rather than the most recent version. +Zenodo will provide a badge code that you can copy. Go back to your GitHub repository, open your `README.md` file, and paste the DOI badge code at the top or in a dedicated section like **Citing this Code**. + ++++ + +## Activity 4: Rename your package and create a new release + +In this activity, you will further develop the Python package you have worked on (or the package you forked above). + +1. Rename the package by updating both the `pyproject.toml` file and the package directory found within the `src/package-name` + +2. If you wish, add a new function to the package using the codespace provided in the repository. Commit your changes before moving on to the next step. + +3. Create a new release of the package on GitHub. + +4. Check out the Zenodo landing page for your package. Do you see the new release there? + +:::{note} +Note: it may take 5-10 minutes for the new release to process. +::: + ++++ + +## Activity 5: Publish your package on test PyPI + +For this activity, you will practice publishing your package to test-pypi. We will follow the [guidance provided in this lesson](https://www.pyopensci.org/python-package-guide/tutorials/publish-pypi.html). - - Zenodo will provide a badge code that you can copy. Go back to your GitHub repository, open your `README.md` file, and paste the DOI badge code at the top or in a dedicated section like **Citing this Code**. +To be successful in this activity, you will need to have -By completing this activity, you’ve taken an important step in making your code citable and accessible to others. Properly citing code encourages transparency and reproducibility, helping others build upon your work with confidence. +1. A [test-PyPI account setup](https://test.pypi.org/account/register/) +2. A unique package name. Don't try to use pyospackage. We suggest renaming your package to something unique like `pyospackage-yourGitHubUserName` diff --git a/publish-share-code/intro.md b/publish-share-code/intro.md index 3ee26fc..f165ed9 100644 --- a/publish-share-code/intro.md +++ b/publish-share-code/intro.md @@ -32,7 +32,7 @@ Publish your Code :maxdepth: 2 -Share your Code +Activities: Share your Code ::: diff --git a/publish-share-code/share-code.md b/publish-share-code/share-code.md index f2978f2..096623b 100644 --- a/publish-share-code/share-code.md +++ b/publish-share-code/share-code.md @@ -47,6 +47,7 @@ Version control systems (like Git) are fundamental to collaborative coding. Thes Using hosting platforms like GitHub and GitLab helps you manage your code and provides a welcoming environment for contributors to get involved and contribute back to your project. +(install-github)= ## Install software directly from GitHub Once you have turned your code into a Python package and shared it on GitHub, multiple ways exist to make it directly installable. One simple approach is to install your package directly from GitHub using `pip`.