Notebook Tutorial and Assignment Directions
GIS714-assignments Intro to Git
Vaclav Petras
To add a new activity to this project, you need to fork this repository, create a branch, create a pull request, and, of course, develop your new activity. The following sections go over the specific steps. A later section discusses how to modify an action later on using another pull request.
To be able to create pull request (PR), you will need to set up a fork and a local repository on your computer (to make changes and to test code locally):
- Fork this repository on GitHub.
- In the web interface, there is a Fork button.
- Clone your fork on your computer.
- For example, in the command line, use the
git clone
command:git clone {url-of-the-repo}
- For example, in the command line, use the
- Create a new Python script according to the provided example.
- There is an example called
simple_example.py
in theactivities
directory which gives information about the specific conventions. - Use a unique filename, for example use your name (e.g.,
petras.py
). - Jupyter can be used to create the file, alternatively, you can use the Simple Python Editor in GRASS GIS.
- There is an example called
- Develop a new analysis and write it as a function in the file.
- Test your analysis locally on your computer or in Binder.
- Use the NC SPM sample location for GRASS GIS.
Place the file in the activities
directory. If the file is not in the
activities
directory or if it does not have the
.py
extension, it will be ignored by the automated system.
- Create a new JSON configuration file according to the provided example.
- There is an example called
simple_example.json
in theactivities
directory which provides an example of a minimal activity configuration. - Again, use a unique filename, for example use your name (e.g.,
petras.json
). - Use Jupyter to create the file or your favorite text editor.
- There is an example called
- Set value for the
analyses
key to the filename of your Python script. - Modify
layers
to fit your needs. - Change
title
,author
, andinstructions
for the task to best describe your work.
Note that the name of the JSON configuration file should differ from the name of the
Python file only by extension (.json
versus .py
).
Once you have your new files ready, you can do all the Git related steps (you could do them as your are working, too).
We will use Git in command line here and for creating the PR with GitHub web interface, but you can use any Git desktop tool including GitHub Desktop. You can also do all through the GitHub web interface. (On the other hand, if you want to do everything in command line, you can add GitHub CLI to the mix.) Notably, you can't do this from the online Binder environment (Binder recommends not to enter any credentials in their environment).
Create a new branch for your changes and switch to it.
Here, we will call the new branch add-awesome-activity
.
In command line, do:
git switch -c add-awesome-activity
Add Python script with your Python file and your JSON file to the repository as new files:
git add activities/awesome-activity.py
git add activities/awesome-activity.json
Record the changes:
git commit -m "Add awesome activity"
Publish the changes into your fork
(origin
is how Git refers to the remote repository you cloned from,
add-awesome-activity
is the name you have picked earlier for your branch):
git push origin add-awesome-activity
This will give your URL to create pull request on GitHub or simply go to GitHub and it will suggest you to open a PR.
After you open a PR, you will see various checks running at the bottom of the PR page. The checks are testing correctness of the code from several perspectives including syntax, indentation, and several checks specific to this repository.
If you see Some checks were not successful, review the output to see the details of what is wrong. For example, if you see the Super-Linter check failing, click Details and then scroll up to see the actual error which, in this case, can be recognized by the word ERROR.
Result of one of these checks needs to be examined manually. Its name is Render activities and it is running the Python file and combining it with the associated JSON file into an HTML page. So, even when the check says Successful, click on Details next to its name, then Summary on the left, and then in Artifacts at the bottom, download the activities-as-html artifact, unzip it, find an HTML file named like your JSON file and open it in your web browser. You should see the title you provided and the rendering of your results according to what you specified in the JSON file. This provides you with the idea of what will eventually happen in Tangible Landscape.
You can run any of these checks locally as well, but it is more practical to just start using some of the basic tools used in the background, namely Black, Flake8, and Pylint. For the rest, you can just rely on the checks associated with the PR.
If some of the checks are failing for you or the activities-as-html artifact
does not look as you intended, make required changes locally, do git add
, then commit and push
as you did before. This will update the PR and trigger the checks.
Repeat as needed.
When your PR is merged, the main, original repository is updated.
Here, we will refer to this repository as the upstream repository.
What was updated in the upstream repository was the main
branch
which will be important in a moment.
Because the changes from the PR are now in the main
branch
of the upstream repository, modifying your Tangible Landscape activity
now requires that you update your fork first.
To update your fork using a combination of the GitHub web interface and command line, go to your fork and switch to the main branch using a combo box on the left. Then push the Fetch and merge button on the right (confirm the action if needed). Then locally in command line, you can do:
git switch main
git pull
Your local main branch should now be the same as the one in the upstream repository and you should be ready to create a new branch for futher updates.
Alternatively, to update your fork using only command line, first, you need to add the upstream repository as another remote repository to the clone on your local machine.
So, add the upstream repository as another remote repository called upstream
.
In command line, using:
git remote add upstream https://github.com/ncsu-geoforall-lab/gis714-2023-tangible-landscape
Second, switch to the main
branch of your repository
(the main
branch should have no changes in it since you used a separate branch
to make the changes for your first PR):
git switch main
Third, update the main
branch of your local repository to match
the main
branch from the upstream repository.
This can be done with the two following commands:
git fetch upstream
git rebase upstream/main
Now when your local main
branch is up to date with the main
branch
of the upstream repository,
you can just follow the instructions above for creating a new activity,
in short, you need to:
- create a new branch (you can also do it after you make the changes),
- make changes,
- add changes to Git,
- make commits,
- publish (push) the changes online, and
- create a pull request.