GitHub Guide

Git is a tool used to keep track of changes to files stored in a repository (version control). GitHub is an online platform which sits on top of Git and supports collaborative and distributed working through the internet.

We know that it can be daunting to start using Git and GitHub if you haven’t worked with them in the past, but we are here to help you figure out any of the jargon or confusing instructions you encounter!

Using GitHub issues

GitHub issues are used to track tasks and ideas on a GitHub repository.

If you have an idea for an issue, please check if any of our open issues cover your idea already. If not, will need to open a new issue on the MapReader repository.

To ensure opening new issues is as easy as possible, we have set up three issue templates with guidelines of what information to include in each type of issue. These are:

  • Bug report (preview here): This template should be used to report bugs in the MapReader code.

  • Feature request (preview here): This template should be used to suggest new features/functionalities that could be incorporated into the MapReader code.

  • Documentation update (preview here): This template should be used for reporting errors, like typos and broken links, in our documentation and to suggest updates or new additions to documentation/tutorials/worked examples/etc.

If you feel your issue does not fit any of these templates, please open a blank issue and provide as much information as possible to help the MapReader community work to resolve the issue.

Making GitHub pull requests

GitHub pull requests <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests> are used to tell others you have made changes to a repository and would like them to be “pulled” into the main branch.

If you would like to contribute to MapReader by making changes to the current code or documentation, you will need to:

  1. Comment on an existing issue (or create a new issue) and let people know the changes you plan on making.

  2. Fork the MapReader repository - this creates a copy of it on your own account. You can then experiment with making your changes here without influencing or breaking the main repository.

  3. Make your changes.

  4. Submit a pull request to let the MapReader team know you’ve made changes and are ready for them to be reviewed.

Please ensure your pull request contains as much information as possible and links to the issue(s) you are resolving. Our pull request template (preview here) should help you with this.

Once created, your pull request will be reviewed by a member of the MapReader team and, once approved, your changes will be merged into the main branch of MapReader repository. To make this review process as easy as possible, please try to work on only one issue/problem per pull request and ensure your commit messages are clear and insightful. You may find it useful to create separate branches for each issue/problem you are working on. Each of these can then be linked to their own pull request.

Most importantly, as you start contributing to MapReader, don’t forget that your ideas are more important than perfect pull requests!

More information

If you are still confused or want to understand more about how these different features are used, GitHub’s documentation pages are full of useful information and tutorials.

You are also more than welcome to contact us directly to ask us questions.