Reprint: Contributing source code to open source projects (take Orchard as an example)

Original address: http://yangw80.blog.163.com/blog/static/247518002201552692516908/

In the era of open source projects, it is not enough to use only open source projects, to participate appropriately in the modification of open source projects, which is of great significance to themselves and others. For example, you are using the 2.0 version of Project A, you have modified 5 places and have not contributed the changes to project A, just for your own use. When the project is updated to version 3.0, you find a lot more interesting features (naturally not including the 5 places you've modified), so you'll have a lot of trouble updating the 3.0 steps. At the same time, do you make 5 changes that have a potential impact on other parts of the project? After the code is submitted, you will be reviewed by Daniel to help you find the problem. This is just an example, I believe the pros and cons of which we can understand.

Now take Microsoft's Open source project Orchard as an example to explain how to participate in code maintenance for the project.

First, the preparatory work

1. Sign up for a GitHub account.
Orchard source is hosted on GitHub, so first, to https://github.com to register an account, and then login.

2. Install and configure the Git client.
The GIT client can be downloaded here: https://windows.github.com/. After the installation is successful, two icons appear on the desktop:

GitHub is a graphical interface, the Git Shell console interface. I don't want to repeat the Git tutorial on the web with the git command line on the console interface, so this article just says one of the simplest steps to contribute to the source code through a graphical interface.

Double-click the GitHub icon to enter the graphical interface. First use launches the Configuration Wizard, enter the username and password you registered on the GitHub website in the "Log in" step, click Log in to log in:

In the Configure step enter your user name and email on the GitHub website, click Continue to continue:

Select one of your own warehouses in the repositories step. Since we have not yet created our own warehouse, point Skip skips:

And then into the empty main interface:

Second, learn some basic knowledge

1. About the Orchard project:
Orchard Project's official website: http://www.orchardproject.net/
Orchard Source of GitHub page: Https://github.com/OrchardCMS/Orchard
The subsequent submission of the source code, are on the GitHub website and the client operation.
After entering the Orchard GitHub page, you can click on the Star button in the upper right corner to collect the items, or to express your liking for the project:

2. About slip (Fork) and branch (Branch)
To make sure that you can modify the project at the same time, everyone can create a branch of the project (fork) and operate on their own branch (fork).
Each branch (Fork) can have a number of branches (Branch) below to hold different states of the project at different times.
Take a look at the following branches of the Orchard Project (Branch):

Orchard Current Latest version is 1.9.1, switch to 1.9.1 branch, in the following list of files can be directly online browsing source code.

3. Branches involved in submitting the code (BRANCH)
When submitting the code, there are two branches to note: 1.9.x and Dev.
Among them, the bug one kind of modification, can submit to 1.9.x branch, the new function kind of modification, can submit to the Dev branch. As the project continues to evolve, the meaning of each branch may be adjusted, as described in the official document: Http://docs.orchardproject.net/Documentation/Contributing-patches.

Third, get a copy of the source can be modified

1. Create a branch (Fork).

Before modifying the source code, first create a copy of your own branch (i.e. a full copy of the source) via the GitHub website:

It's about 10 seconds, and then the system automatically switches to its own branch:

2. Synchronize the branch code locally via the GitHub client.

Open the GitHub client: point to the upper left corner + sign, switch to the Clone tab, and you will find the Orchard slip that was previously forked out. Select, and then click Clone:

Then select the local path to which the source code will be saved, and start the clone operation:

Orchard project documents More, the process is long, need patience wait. Depending on the speed, it takes about more than 10 minutes or even half an hour. After cloning, you will see that the project has 0 changes and 0 unsynced:

At this point, the code has been successfully synchronized to local.

Iv. modification of the source code
As an example, this document submits a Orchard small bug to the 1.9.x branch. As I said earlier, a bug-type modification is a convention on a 1.9.x branch. Switch the default Dev branch to 1.9.x branch:

Open Orchard Source with Visual Studio 2013, open file: orchard/src/orchard.web/modules/orchard.taxonomies/views/fields/ Taxonomyfield.cshtml, found here an @ symbol, delete, and save the file:

(Note: Any modifications must be cautious and debug locally.)
Then switch to the GitHub client, will automatically find a change, check the modified file, the right can display the changes before and after the content, you can check. Fill in the instructions at the bottom of this modification (please describe it in English):

The "commit to 1.9.x" at the bottom of the point commits the changes to the local repository. After that, you will see an item that is not synchronized, point sync, sync the project to the remote repository:

When the synchronization is complete, the status changes to 0 changes,0 unsynced.

Five, the contribution code

Before the operation, just to synchronize the code to the remote warehouse you Fork out, just a branch of the source, and will not affect the original project. Once you have confirmed that the changes are correct, you can send a pull request to the original project and notify the project administrator to merge your code. The steps are as follows:

1. Go to the fork before the project, switch branches to 1.9.x, just the modification is done under this branch. Click on the "Compare, review, create a Pull Request" button on the left:

Subsequent pages will list all changes and check for errors. If that's true, click on the "Create Pull Request" button:

In the next page, fill in the description of this modification, briefly describe your changes in English, and then click on "Create pull request" to make the requests:

After confirming, go to the following page, you can see that the status of the state of your submission is "Open":

The project administrator will discuss your changes with you in the page above. If it does, it will be requested by your merge code and then the state of the commit code modification will change to "merged":

This means that your code has been shared with the world.

At this point, you can see your submission on the Pulse tab on the right side of the GitHub website:

When you download the 1.9.x source code, you will also be included in your submission.

At the same time, your changes in the 1.9.x branch will be synced to the Dev branch after a period of time and become part of the next official version.

Vi. Other contributions

In addition to submitting your code, you can submit bugs or suggestions.

Go to the GitHub website, switch to the Issues tab on the right (exclamation mark icon), click New Issue to submit a fresh question, the process is as simple as a forum post, no longer detailed.

At the same time, you can also browse the problems encountered by others, if you can solve a problem, please fill in the description of the code after the submission of the relevant issue number, for example you will see that there was a description:

Issue #5426 projections don ' t order queries following Position field

This means that the submitted code is resolved with a number #5426 problem.

When you solve the relevant problems and submit the code, remember to go to issues page replies said that they solved the problem, and in the replies to provide pull request number and address, convenient for everyone to view.

You are welcome to become a member of the Open source world.

Original address: http://yangw80.blog.163.com/blog/static/247518002201552692516908/

Reprint: Contributing source code to open source projects (take Orchard as an example)