project-guide

GUIDE TO PROJECTS ON GITHUB

Project maintained by thebhavana Hosted on GitHub Pages — Theme by mattgraham

LET’S BEGIN 🔥

Repository organizes single project. It contains folder, files, video, spreadsheets and data sets with information about project. Branch is a way to work on different versions of repository at a time. The default branch is main. Commits are saved changes on Github, with a description explaining why a particular change was made. Pull request includes proposing changes and requesting others to review and pull in your contribution to merge into thier branch. Merging pull request means bringing changes together.

CREATING REPOSITORY 💼

  1. In upper right corner, next to your avatar or identicon, click + and then select new repository.
  2. Name your repository myfirst-repo.
  3. Write a short description.
  4. Select initialize this repository with ReadME.
  5. Click create repository.

CREATING BRANCH ⚓

  1. Go to your new repository myfirst-repo.
  2. Click the drop down menu at the top of the file list that says branch:main.
  3. Type a branch name, readme-edits, into the new branch text box.
  4. Select the blue Create branch box or hit “Enter” on your keyboard.

COMMIT CHANGES 🎉

  1. Click the README .md file.
  2. Click the ✏️ icon in the upper right corner of the file view to edit.
  3. In the editor, write something about project.
  4. Write a commit message that describes your changes.
  5. Click commit changes button.

CREATE PULL REQUEST ✋

  1. Click Pull Request tab, and click green New pull Request button.
  2. In example comparison box, select branch you made, readme-edits, to compare with main(the original).
  3. Look over your changes in the diffs on the compare page, make sure they’re what you want to submit.
  4. Click the big green Create Pull Request button.
  5. Give your pull request a title and write a brief description of your changes.

MERGE PULL REQUEST 🔀

  1. Click the green Merge Pull Request button to merge the changes into the main branch.
  2. Click confirm merge.
  3. Go ahead and delete the branch, with delete branch button in purple box.

CONTRIBUTIONS ㊗️

GITHUB FLOW ➡️

It is light weight, branch-based workflow that supprts teams and projects where deployements are made regularly. When you create a branch in project, you’re creating an environment where you try out new ideas. Changes you make on a branch dont affect main branch, so you are free to experiment and commit changes, safe in the knowledge that your branch won’t be merged until it’s ready to be reviewed by someone you’re collaborating with.Your branch name should be descriptive because it is created off main when working on a feature or fix.

GIT HANDBOOK 📘

Version control system tracks (VCS) history of change as people and teams collaborate on projects together. As the project envolves, teams can run tests, fix bugs, and contribute new code with the confidence that any version can be recovered at any time. Developers can also review project history to find…

Distributed Version control system (DVCs) is commonly used for open source and commercial software development. They allow access to every file, branch and iteration of project, and allow every user access to full and self-contaimed history of all changes. Developers can work anywhere and collaborate asynchronously from any time zone.

BASIC GIT COMMANDS

HOW GITHUB WORK 🚧

GitHub builds collaboration directly into thye developmenmt process. Work is organized into repositories, where developers can outline requirements or directions and set expectations for team members. Developers simply create a branch to work on updates, commit changes to save them, open a pull request to propose and discuss changes, and merge pull requests once everyone is on same page.

  1. git clone https://github.com/me/repo.git
  2. cd repo
  3. git branch my-branch
  4. git checkout my-branch
  5. git add file1.md file2.md
  6. git commit -m “my snapshot”
  7. git push –set-upstream origin my-branch
  1. git init my-repo
  2. cd my-repo
  3. touch README.md
  4. git add README.md
  5. git commit -m “add README”
  6. git remote add origin https://github.com/YOUR-USERNAME/YOUR-REPOSITORY.git
  7. git push –set-upstream origin master
  1. cd repo
  2. git pull
  3. git checkout feature -a
  4. git add file1.md
  5. git commit -m “edit file 1”
  6. git push

GITHUB PAGES 📃

They are public web pages hosted and published by GitHub. Use Jekyll Theme chooser to load a pre-made theme. You can modify your content and style them remotely i.e. the web or locally on your computer.

  1. Once you sign in, create new repository.
  2. Open Settings tab
  3. Choose theme button
  4. Select a theme
  5. Write your content
  6. Commit changes

FORKING PROJECTS ✨

Creating a fork is producing personal copy of someone else’s project. It acts as a sort of bridge between original repository and your personal copy. You can submit PULL Requests to help make other people’s project better by offering your changes upto the original project.Pull Requests are an area of discussion.

It is core of Social coding on GitHub.

  1. Fork the repository in header.
  2. Clone or Download
  3. Making and Pushing changes
  4. Making a Pull Request
  5. Compare and Pull Request
  6. Create Pull Request

BE SOCIAL👥

