inspired by The Turing Way
🎉🎈🍰 Welcome to URSC 645 Urban and Regional Analytics repository! 🍰🎈🎉
💫🐥☀️ We're excited that you're here and want to contribute. ☀️🐥💫
We want to ensure that every user and contributor feels welcome, included and supported to participate in the URSC 645 community. We hope that the information provided in this document will make it as easy as possible for you to get involved.
We welcome all contributions to this project via the course Google Docs, as a GitHub collaborator, or using GitHub issues and pull requests. Please follow these guidelines to make sure your contributions can be easily integrated into the projects. As you start contributing to URSC 645, don't forget that your ideas are more important than perfect pull requests. ❤️
If you have any questions that aren't discussed below, please let us know through one of the many ways to get in touch.
Been here before? Already know what you're looking for in this guide? Jump to the following sections:
- Joining the community
- Inclusivity
- Get in touch
- Contributing through Google Drive
- Contributing through GitHub
- Writing in Markdown
- Where to start: issues
- Making a change with a pull request
The URSC 645 is a course at Texas A&M University in the Department of Landscape Architecture and Urban Planning. Currently, this repository does not have an official Code of Conduct. The Code of Conduct described by the Turning Way is a good example.
The URSC 645 course primarily includes PhD students in the Department of Landscape Architecture and Urban Planning at Texas A&M University. However, the repository would like to also include former students, faculty, and other interested parties.
The material in the GitHub repository is open to anyone with internet access. If you would like to contribute feel free to create a new GitHub Issue or Pull Request.
Most of the Google Docs linked in the repository are viewable by anyone with the link. However, access to editing and contributing to the Google Docs is limited to the course instructors and current students enrolled in the course.
Students enrolled in the course have access to the course's shared Google Drive Folder. The Google Drive folder contains more material than is currently in the GitHub repository. The Google Drive folder is also the primary location for students to submit their assignments.
There are many ways to get in touch with URSC 645 team!
- GitHub issues and pull requests
- Join a discussion, collaborate on an ongoing task and exchange your thoughts with others.
- Can't find your idea being discussed anywhere? Open a new issue! (See our Where to start: issues section below.)
- Slack Channel - Currently not using Slack.
- Contact the Course Instructor of URSC 645 project – Nathanael Rosenheim – by email at nrosenheim@arch.tamu.edu
The current way to receive updates is to Watch the repository. This will send you an email every time a new issue or pull request is opened. Instructions on how to do this can be found here.
Access to the Google Drive is limited to students enrolled in URSC 645. Students enrolled in the course will be able to add files, create folders, and edit files in the Google Drive. Students enrolled in the course will also be able to submit their assignments through the Google Drive.
In order to contribute via GitHub, you'll need to set up a free account and sign in. Here are some instructions to help you get going. Remember that you can ask us any questions you need to along the way.
To use GitHub requires setting up your local machine by following the tasks described in the Getting Started Page.
GitHub has a helpful page on getting started with writing and formatting on GitHub.
Most of the writing that you'll do will be in Markdown.
You can think of Markdown as a few little symbols around your text that will allow GitHub to render the text with a little bit of formatting.
For example, you could write words as bold (**bold**), or in italics (_italics_), or as a [link][rick-roll] ([link](https://youtu.be/dQw4w9WgXcQ)) to another webpage.
Also when writing in Markdown, please start each new sentence on a new line. Having each sentence on a new line will make no difference to how the text is displayed, there will still be paragraphs, but it makes the diffs produced during the pull request review easier to read! ✨
The current URSC 645 repository does not have a book version - but this is something that is on the to-do list. When the book is developed the writing style will be more formal and will follow the The Turing Way Style Guide.
Before you open a new issue, please check if any of our open issues cover your idea already. If you open a new issue, please follow our basic guidelines laid out in our issue templates. There are 2 issues template to choose from.:
- General (preview here): Use this template for a general issue related to the book, community, process or ideas.
- Bug Report (preview here): With this template, create an issue report that can help others repair something that is currently broken. This can be used for reporting errors like typos and broken links. The issue template will automatically be rendered in the comment section of the new issue page, so all you need to do is edit the "Lorem ipsum" sections.
We appreciate all contributions to URSC 645. THANK YOU for helping us build this useful resource. ✨🌟💫
All project management, conversations and questions related to URSC 645 project happens here in URSC 645 repository.
The following steps are a guide to help you contribute in a way that will be easy for everyone to review and accept with ease 😎.
Add a comment on an existing issue or open a new issue referencing your addition
This allows other members of URSC 645 team to confirm that you aren't overlapping with work that's currently underway and that everyone is on the same page with the goal of the work you're going to carry out.
This blog is a nice explanation of why putting this work in upfront is so useful to everyone involved.
Remember, if you open a new issue, please follow our basic guidelines laid out in our issue template. The issue template will automatically be rendered in the comment section of the new issue page so all you need to do is edit the "Lorem ipsum" sections.
This is now your own unique copy of URSC 645. Changes here won't affect anyone else's work, so it's a safe space to explore edits to the code!
Make sure to keep your fork up to date with the main repository, otherwise, you can end up with lots of dreaded merge conflicts. If you prefer working in the browser, these instructions describe how to sync your fork to the original repository via GitHub.
Try to keep the changes focused. If you submit a large amount of work all in one go it will be much more work for whoever is reviewing your pull request. Help them help you. 😉
While making your changes, commit often and write good, detailed commit messages. This blog explains how to write a good Git commit message and why it matters. It is also perfectly fine to have a lot of commits - including ones that break code. A good rule of thumb is to push up to GitHub when you do have passing tests then the continuous integration (CI) has a good chance of passing everything. 😸
If you feel tempted to "branch out" then please make a new branch and a new issue to go with it. This blog details the different Git branching models.
Please do not re-write history! That is, please do not use the rebase command to edit previous commit messages, combine multiple commits into one, or delete or revert commits that are no longer necessary.
Are you new to Git and GitHub or just want a detailed guide on getting started with version control? Check out our Version Control chapter in The Turing Way Book!
Submit a pull request
We encourage you to open a pull request as early in your contributing process as possible. This allows everyone to see what is currently being worked on. It also provides you, the contributor, feedback in real-time from both the community and the continuous integration as you make commits (which will help prevent stuff from breaking).
When you are ready to submit a pull request, you will automatically see the Pull Request Template contents in the pull request body. It asks you to:
- Describe the problem you're trying to fix in the pull request, reference any related issue and use fixes/close to automatically close them, if pertinent.
- List of changes proposed in the pull request.
- Describe what the reviewer should concentrate their feedback on.
By filling out the "Lorem ipsum" sections of the pull request template with as much detail as possible, you will make it really easy for someone to review your contribution!
If you have opened the pull request early and know that its contents are not ready for review or to be merged, add "[WIP]" at the start of the pull request title, which stands for "Work in Progress". When you are happy with it and are happy for it to be merged into the main repository, change the "[WIP]" in the title of the pull request to "[Ready for review]".
A member of URSC 645 team will then review your changes to confirm that they can be merged into the main repository. A review will probably consist of a few questions to help clarify the work you've done. Keep an eye on your GitHub notifications and be prepared to join in that conversation.
You can update your fork of URSC 645 repository and the pull request will automatically update with those changes. You don't need to submit a new pull request when you make a change in response to a review.
You can also submit pull requests to other contributors' branches! Do you see an open pull request that you find interesting and want to contribute to? Simply make your edits on their files and open a pull request to their branch!
GitHub has a nice introduction to the pull request workflow, but please get in touch if you have any questions 🎈.
These Contributing Guidelines have been adapted from the Contributing Guidelines of the Turing Way! (License: CC-BY)