This the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Contributing

How to contribute to BioPAL

We want your help! BioPAL is an open source project that is supported by a community who welcomes your enthusiasm and expertise! We will gratefully accept any contribution you might make to the project. Large or small, any contribution makes a big difference; and if you have never contributed to an open source project before, we hope you will start with BioPAL!

It is important to us to create a open and inclusive community that values it’s diversity. In oder to achieve this, we all abide by our Code of Conduct. Please make sure to get to know this Code of Conduct when interacting within the community.

The main goal of BioPAL is to advance the BIOMASS core processing algorithms for Forest Height estimation, Forest Disturbance assessment, or Above Ground Biomass estimation. We are always on the lookout for advances in estimating these metrics. If you have a novel integration of such an algorithm feel free to create an issue, a pull request or reach out to us via the slack channel.

However, open-source is about much more than contributing with new algorithms, we need your help in many ways:

  • Submit a bug report or feature request on GitHub issues.
  • Contribute an Jupyter notebook to our examples gallery.
  • Assist us with user testing.
  • Add to the documentation or help with our website, biopal.org
  • Write unit or integration tests for our project.
  • Answer questions on our GitHub issues, the MAAP forums, Slack channels, Stack Overflow, and Twitter.
  • Translate our documentation into another language.
  • Write a blog post, tweet, or share our project with others.
  • Teach someone how to use BioPAL

Starting to Contribute

Whether you are a first time contributor to open-source or a seasoned open-source veteran interested in joining the BioPAL community, this section will guide you in:

1 - Code of Conduct

Conde of Conduct for interacting wihtin the BioPAL community

The BioPAL Code of Conduct can be found on the BioPAL/governance GitHub repository. For convenience it has been replicated here. In case of difference, the BioPAL/governance version is the canonical one.

1.1 - Code of Conduct

BioPAL Code of Conduct

BioPAL is an engaged and respectful community made up of people from all over the world. Your involvement helps us to further our mission and to create an open platform that serves a broad range of communities, from research and education, to industry and beyond.

Naturally, this implies diversity of ideas and perspectives on often complex problems. Disagreement and healthy discussion of conflicting viewpoints is welcome: the best solutions to hard problems rarely come from a single angle. But disagreement is not an excuse for aggression: humans tend to take disagreement personally and easily drift into behavior that ultimately degrades a community. This is particularly acute with online communication across language and cultural gaps, where many cues of human behavior are unavailable. We are outlining here a set of principles and processes to support a healthy community in the face of these challenges.

Fundamentally, we are committed to fostering a productive, harassment-free environment for everyone. Rather than considering this code an exhaustive list of things that you cannot do, take it in the spirit it is intended - a guide to make it easier to enrich all of us and the communities in which we participate.

Importantly: as a member of our community, you are also a steward of these values. Not all problems need to be resolved via formal processes, and often a quick, friendly but clear word on an online forum or in person can help resolve a misunderstanding and de-escalate.

However, sometimes these informal processes may be inadequate: they fail to work, there is urgency or risk to someone, nobody is intervening publicly and you don’t feel comfortable speaking in public, etc. For these or other reasons, structured follow-up may be necessary and here we provide the means for that: we welcome reports by emailing biopal@esa.int. For more details please see our Reporting Guidelines.

This code applies equally to founders, developers, mentors and new community members, in all spaces managed by BioPAL. This includes our GitHub organizations, our chat rooms, in-person events and any other forums created by the project team. In addition, violations of this code outside these spaces may affect a person’s ability to participate within them.

Expected behavior

