rockmanr / learning-github Goto Github PK
View Code? Open in Web Editor NEWGitHub best practices
Home Page: https://lab.github.com/courses/moving-your-project-to-github
License: MIT License
GitHub best practices
Home Page: https://lab.github.com/courses/moving-your-project-to-github
License: MIT License
Part of what makes working on GitHub so effective is how easy it is to collaborate. If you want to give others the permission to work in your repository, you can add them as collaborators.
Whether your repository is public or private, inviting someone as a collaborator will give them push access to your repository. That means that they'll be able to make changes to the code. Depending on whether or not you have protected branches enabled, they may even be able to change the history on the master
branch! Before inviting collaborators, make sure they are people you trust with your code.
Your repository is public but there's no License. Licenses are vital in public repositories, because they set the rules for how others are allowed to use, change, and contribute to your project.
Access the Community profile pane
Click the Add button on the License row.
Select a license from the left side of the screen and review the license you selected.
Add information to the displayed fields and click the Review and submit button.
With your file displayed, scroll down and click the Propose new file button.
This is adding your new file to a new branch that GitHub created for you.
With the Open a pull request screen displayed, click the Create pull request button.
If you are ready to merge (or apply) your file to the project click the Merge pull request button. If you want to share this change to your repository with someone, share the URL for this pull request or @ mention them in the comment section.
After clicking Merge pull request, click Confirm merge.
Once the merge is complete (it should happen really quickly) delete your branch by clicking Delete branch.
Your project doesn't have a README.md
file. A README.md
file is useful for telling other people why your project is useful, what they can do with your project, how they can use it, and more importantly, how they can contribute to your project.
A README
is often the first item a visitor will see when visiting your repository. README
files typically include information on:
Access the Community profile pane
Click the Add button on the README row.
Edit the new README file to describe your projects, using the bullet points listed above ☝️
After editing the README file, scroll down and click the Commit new file button.
This is committing your README file directly to
master
. Normally, you would create a pull request when making changes to your projects, but README files are very important on GitHub.
In general, there are two types of files: text files and binary files.
Text files, like most code files, are easily tracked with Git 📖 and are very lightweight.
However, binary files like spreadsheets, presentations with slides, and videos don't work well with Git. If your repository already has some of these files, it's best to have a plan in place before you enable Git version control.
You could choose to remove the binary files, or use another tool like git-lfs (Git Large File Storage). We won't get into detail on how to set up git-lfs in this course, but we will talk about .gitignore
files next, which are key to protecting your code from becoming bloated with binaries.
.gitignore
As mentioned above, there are files you won't want to store in Git. In addition to avoiding binaries, you will also want to keep build artifacts out of your version controlled code. As we convert your project to a Git repository, it should only include the source code necessary to build or compile your project.
To do this, you will create a file in your current project named .gitignore
. When you switch over, Git will use the .gitignore
to determine which files and directories should not be tracked under version control.
A .gitignore
file should be committed into your repository in order to share the ignore rules with any other users that interact with the repository.
Since the files to be ignored are dependent on the language you are using, the open source community has contributed some great templates for .gitignore
files in the github/gitignore
repository.
.gitignore
file. Use a template or create your own.When you are finished, close this issue. I will open a new issue with the next steps. 🎉
🤖 I'm waiting for you to close this issue before moving on.
GitHub Pages is a powerful tool that creates a static web page for GitHub repositories. GitHub Pages looks for an index.html
or index.md
file, but will also use a README.md
file as the home page for the web page.
You can choose to have GitHub Pages look at the master
branch, the gh-pages
branch, or the /docs
directory of the master
branch.
/docs/index.html
file in this repository./docs
.Congratulations @RockmanR, you've completed the core section of this course! 🎉
Before I say good-bye, I want to recap all the tasks you've accomplished. You:
Choose your own adventure! There are some issues already opened in this repository to help you craft this repository's important files, including these:
There's so much more you can do with GitHub, and you have a solid start. Now...what will you learn next?
In your repository, you will see a Settings tab on the right-hand side of the navigation, after Code, Issues, Pull Requests, and other categories. I've opened a milestone to track each of the settings issues.
Repositories can be "owned" by individual user accounts or by organization accounts. If this repository is currently under your own user account but you'd like it to be owned by your organization, don't worry. You can change repository ownership.
Repositories can also be private or public.
A private repository can only be seen by those who are collaborators, administrators, or owners. Permission has to be explicitly granted.
A public repository has code, issues, and pull requests that can be seen by anyone on the internet. Public repositories should always have licenses, so it's clear if others are able to use the project or code in any way. Just because a repository is public doesn't mean that anyone can make changes, though - only collaborators, administrators, or owners can do that.
If you want to give others permission to edit the code in your repository, you will need to add them as collaborators. In the Settings tab of your repository, find the Collaborators tab on the left navigation. Then, you can invite others to your repository.
Protected branches ensure that collaborators on your repository cannot make irrevocable changes to branches. These branches can also be protected by requiring pull requests to have at least one approved review before they can be merged.
If you want to know more about protected branches, check out this documentation.
Integrations are tools and services that connect with GitHub to complement and extend your workflow.
Integrations can be GitHub Apps, OAuth Apps, or anything that utilizes GitHub APIs or webhooks. For more information, see "About integrations" in the GitHub Developer documentation.
You can find an integration to install or publish your own integration in GitHub Marketplace and Works with GitHub.
When you're done, close this issue. I'll open new issues in this repository with your next instructions.
There are many services that integrate with GitHub. These integrations provide specialized solutions to take your software and workflow to the next level.
You can search for and browse integrations in GitHub's Marketplace, and on this "Works with" site.
You might have some integrations set up to sync with your project on another platform, or maybe you are integrating manually. Go ahead and connect these now, and then close this issue when you're done.
Right now, your repository is set to public.
You can change the visibility of a repository to Private 📖 or Public at any time, but there are some things you should know.
If your repository is private, then the only people who can see your code are the collaborators 📖 that you've invited.
Private repositories also aren't free. The price depends on how many collaborators have access to any given repository, but the base price is $7 per month for unlimited private personal repositories.
You might want this repository to be private if it has sensitive information, or depending on the software's license.
In public repositories, anybody can see your code. All of the millions of open source repositories on GitHub are public, too!
Licenses, code of conduct, other files become even more important when the world can interact with you and your code. There are many benefits to this, but it's also a large responsibility. Keep in mind that once a repository is public and open source, there are certain implications about keeping it public, depending on the license chosen.
It's important to note that public does not equal open source! The license associated with code determines whether or not it is open source.
Your repository has no Code of Conduct.
Having a Code of Conduct is really important, especially for public repositories. Instead of re-writing the wheel, I want to point you to some of the best instructions around.
Access the Community profile pane
Click the Add button on the Code of Conduct row.
Select a Code of Conduct from the left side of the screen and review the Code of Conduct you selected.
Add information to the displayed fields then click the Review and submit button.
With your file displayed, scroll down and click the Commit new file button.
This is adding your new file to a new branch that GitHub created for you.
With the Open a pull request screen displayed, click the Create pull request button.
If you are ready to merge (or apply) your file to the project click the Merge pull request button. If you want to share this change to your repository with someone, share the URL for this pull request or @ mention them in the comment section.
After clicking Merge pull request, click Confirm merge.
Once the merge is complete (it should happen really quickly) delete your branch by clicking Delete branch.
You have a few options when moving your project to GitHub. This course will expose you to these options, help you choose a path, and then guide you down the path you have selected.
I know some people like to get straight to the point while others like more information. For those who like more information, be sure to check out the drop-downs like this one ⬇️
You may be wondering what this GitHub thing is all about and why you should use it. If this sounds like you, here are a few reasons to make GitHub your project's new home:
To give you the best information, I need to know a little about your project. In the next activity, you will apply a label to this issue to help me provide the most applicable information to help you move a project to GitHub.
For this exercise, use the following table to determine which label to apply to this issue.
If your project is ... | Add the label |
---|---|
On your local machine | local |
On a different website that includes version control | migration |
On another website without version control (e.g. CodePen) | other |
For a printable version of the steps in this course, check out the Quick Reference Guide.
After you have added the label, I will add a new comment to this issue with next steps.
Sometimes I respond too fast for the page to update! If you perform an expected action and don't see a response from me, wait a few seconds and refresh the page for your next steps.
A contributing guide provides important information to those who may be interested in helping you with your project. Without a contributing guide, they might not know what you need help with, how they can get started, or how you like to communicate.
Providing the baseline expectations for a contribution to your project makes it much easier for a new user to contribute to the growth and development of your project. Identifying the processes that you expect to be followed when creating contributions to your project helps reduce the hesitation a new contributor might feel when adding a new contribution because what you are looking for in a contribution is well laid out. The contributing guide is helpful for veteran contributors as well, as it provides a reference point for their review if they are contribting to an area of the project they hadn't previously worked with.
Access the Community profile pane
Click the Add button on the Contributing row
Modify your new file with contributing guidelines for your project, for ideas on what should be included in a contributing guidelines file, read this stellar documentation
After editing the CONTRIBUTING.md
file, scroll down and click the Commit new file button.
This is committing your
CONTRIBUTING.md
file directly tomaster
.
Describe the bug
A clear and concise description of what the bug is.
To Reproduce
Steps to reproduce the behavior:
Expected behavior
A clear and concise description of what you expected to happen.
Screenshots
If applicable, add screenshots to help explain your problem.
Desktop (please complete the following information):
Smartphone (please complete the following information):
Additional context
Add any other context about the problem here.
When you add an issue template and pull request template to your repository, project contributors will automatically see the template's contents in the issue or pull request body. Templates customize and standardize the information you'd like included when contributors open issues. This information can guide contributors to include the information that allows enhancement or bug reports to be reviewed quickly and identify the information that a reviewer would need to succintly review a new pull request.
In Open Source projects, these templates make it very easy for a new contributor to your project to create a bug report, suggest a new enhancement, or potentially contribute a change. By identifying what information the new contributor should provide when creating a new issue or pull request, veteran contributors to the project can easily review and move forward with reported bugs, new enhancements, or contributed pull requests.
Access the Community profile pane
On the Issue or pull request template row, select the Add drop down and select Issue template or Pull request template
Edit the new template file to identify how you want issues or pull requests submitted to your project, for suggestions on what should be included in a template file, read this
Afer editing the template file, scroll down and click the Commit new file button
This is committing your template file directly to
master
.
After using the Community profile pane to create a template file, the option to create the other template file isn't displayed. To create the other template file, perform the following steps:
- Issue templates are named: `ISSUE_TEMPLATE.md`
- Pull Request templates are named: `PULL_REQUEST_TEMPLATE.md`
> This is committing your template file directly to `master`.
When you look in the Settings tab of your repository, you'll see Branches on the left side. Here, you can choose to enable something called Protected Branches.
Protected branches ensure that collaborators on your repository cannot make irrevocable changes to branches. These branches can also be protected by requiring pull requests to have at least one approved review before they can be merged.
You might want to use protected branches if you're working on a team, you have CI tests enabled, or in any case where you want to be sure that the code that gets merged into the master
branch meets a certain set of requirements.
If you'd like to enable protected branches, go ahead and do so now, and then close this issue.
Not sure what settings to enable? Check out this article that goes into more detail about the settings for protected branches.
Having a project already stored locally enables you to move it to GitHub rather quickly. The following activity provides instructions to move your local project to GitHub using various tools. Select the tool you are most comfortable with and get importing 😄.
git init
to initialize the directory as a Git repository.git remote add origin https://github.com/RockmanR/github-move.git
git add .
git commit -m "initializing repository"
git push -u origin master
to push the files you have locally to the remote on GitHub. (You may be asked to log in.)File > Add a Local Repository
, and then navigating to your local repository.Repository > Repository Settings...
and pasting the URL from your repository on GitHub into the "Primary remote repository (origin)" field. Click Save.git remote add origin https://github.com/RockmanR/github-move.git
git remote add origin https://github.com/RockmanR/github-move.git
🤖 Once you push your project to GitHub, I'll provide the next steps in your journey.
Releases are GitHub's way of packaging and providing software to your users. You can think of it as a replacement to using downloads to provide software.
With Releases, you can provide links to binary files, as well as release notes describing your changes.
At their core, Releases are based on Git tags. Tags mark a specific point in the history of your project, so they're a great way to indicate a Release. Releases are ordered by a tag's date in the following way:
If it's an annotated tag, the tag object's date is used.
If it's a lightweight tag, then the commit object's date is used.
On GitHub, navigate to the main page of the repository.
Under your repository name, click Releases.
Click Draft a new release.
Type a version number for your release. Versions are based on Git tags. We recommend naming tags that fit within semantic versioning.
Select a branch that contains the project you want to release. Usually, you'll want to release against your master branch, unless you're releasing beta software.
Type a title and description that describes your release.
If you'd like to include binary files along with your release, such as compiled programs, drag and drop or select files manually in the binaries box.
If the release is unstable, select This is a pre-release to notify users that it's not ready for production.
If you're ready to publicize your release, click Publish release. Otherwise, click Save draft to work on it later.
You can create releases from the GitHub user interface. Read this detailed documentation when you're ready to implement releases.
Your repository has no description! Let's add one.
Public repositories on GitHub have a Community score. This score is based on the documentation, and how easy it would be for new users to help out and contribute to your project.
Your score is currently 0 and can be seen here.
I've opened up issues for each one of the items that you should take action on, and started a milestone to help you keep track of them.
To continue with best practices for moving to GitHub, close this issue. Don't worry, the milestone will remain open so you can return to it later.
🤖 I'm waiting for you to close this issue before moving on.
no comment
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.