With more and more people joining GitHub and adding projects everyday, keeping up with them all can be difficult. This can be fun and easy by following users or watching reposityories, or simply showing interst by starring, or using explore to find out new people and projects.

  1. Follow a friend
  2. Watch a project’s repository
  3. Stargazing
  4. Discover repositories
  5. Explore/Newsletter

CITABLE CODE ⌨️ 💻

Digital Object Identifiers are the backbone of academic reference and metric systems. If you’re a researcher writing software, this will explain you how to make the work you share on GitHub by archiving one of your GitHub repositories and assigning a DOI with the data archiving tool Zenodo

  1. Choose your repository
  2. Login to Zenodo
  3. Pick repository to archive
  4. Click repository settings
  5. Create new release
  6. Minting a DOI
  7. FINISHING UP

MASTER ISSUES 🐛

Issues are great way to keep track of tasks, enhancements, and bugs for your project. They’re kind like email -exept that can be shared and discussed with rest of your team. Most software projects have bug tracker of some kind. GitHub’s tracker is called issues, and has its own section in repository.It is special because of our focus on collaboration, references, and excellent text formatting.

TYPICAL ISSUE

Milestones 🎯

They are group of issues that correspond to a project, feature, or time period. People use them in many different ways in software development. Some milestones are…

  1. Beta Launch - File bugs you need to fix before the launch of your beta project. It’s great way to sure you’re missing anything.
  2. October Sprint - File issues that you’d like to work on in October. It’s great way to focus on efforts when there’s lot to do so.
  3. Redesign - File issues related to redesigning of project. It’s great way to collect ideas on what to work on.

Labels 🏷️

It organize different types of issues. Issues can have as many labels as you want, and you can filter one or more labels at once. Some labels are…

  1. css
  2. js
  3. cofirmed
  4. feature

Assignees 🙆

Assignee is one person that’s responsible for moving the issue forward. They are selected the same way milestones are, through the grey bar at top of issue.

Notifications 🔔

There are 2 ways to recieve notifications,email and web. Notifications are GitHub’s way to keep up to date with your issues. You can use them to find out new repositories, or just to know when someone need’s your input to move forward on an issue. How you recieve notifications…

  1. Participating
  2. Watching

@Mentions 📲

It’s way to reference other GitHub users inside of GitHub issues. Inside description or any comment of the issue, include the @username of another GitHub user to send them a notification. Use /cc syntax to include people in issues.

It looks function not working. Maybe a broser bug? @user1 @user2

If you dont know specific users to include who might be able to help you, reference the team with @mentions. If browser-bug is team under klopo organization…

/cc@klopo/browser-bugs

References ➡️

Often time issues are dependent on other issues, or at least relate to one of them and you’d like to connect the two. You can refer issues by typing in a hashtag(#) plus the issue number

Hey @user1, I think problem started in #49

By doing this, we create an event inside of issue #49. If there is issue in another repository, just include the issue number inside of the commit message. By prefacing your commits with “Fixes”, “Fixed”, “Fix”, “Closes”, “Closed”, “Close” when commit is merged into main, it will close the issue. It is great way to add visibility into history of project.

Search ❓

At top of each page, there is a search box that lets you search through issues.You can scope results by…

  1. Keyword, such as all issues mentioning sidebar
  2. State, such as all issues mentioning sidebar that are closed.
  3. Assignee, such that all issues mentioning sidebar that were assigned to @klo

Overviews & Reports

Outside issue section, there are 2 other pages that help summarize what’s going on with issues across all of your repositories.

The Issue Dashboard 📋

If you use organizations,each one has its own Issue Dashboard that separates out issue within the organization. It is for broader listing of all your issues across many projects. It can be a great tool. Issue section of dashboard collect issues differently…

  1. All issues in repositories you own and collaborate own
  2. Issues assigned to you
  3. Issues you’ve created

Pulse 🟪

Pulse is snapshot of everything that happened in last repository in the past week(day,past 3 month). It’s a great way to catchup with repositories when you’ve been away and don’t want the granularity notifications offer when watching a repository.

MARKDOWN RULES ☑️

It is easy-to-use syntax for styling all forms of writing on the GitHub platform. It is a way to style text on web. You can control the display of document, formatting words such as bold or italic, adding images, creating lists, etc. I t is regular text with few non-alphabetical character thrown like #, *, >. Places to use Markdown…

  1. Gists
  2. Comments in issues and Pull Requests
  3. Files with .md and .markdown extension

DOCUMENTING PROJECTS 📄

Good Documentation is key to success of any project. Making accessible documentation enables people to learn about a project, making it easy to update ensures that documentation stays relevant. Common ways are README files and WIKIS. Wikis help you present in-depth information about project. Readme’s are quick and simple way for other users to learn more about your work. Formats of Readme are…

Other documentation includes

◾ ◾ ◾