By embracing the following principles, guidelines and actions to follow or avoid, you will help us make BioPAL a welcoming and productive community. Feel free to contact the Code of Conduct Committee at biopal@esa.int with any questions.

  1. Be friendly and patient.

  2. Be welcoming. We strive to be a community that welcomes and supports people of all backgrounds and identities. This includes, but is not limited to, members of any race, ethnicity, culture, national origin, color, immigration status, social and economic class, educational level, sex, sexual orientation, gender identity and expression, age, physical appearance, family status, technological or professional choices, academic discipline, religion, mental ability, and physical ability.

  3. Be considerate. Your work will be used by other people, and you in turn will depend on the work of others. Any decision you take will affect users and colleagues, and you should take those consequences into account when making decisions. Remember that we’re a world-wide community. You may be communicating with someone with a different primary language or cultural background.

  4. Be respectful. Not all of us will agree all the time, but disagreement is no excuse for poor behavior or poor manners. We might all experience some frustration now and then, but we cannot allow that frustration to turn into a personal attack. It is important to remember that a community where people feel uncomfortable or threatened is not a productive one.

  5. Be careful in the words that you choose. Be kind to others. Do not insult or put down other community members. Harassment and other exclusionary behavior are not acceptable. This includes, but is not limited to:

    • Violent threats or violent language directed against another person
    • Discriminatory jokes and language
    • Posting sexually explicit or violent material
    • Posting (or threatening to post) other people’s personally identifying information (“doxing”)
    • Personal insults, especially those using racist or sexist terms
    • Unwelcome sexual attention
    • Advocating for, or encouraging, any of the above behavior
    • Repeated harassment of others. In general, if someone asks you to stop, then stop
  6. Moderate your expectations. Please respect that community members choose how they spend their time in the project. A thoughtful question about your expectations is preferable to demands for another person’s time.

  7. When we disagree, try to understand why. Disagreements, both social and technical, happen all the time and BioPAL is no exception. Try to understand where others are coming from, as seeing a question from their viewpoint may help find a new path forward. And do not forget that it is human to err: blaming each other does not get us anywhere, while we can learn from mistakes to find better solutions.

  8. A simple apology can go a long way. It can often de-escalate a situation, and telling someone that you are sorry is an act of empathy that does not automatically imply an admission of guilt.

Responding to inappropriate behavior

In some cases, individuals may violate the CoC in online or in-person situations. If any community member deems the action to be harmful to the community, they may act immediately to defuse the situation. This includes actions directed at the situation, rather than at an individual, such as locking a thread, temporarily suspending a user’s account in the community forum, calling a meeting break, or generally acting to de-escalate the situation. Follow-up your actions by reporting the incident to the CoC committee.

If the incident involves physical danger, or involves a threat to anyone’s safety (such as threats of violence), any member of the community may – and should – act unilaterally to protect the safety of any community member. This can include contacting law enforcement, other members of the Jupyter community, or other local personnel that are present.

In situations where an individual community member acts unilaterally, they must inform the Code of Conduct committee as soon as possible, by e-mailing biopal@esa.int within 24 hours.

Reporting

If you believe someone is violating the code of conduct, please report this in a timely manner. Code of conduct violations reduce the value of the community for everyone and we take them seriously.

You can file a report by emailing biopal@esa.int. For more details or information on reporting in-person at an event, please see our Reporting Guidelines.

Enforcement

For information on enforcement, please view the Enforcement Manual.

Document History

TBD

Acknowledgments

Original text courtesy of the Speak Up!, Django and Jupyter Projects, modified by BioPAL. We are grateful to those projects for contributing these materials under open licensing terms for us to easily reuse.

License

All content on this page is licensed under a Creative Commons Attribution license.

1.2 - Enforcement Manual

Enforcement of the BioPAL Code of Conduct

This is the enforcement manual followed by BioPAL’s Code of Conduct Committee. It’s used when we respond to an incident to make sure we are consistent and fair.

The Code of Conduct Committee

All responses to reports of conduct violations will be managed by a Code of Conduct Committee (“the committee”). The BioPAL Steering Council is responsible for vetting and appointing the Code of Conduct Committee. During periods where a separate Code of Conduct Committee is not appointed or is not available to handle a code of conduct report promptly, the BioPAL Steering Council will serve as the interim Code of Conduct Committee.

If a Code of Conduct report involves a member of the Steering Council or Code of Conduct Committee, that member will not participate in the investigation or any decisions related to that report.

Current Code of Conduct Committee members

