| ... | ... | @@ -5,6 +5,7 @@ title: Developer guide |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# Joining the developers of PASE
|
|
|
|
All contributions are welcome. To start coding :
|
|
|
|
- read this developer guide completely for essential information and practices to follow
|
| ... | ... | @@ -85,7 +86,7 @@ Branch naming convention: |
|
|
|
|
|
|
|
# Branching workflow
|
|
|
|
|
|
|
|
This is the process to create a new branch. It is mandatory to first create an issue on Gitlab, create the branch from within the issue, then pull locally.
|
|
|
|
This is the process to create a new branch. It is mandatory to first create an issue on Gitlab, create the branch from within the issue, then pull locally. Please read further for a detailed procedure
|
|
|
|
|
|
|
|
|
|
|
|
|
| ... | ... | @@ -98,7 +99,8 @@ Example issue title : |
|
|
|
|
|
|
|
[feature] Implement algorithm Foo bar
|
|
|
|
|
|
|
|
Select an issue template (feature request or bug report) and fill all fields as clearly and concisely as possible.
|
|
|
|
Select an issue template (feature request or bug report) and fill all fields as clearly and concisely as possible.
|
|
|
|
Some of those fields may not be available to non-members.
|
|
|
|
|
|
|
|
### Assignees
|
|
|
|
Assign the issue to people who should or want to work on it.
|
| ... | ... | @@ -132,17 +134,21 @@ Set the due date for the issue. Useful to organize work and indicate the level o |
|
|
|
### Iteration
|
|
|
|
Assign the issue to the appropriate Iteration cadence (if there is one).
|
|
|
|
|
|
|
|
# Push rules
|
|
|
|
## Creating the Branch and Merge request
|
|
|
|
|
|
|
|
The online repository has rules on the format of commit messages as well as branch names.
|
|
|
|
The creation of a branch marks the beginning of a new feature's development, and the Merge request will be used at the end of the feature's development to include it in the code base.
|
|
|
|
|
|
|
|
## Branch names
|
|
|
|
Branch names should always be created from Issues, and the Gitlab repository settings are such that their suggested name should always match the branch name push rule.
|
|
|
|
When creating a branch, always check that you are branching from the correct source branch (see [Branching strategy : git-flow](#branching-strategy--git-flow))
|
|
|
|
Branches should **always be created from Issues** within the Gitlab interface, and the Gitlab repository settings are such that their suggested name will always match the branch name push rule.
|
|
|
|
To configure the new branch, click on the drop-down arrow on the right of the blue "Create merge request" button.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
When creating a branch, always check that you are branching from the correct source branch (see [Branching strategy : git-flow](#branching-strategy--git-flow)).
|
|
|
|
When the correct source is selected, click on "Create merge request", at the bottom of the drop-down.
|
|
|
|
|
|
|
|
{width=537 height=302}
|
|
|
|
|
|
|
|
The branch name rule in the public repository is set with the following regular expression:
|
|
|
|
The branch name push rule in the public repository is set with the following regular expression:
|
|
|
|
|
|
|
|
`^(main|develop|(\d+)-hotfix-.+|(\d+)-feature-.*|release-v\d+\.\d+\.\d+)$`
|
|
|
|
|
| ... | ... | @@ -155,6 +161,26 @@ Valid branch names: |
|
|
|
- \<issue number\>-feature-\<issue title\> (e.g. : 69-feature-grassim-refactoring, generated from issue #69 )
|
|
|
|
- release-v\<major version\>.\<minor version\>.\<patch version\> (e.g. release-v1.2.4)
|
|
|
|
|
|
|
|
Once the branch and merge request are created, you can pull the branch locally, e.g. :
|
|
|
|
```
|
|
|
|
git fetch
|
|
|
|
git checkout -t <remote>/<branch name>
|
|
|
|
```
|
|
|
|
|
|
|
|
If you are unsure about the `<remote>/<branch name>` combination, you can find it with git:
|
|
|
|
```
|
|
|
|
git branch -a
|
|
|
|
```
|
|
|
|
|
|
|
|
Before starting development, make sure to read the next sections.
|
|
|
|
|
|
|
|
# Push rules
|
|
|
|
|
|
|
|
The online repository has rules on the format of commit messages as well as branch names.
|
|
|
|
|
|
|
|
## Branch name rule
|
|
|
|
See "Creating a branch" section.
|
|
|
|
|
|
|
|
## Commit rule
|
|
|
|
This rule exists to prevent cryptic commit messages, often pushed when in a rush and thus degrading the traceability of the commits in the repository's history.
|
|
|
|
|
| ... | ... | @@ -205,5 +231,34 @@ Merge branch '\<branch name\>' of gitlab.uliege.be:deal-public/branch into branc |
|
|
|
|
|
|
|
Some description.
|
|
|
|
|
|
|
|
# Start coding
|
|
|
|
|
|
|
|
Start developing on your local branch.
|
|
|
|
|
|
|
|
Make your first push with a small, inconsequential commit so you validate that you comply with the push rules (branch name, commit message).
|
|
|
|
|
|
|
|
At the end of the branch development, the merge will occur through a Merge request. This will in time include the result of your work in the `partners-main` branch.
|
|
|
|
|
|
|
|
# Merge requests
|
|
|
|
The Gitlab [documentation on merge requests](https://docs.gitlab.com/user/project/merge_requests/) states that :
|
|
|
|
> A merge request (MR) is a proposal to incorporate changes from a source branch to a target branch.
|
|
|
|
|
|
|
|
If you followed the instructions on this page correctly, you should have created a MR directly related to the issue and branch supporting the new feature.
|
|
|
|
You can consult this MR at anytime to have an overview of all the commits pushed within that MR's scope, as well as all the changes between the latest commit and the branching commit.
|
|
|
|
The MR interface will be used for review by peers, to give feedback and ask questions about the proposed changes.
|
|
|
|
|
|
|
|
Approval by one member of the DEAL lab is currently mandatory.
|
|
|
|
Once an MR is approved, you can prepare to merge it in the target branch (typically, feature branches merge into develop).
|
|
|
|
|
|
|
|
You can :
|
|
|
|
- check Delete source branch
|
|
|
|
- Squash commits (especially if your developments contain many commits, it may be clearer for other users to read a summary of the changes related to the features instead of potentially a great number of commits containing bugs, etc.)
|
|
|
|
- edit commit message for 2 reasons :
|
|
|
|
1. Summarize the changes you propose to merge
|
|
|
|
2. Make sure your commit message complies with the commit message [push rule](#commit-rule)
|
|
|
|
|
|
|
|
|
|
|
|
# Good practices
|
|
|
|
- **NEVER** `git add .` or `git add -A` or `git add -A .` as it can create confusion when going back to a previous commit and hide meaningful changes in a heap of modified or newly created files |
|
|
\ No newline at end of file |
|
|
|
- **NEVER** add "all files" to git's tracked files (i.e. DO NOT use `git add .` or `git add -A` or `git add -A .`).
|
|
|
|
It can create confusion when going back to a previous commit and hide meaningful changes in a heap of modified or newly created files
|
|
|
|
- regularly pull `main` and `develop` branches from remote so you have the latest changes on your computer |
|
|
\ No newline at end of file |
