Contribute to Concrete5 on GitHub::ExchangeCore (2023)

Goal:To learn how to properly make code changes to Concrete5 on github

Requirements:

You must havegit scminstalled on your computer.
In this tutorial we will also be using a free GUI (Graphical User Interface) tool for git calledOriginal tree.
Create an account ongithub.com(It's important to note that github is just a repository for git repositories, git and github are not the same thing. Another very popular git repository is bitbucket, but Concrete5 uses github, so we'll stick with that for now.)

Entry

There are many open source projects available on the internet, but many developers are just learning to develop or have never used a version control system for their source code. I think that for open source projects to work, you need a community that uses the product, reports problems with it and makes it better. The last two can be done very efficiently using github, and we'll focus on how anyone with a bit of programming experience can contribute code.

GitHub configuration

As mentioned above, GitHub is a website for storing git repositories, and you can think of git repositories as something like a mini filesystem tracking software/database, but more on that later. To get started with GitHub, just visit their website (https://github.com/) and open an account. Now that you have an account, it's usually better to create an SSH key (I think the easiest way is to use git gui client or SourceTree) and add it to your github account via account settings. If you choose not to, that's fine, just know that every time you open github (via push, pull, clone, etc) you will be prompted for your user credentials.

Quick overview of Git

Now that we're ready to access the git repository on github, let's take a look at what git actually does for us. You can think of git as a filesystem manager/monitoring database. I'm using the database quite loosely because it's really just a bunch of small files that live on the file system wherever your repository is, but basically they're there to keep track of differences between files, and it uses git binaries to understand the .

Here are some Git/Github terms you might find useful:

Involved- Differences from changes to files, which may be deletion, addition or change of a file and may involve one or more files.
branch- Branches are mostly used to create different workspaces in one repository. A common setup is to use a "Master" branch, which somehow acts as the root upon which all other branches (usually significant branches) are based. For example, let's say you want to start working on some validation helpers, you can create a "Helpers" branch and say halfway through that you are told to work on the database abstraction layer, you can create another branch based on "Master" called "repair cares". You can now separate helper joins from database joins, which is important to ensure proper code validation. After all, you don't want someone reviewing changes to your helper functions affecting changes to your database, and vice versa, if they don't depend on each other.
Unite- Merge is just taking 2 branches and merging the changes. Note that this may mean merging your local origin/develop copy with your origin/develop github copy, as each is truly its own repository, even if they are clones of each other. More about engagementgit-scm.com.
Jaw- Forking is an important aspect of github, not git. Forking allows you to create your own copy of a repository on github. This is important because you can then create "Pull Requests" from the forked repository.
withdrawal request- Requesting the forked repository to merge changes from the forked repository branch into one of the forked repository branches. Anyway, hopefully most of this will make more sense after going through the example, so let's get to it.

Using Github

From now on, I will provide more detailed instructions on how to use Github for the Concrete5.7 repository. The concepts should apply to all git repositories, but I think specific examples are easier to reference, so here...

Make a fork

Go to the page of the repository you want to split. In our case, we go tohttps://github.com/concrete5/concrete5-5.7.0
Click the "Fork" button in the upper right corner of the screen or just add /fork to the end of the URL.
You will then be redirected to the new forked repository. You can tell you're in a forked repository by looking at the top left corner of github.
(Video) concrete5 - What Did We Get in Git & How Would We Do That? 5/17/2013
A quick note about forks: when you forked the 5-5.7.0 concrete repository, you actually made a copy of that git repository at that point. Any changes that occur in the Concrete5/concrete5-5.7.0 branch will need to be manually merged or changed in your forked repository to get the latest changes. There is a decent stack flow article on how to do it with git bash athttp://stackoverflow.com/questions/7244321/how-to-update-github-forked-repository.

Create a local fork clone

Now that we have our own copy (fork) of the concrete 5 repository on github let's move it to our local machine so we can actually manipulate the code with our favorite IDE or text editor (it's also worth noting that many IDEs have git capabilities built into them, which are really beautiful. To do this, we run the Source Tree (link in the requirements at the top of the article). There are some of you who probably won't use Source Tree in favor of git bash, which is great, and you can transfer the concepts here to your own understanding of how it will work. I personally use a combination of the two because git bash merge conflicts just aren't fun.

Create a local "Clone" of the newly split repository by clicking the "Clone/New" button in the upper left corner of the source tree.
Then you need to get the source path/URL for your git repository. This can be done by copying the url from the clone url box on github. Once you've done that, copy it into the SourceTree window that appears and hit the "Clone" button. This will initiate the download of the forked repository to your computer, so it may take a while if you're using a slower internet connection (around 100MB at the time of writing this blog).
Resource tree window:
Once the cloning is complete, you should see the repository in the left navigation area of SourceTree. However, if it's not there, you can add it by opening the cloned repository on your local machine via File -> Open in SourceTree. It should look something like this:
(Video) Using the concrete5 Migration Add-Ons to Upgrade a Legacy Site to Version 5.7

Create a branch

The next step in the process is to create a "Fature branch". When working with repositories, it's always a good idea to split the different tasks you're working on into their own branches (usually called feature branches). This way you can create pull requests for each feature independently of the others.

To do this in SourceTree, right click on the "Branch" navigation and click on "New Branch" (You need to make sure that the "Master" branch is currently set as the current branch before you do this. Check the "master branch.)
Then create a meaningful name for the feature branch. If there is a github issue for a feature/fix you are working on, using "fixes-####" is often a common naming scheme (so if you are working on a fix for issue #123, you would name your branch "fixes-123"). If you're working on something new that doesn't have any problems, keep it short and to the point so you don't confuse it with other industries.
You should now notice that a new branch has been created and checked out as your current working branch. This means that any commit you make will be applied to this new branch, not to "master" or other branches.

Make changes to the repository

We can finally make the changes you want! You can do it any way you want, you can use Notepad, Vi, Sublime, PHPStorm or any other text editor or IDE you can think of. Modify your files and watch the changes appear in the "File Status" -> "Working Copy" section in SourceTree.

Once you've made some changes, they should appear in the "Draft Changes" section. There is also a popup on the right to show what the change is. If your changes do not appear here, .gitignore may exclude the modified file from the repository. This is what it looks like when I modify the file to use the full php tag instead of the short tag.
(Video) Learning concrete5 with Korvin and Myq, Season 1 Episode 3
The next step towards "approval" of these changes would be to "commit" them. In general, don't do anything you haven't tested yet. If it doesn't work then it shouldn't be a commit, this helps prevent crashes if you need to undo a commit. Another tip: the more detail you capture, the better. For example, if you want to make changes to a file and then format the entire file to psr-2 standards, you must do so in two separate sessions. This makes it easier to see in the pull request what you actually changed instead of what you probably did with autoformatting.
Anyway, to commit changes to SourceTree, you usually first upload all the files you want to apply, select the files from "Change Working Copy" and click the up arrow to "deploy" the changes.
Once you've made the changes you want to apply to your home area, simply click the "Commit" button in the top left corner of SourceTree.
And now you can create a [hopefully] sensible commit message. This post gives a quick overview of what you changed in this commit and helps others to easily decipher what you did and whether it might affect their actions without having to go through all the code you just changed. When you commit, you have the option to "push" that commit to your forked repository. Assuming you've tested and don't need to remove this commit, you can safely check that box that says "Submit commit immediately to [Origin]".
Congratulations, you just moved your commit to your forked repository. You can see where each commit is in SourceTree by clicking on "Branch" again and selecting the branch you want to view.
(Video) Live Coding - Concrete5 8.5.1 Docker Install

withdrawal request

Back on github, our web interface has been updated with our new branch. Here we go to take a look at it and send our pull request back to the country (also known as Concrete5/Concrete5-5.7.0).

Go back to your forked github.com repository (should look something like thishttps://github.com/EC-Joe/concrete5-5.7.0)
From there, select the "Branches" tab.
Here you will find a list of branches that can be found in the fork, as well as those that have been pushed from the main repository. But what we want to do is create a pull request for our new feature.
Finally, we can initiate a pull request by clicking a nice shiny button. If you do this, hopefully you're pretty sure your code is production-worthy and you've tested it yourself. You'll also find a full summary of all the changes on this page if you want to review them.
Once a pull request is created, it generates a pull request/issue number in the Concrete5/Concrete5-5.7.0 repository.
If you make changes to the branch you're creating a pull request for, they'll be automatically added to the pull request. That is, if you want to work on a different issue, create a new branch, but if someone can comment on your pull requests and you realize you need to add something, you can certainly do so.

Delete branch

When your pull request is merged or closed and no longer needed (until merged), you can delete the branch. This can be done by going to the pull request and there is usually an option to delete a branch at the bottom. This can also be done from the fork side. The last place you should remove it is a local copy of your fork. This is easily done by right-clicking on a branch in SourceTree and clicking "Delete".

(Video) concrete5 Town Hall

Here's what it looks like:

I hope this helps some of you to start using git/github and contribute to open source projects. If they're worth it, they're great tools to use not only for open source, but also at home. There are many benefits to using these tools in team environments, but even if you're working with one person, being able to review the changes you've made can often be worth the little extra time it takes to maintain your repository.