Alphabetical by surname name:

  • Clement Albinet, @ClementAlbinet (2020)
  • Stefanie Lumnitz, @slumnitz (2020)
  • Paolo Mazzucchelli, @pmazzucchelli (2020)

Enforcement guidelines and principles

Enforcing the Code of Conduct impacts our community today and for the future. It’s an action that we do not take lightly. When reviewing enforcement measures, the Code of Conduct Committee will keep the following values and guidelines in mind:

  • Act in a personal manner rather than impersonal. The Committee can engage the parties to understand the situation, while respecting the privacy and any necessary confidentiality of reporters. However, sometimes it is necessary to communicate with one or more individuals directly: the Committee’s goal is to improve the health of our community rather than only produce a formal decision.

  • Emphasize empathy for individuals rather than judging behavior, avoiding binary labels of “good” and “bad/evil”. Overt, clear-cut aggression and harassment exists and will be addressed unambiguously. But many scenarios that can prove challenging to resolve are those where normal disagreements devolve into inappropriate behavior from multiple parties. Understanding the full context and finding a path that re-engages all is hard, but ultimately the most productive for our community.

  • Help increase engagement in good discussion practice: try to identify where discussion may have broken down and provide actionable information, pointers and resources that can help enact positive change on these points.

  • Be mindful of the needs of new members: provide them with explicit support and consideration, with the aim of increasing participation from underrepresented groups in particular.

  • Individuals come from different cultural backgrounds and native languages. While lack of intent to harm is not an excuse, try to identify any honest misunderstandings caused by a non-native speaker and help them understand the issue and how to change. Complex discussion in a foreign language can be very intimidating, and we want to grow our diversity also across nationalities and cultures.

  • Our actions will reflect compassion for all individuals. We will seek to understand, to educate, and, as necessary, take action.

Mediation: voluntary, informal mediation is a tool at our disposal. In contexts such as when two or more parties have all escalated to the point of inappropriate behavior, it may be useful to facilitate a mediation process. This is only an example: the Committee can consider mediation in any case, mindful that the process is meant to be strictly voluntary and no party can be pressured to participate. If the Committee suggests mediation, it should:

  • Find a candidate who can serve as a mediator.
  • Obtain the agreement of the reporter(s). The reporter(s) have complete freedom to decline the mediation idea, or to propose an alternate mediator.
  • Obtain the agreement of the reported person(s).
  • Settle on the mediator: while parties can propose a different mediator than the suggested candidate, only if common agreement is reached on all terms can the process move forward.
  • Establish a timeline for mediation to complete, ideally within two weeks.

The mediator will engage with all the parties and seek a resolution that is satisfactory to all. Upon completion, the mediator will provide a report (vetted by all parties to the process) to the Committee, with recommendations on further steps. The Committee will then evaluate these results (whether satisfactory resolution was achieved or not) and decide on any additional action deemed necessary.

How the committee will respond to reports

When a report is sent to the committee they will immediately reply to the reporter to confirm receipt. This reply must be sent within 48 hours, and the group should strive to respond much quicker than that.

See the Reporting Guidelines for details of what reports should contain. If a report doesn’t contain enough information, the committee will obtain all relevant data before acting. The committee is empowered to act on the Steering Council’s behalf in contacting any individuals involved to get a more complete account of events.

The committee will then review the incident and determine, to the best of their ability:

  • What happened.
  • Whether this event constitutes a Code of Conduct violation.
  • Who are the responsible party(ies).
  • Whether this is an ongoing situation, and there is a threat to anyone’s physical safety.

This information will be collected in writing, and whenever possible the group’s deliberations will be recorded and retained (i.e. chat transcripts, email discussions, recorded conference calls, summaries of voice conversations, etc).

It is important to retain an archive of all activities of this committee to ensure consistency in behavior and provide institutional memory for the project. To assist in this, the default channel of discussion for this committee will be the BioPAL e-mail list accessible to current and future members of the committee as well as members of the Steering Council upon justified request. If the Committee finds the need to use off-list communications (e.g. phone calls for early/rapid response), it should in all cases summarize these back to the list so there’s a good record of the process.

