Software Engineering Best Practices: How to document a Pull Request?

“I'm not a great programmer; I'm just a good programmer with great habits.”

― Kent Beck

In collaborative projects, generally, one developer makes a Pull Request and another developer reviews and accepts it. This dynamic and its documentation are important because:

• They help maintain code quality, since reviewers can detect and fix errors before the merge (i.e., before merging the suggestion with the main codebase).
• They can serve as project documentation and be revisited later. If someone in the future needs to work on the code, they will understand the goal of the pull request and why certain code decisions were made.

So, DOCUMENT YOUR PULL REQUEST!

❓ How to write good Pull Request documentation?

Most projects have rules and standards that must be followed to contribute and submit a pull request. This information may be presented in the CONTRIBUTING.md or README.md file.

If the project doesn't have this information, there are general details that your pull request should ideally include. A template is also provided at the end :)

✒️ Pull Request Title

The title of a pull request is the first thing someone will see when looking at the list of changes in a repository. So it should be concise and complete!

It should contain two main items:

• A tag related to the action
• A brief description

Tags are used to indicate what type of change occurred in the code. You can use the same tags as conventional commits:

1. feat: Used when a new feature or functionality is added to the project.
2. fix: Used when a bug is fixed.
3. docs: Changes or additions to documentation.
4. style: Refers to style corrections such as formatting, missing semicolons, etc., that don't affect code logic.
5. refactor: Code changes that neither introduce new features nor fix bugs — may be a restructuring or optimization.
6. perf: Performance improvements to the code.
7. test: When adding missing tests or fixing existing ones.
8. chore: Regular or maintenance changes, such as dependency updates.

Example of a good pull request name:

[feat] add search functionality

🔗 Linking a Pull Request to an Issue

Issues are problems identified in the code (such as a bug or a missing feature, for example).

When creating a pull request, it is expected to resolve an issue (if one exists!). You can find issues in the "Issues" tab of a repository. Each issue has an ID.

There are reserved keywords that link your pull request to an issue by its ID. When used in the pull request description, it makes it possible to see which problem your code is solving — and when the reviewer accepts it, the issue will be automatically closed.

1. close
2. closes
3. closed
4. fix
5. fixes
6. fixed
7. resolve
8. resolves
9. resolved

Example usage:

fixes #1

🎯 Goal and Motivation of the Pull Request

What is the goal of your pull request? Why did you make certain decisions and implement the code that way? What problem is it solving? It's important to provide context so the reviewer doesn't have to look for it elsewhere.

💥 List of Changes and Breaking Changes

What were the main changes made to the code? Do any of the changes deserve special attention because they might break an existing feature (breaking change)?

📷 Screenshots

Especially if your code is related to interfaces, it's a good idea to include a screenshot showing how things look after the changes.

📖 Template

To make your life easier, here is a simple pull request template. Just copy and paste it, adding the important information!

# ✨ Pull Request 💻

## Pull Request details:

Goal, motivation, and description

Fixes #1

## Changes and Breaking changes:

- Add a list of what was changed and whether any change may cause
  issues with existing functionality

## Associated Screenshots:

You can copy and paste a screenshot here

Example usage from Codú:

https://github.com/codu-code/codu/pull/533