Jumping into a new project is hard. People have been working on the code base potentially for many years! That’s a lot of technical knowledge to gather before you can start being productive. There’s probably thousands of files, maybe more than one project that drives the application. Where do you begin?
Photo Credit: Rajesh Sundaram
For some reason people think that browsing the source code is still the normal way of learning how a project works. I’m here to say no, that’s not ideal and there are better ways.
The Pull Request
This is the easiest to place to start if you’re using a Git hosting solution like GitHub, GitLab, BitBucket, etc. Projects contain the history of how every change came to be and the discussion around every change in the form of Pull or Merge Requests.
For example, GitLab has recently added some slash commands (think of your slash commands in Slack) to their issue system. I am curious how they implemented this. So let’s go browse their merged merge requests.
GitLab Issue Board
As you can see, all I did was search their merge requests for slash commands and limited the search to merged.
That top merge request looks promising. It’s the oldest and the title of it seems to indicate this is where the feature came in. Let’s check that request out and scroll down to see the changes.
GitLab Merge Request
The merge request will tell you exactly what changed and what was added to implement the feature. This request contains a lot of change so we won’t be going over it, nor is that the point of this article.
In just a few minutes we were able to find when a feature was added, who added the feature, and what changes were needed to implement the feature. This is a bit better than browsing source files looking for something looks like it might be related. It also gives you every bit of information you need if you want to go in and enhance the feature.
Git Log
So we’ve gone over basic searching through pull or merge requests to find out how a feature was implemented. How can we do this same kind of search using git log? git loghas a --grep flag you can use for searching through commit messages.
jaredready@Jareds-MBP gitlab (master)$ git log — grep=”slash command” — reversecommit 0eea8c885743575b0e93a98846b3663e9903aa66Author: Rémy Coutable <remy@rymai.me>Date: Thu Jun 30 17:34:19 2016 +0200
Support slash commands in noteable description and notes
Some important things to note:
— commands are removed from noteable.description / note.note— commands are translated to params so that they are treated as normalparams in noteable Creation services— the logic is not in the models but in the Creation services, which isthe right place for advanced logic that has nothing to do with whatmodels should be responsible of!— UI/JS needs to be updated to handle notes which consist of commandsonly— the `/merge` command is not handled yet
Other improvements:
— Don’t process commands in commit notes and display a flash is note is only commands— Add autocomplete for slash commands— Add description and params to slash command DSL methods— Ensure replying by email with a commands-only note works— Use :subscription_event instead of calling noteable.subscribe— Support :todo_event in IssuableBaseService
Signed-off-by: Rémy Coutable <remy@rymai.me>
If you’ll look back at the pull request, you’ll see this commit is actually the first commit of that pull request. The rest of the log from the git log — grep=”slash command” — reverse command contains most of the rest of those commits.
To view the changes from this commit so you can see how the slash commands were implemented, we can use the git show <sha> command.
Conclusion
I urge you to not blindly flail through the code base to figure out how a project works. Use the pull requests as an easy to read history and discussion of the project. Use the git log when you don’t have access to a pull request. Hopefully this makes jumping into new projects a little easier.