The Code of Conduct Committee should aim to have a resolution agreed upon within one week. In the event that a resolution can’t be determined in that time, the committee will respond to the reporter(s) with an update and projected timeline for resolution.

Incident Response and Committee Actions

If the act is ongoing, or involves a threat to anyone’s safety (e.g. threats of violence), any committee member may act immediately (before reaching consensus) to address the situation. In ongoing situations, any member may decide to employ any of the tools available to the committee, including bans and blocks.

If the incident involves physical danger, any member of the committee may – and should – act unilaterally to protect the safety of those involved. This can include contacting law enforcement (or other local personnel) and speaking on behalf of the BioPAL Steering Council.

In situations where an individual committee member acts unilaterally, they must report their actions to the committee for review within 24 hours.

At events where no Committee members may be present, an event organizer will act as their delegate. They will forward any reports to the Committee, as well as a summary of any action they may have taken during the event.

Resolutions

The committee must agree on a resolution by consensus. If the group cannot reach consensus and deadlocks for over two weeks, the group will turn the matter over to the Steering Council for resolution.

Possible responses may include:

  • Taking no further action
    • if we determine no violations have occurred.
    • if the matter has been resolved publicly while the committee was considering responses.
  • Coordinating voluntary mediation: if all involved parties agree, the Committee may facilitate a mediation process as detailed above.
  • Remind publicly, and point out that some behavior/actions/language have been judged inappropriate and why in the current context, or can but hurtful to some people, requesting the community to self-adjust.
  • A private reprimand from the committee to the individual(s) involved. In this case, the group chair will deliver that reprimand to the individual(s) over email, cc’ing everyone involved.
  • A public reprimand. In this case, the committee chair will deliver that reprimand in the same venue that the violation occurred, within the limits of practicality. E.g., the original issue report for a CoC violation within a filed issue, but for a chat room discussion where the person/context may be gone, they can be reached by other means. The group may choose to publish this message elsewhere for documentation purposes.
  • A request for a public or private apology, assuming the reporter agrees to this idea: they may at their discretion refuse further contact with the violator. The chair will deliver this request. The committee may, if it chooses, attach “strings” to this request: for example, the group may ask a violator to apologize in order to retain one’s membership on a mailing list.
  • A “mutually agreed upon hiatus” where the committee asks the individual to temporarily refrain from community participation. If the individual chooses not to take a temporary break voluntarily, the committee may issue a “mandatory cooling off period”.
  • A permanent or temporary ban from some or all BioPAL spaces (BioPAL organisation, Slack, etc.). The group will maintain records of all such bans so that they may be reviewed in the future or otherwise maintained.

Once a resolution is agreed upon, but before it is enacted, the committee will contact the original reporter and any other affected parties and explain the proposed resolution. The committee will ask if this resolution is acceptable, and must note feedback for the record. However, the committee is not required to act on this feedback.

Finally, the committee will make a report to the BioPAL Steering Council (as well as the BioPAL core team in the event of an ongoing resolution, such as a ban).

The committee will never publicly discuss the issue; all public statements will be made by the chair of the Code of Conduct Committee or the BioPAL Steering Council.

Conflicts of Interest

In the event of any conflict of interest, a committee member must immediately notify the other members, and recuse themselves if necessary.

Acknowledgments

Original text courtesy of the Speak Up!, Django and Jupyter Projects, modified by BioPAL. We are grateful to those projects for contributing these materials under open licensing terms for us to easily reuse.

License

All content on this page is licensed under a Creative Commons Attribution license.

1.3 - FAQ

BioPAL Code of Conduct - Frequently Asked Questions

This FAQ attempts to address common questions and concerns around the BioPAL community’s Code of Conduct. If you still have questions after reading it, please feel free to contact us at biopal@esa.int.

Why have you adopted a Code of Conduct?

We think the BioPAL community is awesome. If you’re familiar with the BioPAL community, you’ll probably notice that the Code basically matches what we already do. Think of this as documentation: we’re taking implicit expectations about behavior and making them explicit.

Maintaining a Code of Conduct forces us to consider and articulate what kind of community we want to be, and serves as a constant reminder to put our best foot forward. But most importantly, it serves as a signpost to people looking to join our community that we feel these values are important.

We know that the BioPAL community is open, friendly, and welcoming. We want to make sure everyone else knows it too.

What does it mean to “adopt” a Code of Conduct?

For the most part, we do not think it means large changes. We think that the text does a really good job describing the way the BioPAL community already conducts itself. We expect that most people will simply continue to behave as they have in the past.

However, we do expect that people will abide by the spirit and words of the Code of Conduct when in “official” BioPAL spaces. In practice, BioPAL spaces include mailing lists, various communication channels, and events.

What happens if someone violates the Code of Conduct?

We are all stewards of our community, and are encouraged to participate in ways that defend the values highlighted in this document and help others understand when their actions go against these values (by engaging them and directing them to this document if necessary). If that doesn’t work, or if you need more help, you can contact biopal@esa.int. For more details please see our Reporting Guidelines.

Acknowledgments

Original text courtesy of the Speak Up!, Django and Jupyter Projects, modified by BioPAL. We are grateful to those projects for contributing these materials under open licensing terms for us to easily reuse.

License

All content on this page is licensed under a Creative Commons Attribution license.

1.4 - Reporting Guide

BioPAL Code of Conduct - Reporting Guide - Online Community

If you believe someone is violating the code of conduct we ask that you report it to BioPAL by emailing biopal@esa.int. All reports will be kept confidential. In some cases we may determine that a public statement will need to be made. If that’s the case, the identities of all involved will remain confidential unless those individuals instruct us otherwise.

If you believe anyone is in physical danger, please notify appropriate law enforcement first. If you are unsure what law enforcement agency is appropriate, please include this in your report and we will attempt to notify them.

If you choose to email, please include the following information:

  • Your contact info (not required)
  • Names (real, nicknames, or pseudonyms) of any individuals involved. If there were other witnesses besides you, try to include them as well (not required)
  • When and where the incident occurred. Please be as specific as possible.
  • Your account of what occurred. If there is a publicly available record (e.g. a Slack chat or GitHub issue) please include a link
  • Any extra context you believe exists for the incident
  • If you believe this incident is ongoing
  • Any other information you believe we should have

Note: with anonymous reports, there are inherent limits in our ability to do follow-up or collect additional information. Hence we suggest that if you would like to remain anonymous, you at least create a throw-away email address without your real name.

What happens after you file a report?

You will receive an email from the BioPAL Code of Conduct Committee acknowledging receipt immediately. We promise to acknowledge receipt within 48 hours (and will aim for much quicker than that).

The committee will immediately communicate to review the incident and determine:

  • What happened
  • Whether this event constitutes a Code of Conduct violation
  • Who the individual(s) involved were
  • Whether this is an ongoing situation, or if there is a threat to anyone’s physical safety

If this is determined to be an ongoing incident or a threat to physical safety, the committee’s immediate priority will be to protect everyone involved. This means we may delay an “official” response until we believe that the situation has ended and that everyone is physically safe.

The Code of Conduct committee will then follow the standard procedure to arrive at and communicate a resolution.

Appealing the Code of Conduct Committee’s Response

To appeal a decision of the Code of Conduct Committee, contact the BioPAL Steering Council at biopal@esa.int with your appeal and they will review the case.

The Steering Council will gather all relevant information from the Committee and provide a resolution within two weeks. If more time is required, it should inform the appellant within that time frame.

Acknowledgments

Original text courtesy of the Speak Up!, Django and Jupyter Projects, modified by BioPAL. We are grateful to those projects for contributing these materials under open licensing terms for us to easily reuse.

License

All content on this page is licensed under a Creative Commons Attribution license.

2 - Git Tutorial

Getting started with git

This section is a gentle introduction on how to get started with git and the collaborative workflow using the command line.

2.1 - Git installation

Installing git and setting up your bash console

Before you start using git for your Python projects or other collaborative purposes, you have to choose and set up an environment that allows you to work with git and install the latest version of git.

Git can be used through many different interfaces. Throughout this collection of resources we will predominantly be working with git in the command line in order to manage collaborative projects. To get started you’ll set up a command line interface, install git and optionally a gui. Gui’s are often helpful to check a projects branch structure and see which branches are merged, not merged and under development.

Linux

Checklist:

  • git & git bash installed
  • configured identity
  • git command line interface personalized (optional)
  • set-up user account on i.e. github or gitlab

If you want to install the basic Git tools on Linux via a binary installer, you can generally do so through the package management tool that comes with your distribution. If you’re on Fedora (or any closely-related RPM-based distribution, such as RHEL or CentOS), you can use dnf:

sudo dnf install git-all

If you’re on a Debian-based distribution, such as Ubuntu, try apt:

sudo apt install git-all

For more options, there are instructions for installing on several different Unix distributions on the Git website, at linux installation page.

Windows

Checklist:

  • install VS Code editor (optional)
  • git & git bash installed
  • configured identity
  • git gui installed (optional)
  • git command line interface personalized (optional)
  • set-up user account on i.e. github or gitlab

Editor: Visual Studio Code

If you are not familiar with vim, nano or other text editors used in the command line you can make access to git easier by installing the open-source text editor and Python IDE Visual Studio Code (VS Code). Download the windows version of VS Code, then run the installer. Accept most default configurations on all pages except for the following:

  • (Optional) On the Select Additional Tasks page, check “Create a desktop icon” under “Additional icons”.
  • Also on the Select Additional Tasks page check all four boxes under “Other”
    1. “Add ‘Open with Code’ action to Windows file context menu”
    2. “Add ‘Open with Code’ action to Windows directory context menu”
    3. “Register Code as an editor for supported file types”
    4. “Add to PATH” (this should be selected by default).

Git and Bash Shell

(Please note VS Code should be installed before this step.) There are multiple different ways to install git on Windows. I recommend installing the official and latest git version. It will come with a command line tool. Download the official windows installer form here, then run the installer. If you have not used git before, accept most default configurations on all pages except for the following:

  • (Optional) On the Select Components page, check “On the Desktop” under “Additional icons”.
  • On the Choosing the default editor used by Git page, think about which editor you’d prefer to use and feel comfortable using. “Use Visual Studio Code as Git’s default editor” from the drop-down menu if you are not comfortable yet using i.e. vim.

To check if your installation was successful open teh Git Bash program (if you checked the option you can find it as a new icon on your desktop). The type:

git --version

to check which version of git was installed. Then run the following commands, make sure you add your name and e-mail address, to let git know who you are:

git config --global user.name "Name Surname"

git config --global user.email "name.surname@examplemail.com"

MacOS

Checklist:

  • commandline/ terminal available
  • git installed
  • configured identity
  • git gui installed (optional)
  • git command line interface personalized (optional)
  • set-up user account on i.e. github or gitlab

Command line interface

Using the command line on MacOS is straight forward as MacOS comes with the Terminal already installed. The easiest way to open the Terminal is to search for it via MacOS Spotlight. Open spotlight by pressing cmd+space or navigating to the Search icon in the top right corner. Then look for the Terminal and double click to open.

Installing git

There are multiple ways to install git on MacOS and modern Macs ship with a pre installed version of git through the Xcode Command Line Tools. To check if git is installed type in your terminal:

git --version

If git is not already installed you’ll get prompted to install it. Follow the suggestions in the command line. Once the installation has finished, run the following commands, make sure you add your name and e-mail address, to let git know who you are:

git config --global user.name "Name Surname"

git config --global user.email "name.surname@examplemail.com"

Gui

In most cases, gitk, a gui to check your projects branch structure, will automatically be installed with git on MacOS. You can check if gitk is installed by typing:

gitk --all

A small separate pop-up window should open, either showing you the branch structure of the project - in case you opened gitk in a git directory -, or showing a message explaining that not git repository could be found.

There are many alternatives to gitk with more elaborative gui’s, i.e. gitdesktop. However, gitk provides all functionality needed for the beginning. of course there is also a way to check your branch structure directly from the terminal without a gui. You could for example inspect the output of:

git log --oneline

Trouble shooting

In case you have trouble accessing git via the commandline, try:

  • Installing the latest version of Xcode through the app store
  • Install git using Homebrew

Personalized command line interface

Personalizing your command line interface, for example, to show the branch name you are currently using, can make working with git much easier. Copy these following lines:

parse_git_branch() {
     git branch 2> /dev/null | sed -e '/^[^*]/d' -e 's/* \(.*\)/ (\1)/'
}
export PS1="\u@\h \[\033[32m\]\w\[\033[33m\]\$(parse_git_branch)\[\033[00m\] $ "

and past them to your ~/.bashrc file. Then restart your terminal, i.e. by typing source ~/.bashrc or opening and closing it.

Further reading and Sources:

2.2 - Collaborating on an existing project

Collaborating on BioPAL

This section introduces you to getting started with BioPAL in git and gives you an example of a basic git workflow.

Setting-up, cloning an existing project

  1. Navigate to the existing project on github in your web browser:
https://github.com/biopal/biopal
  1. Create a fork of the project in your profile by clicking the fork icon in the top right corner and selecting you profile. This allows you to track your changes, and save them to your own profile before integrating them to the official version of the project.

  2. Copy the link of your forked version of the project, found under the green code button on the right hand side:

https://github.com/YOURUSERNAME/biopal.git 
  1. In the terminal, navigate to a directory you’d like to store your project in. You can for example create a new projects directory to store your git projects under. Type into git bash or terminal:
mkdir ~/projects # to create a directory
cd ~/projects    # to navigate to the directory
  1. Clone the project using git clone <url>:
git clone https://github.com/biopal/biopal.git

This creates a new directory named ~/projects/biopal, initializes a .git directory inside it, pulls down all the data for that repository, and checks out a working copy of the latest version. If you go into the new biopal directory that was just created, you’ll see the project files in there, ready to be worked on or used.

  1. Check your remotes by typing git remote -v into the command line. Your git remotes point to the online github repository and will help you synchronize with your online fork of the project. You will now set up your git remote, aiming for git remote -v to display:
origin	https://github.com/YOURUSERNAME/biopal.git (fetch)
origin	https://github.com/YOURUSERNAME/biopal.git (push)
upstream	https://github.com/biopal/biopal.git (fetch)
upstream	https://github.com/biopal/biopal.git (push)

It is likely that git remote -v will look more something like this:

upstream	https://github.com/YOURUSERNAME/biopal.git (fetch)
upstream	https://github.com/YOURUSERNAME/biopal.git (push)

We will first, need to rename upstream to origin which will point to your personal fork of the project created in step 2. Type:

git remote rename upstream origin

Check if upstream was renamed to origin typing git remote -v. Next we need to add a new upstream this will point to the original project you saw in step 1. To add an upstream type:

git remote add upstream https://github.com/biopal/biopal.git

Note depending on your access/ development rights in the origin project you may or may not be able to push to upstream. In general it is considered best practice to ALWAYS push to origin first, and then point a Pull Request to upstream if upstream is a collaborative project. To finish, verify that all changes were made successfully checking the output of git remote -v.

You are now ready to make your first changes!

Making changes in your project and adding them

General workflow:

  1. Make sure you are on the right working branch or create a new branch: git checkout -b NEW
  2. Make changes
  3. Stage changed files for commit: git status (optional, to check changed files), git add <file_name>
  4. Commit staged files and write a commit message: git commit -m "[ENH] my message"
  5. Push commits in branch NEW to github origin: git push origin NEW
  6. Create a PR pointing your branch NEW to your origin main or to the upstream main
  7. Include changes in your local main branch: git checkout main, then git pull upstream or git pull origin
  8. Repeat with step 1 or rebase your working branch NEW onto your local main and repeat with step 2: git checkout NEW and git rebase main NEW

Further Reading: