Contribute to a Repository¶

Warning

It is here assumed the statiskit environment has been installed and activated as detailed in the Configure your Computer section.

Note

This section heavily relies on the devops-tools program. For more information concerning the github, travis_ci and appveyor_ci commands, refer to their documentation.

Official repositories of StatisKit are currently hosted on GitHub. In order to contribute to an official repository of StatisKit we recommend to proceed as follows.

Note

In the following <REPOSITORY> denote the official repository name.

1. Fork the repository from the organization account to your personal account. If this repository is already forked on your personal account, you can skip this step. Otherwise, type the following command in your console

github fork <REPOSITORY> --owner=StatisKit

2. Clone the repository from your personal account to your computer. If this repository is already cloned on your computer, you can skip this step. Otherwise, type the following command in your console

github clone <REPOSITORY>


Warning

After this step, it is assumed that your console working directory is the one of the local repository. Two remotes are available for this local repository:

• The upstream remote pointing to the repository located on the organization account.
• The origin remote pointing to the repository located on your personal account.
3. Activate Continuous Integration and Deployment (CI&D) services for the repository located on your personal account. This step is not mandatory but is recommended. To do so, type the following commands in your console

travis_ci init --anaconda-label=main
appveyor_ci init --anaconda-label=main


Warning

To activate CI&D services, you need to have:

1. Retrieve the latest code from the repository located on the organization account and push it together with your modifications to the repository located on your personal account. This step is particularly important if you skipped one of the first two.

To do so, type the following commands in your console

git pull
git push
git pull upstream master
git push


Warning

Before using these commands, it is better to make sure that there are no uncommitted changes nor untracked files on your local repository. To do so, type the following command in your console

git status


If you want to suppress (permanently) all uncommitted changes, type the following command in your console

git reset --hard


Moreover; if you want to suppress (permanently) all untracked files, type the following command in your console

git clean -fd

2. Work on your local repository. To work on a repository, an issue must first have been published.

Warning

Issues must be published on the repository located on the organization account, not on your personal repository.

github issues --browser


To display in your console current open issues, type the following command in your console

github issues


To display in your console current open issues that are assigned to yourself (i.e., that you are currently working on), type the following command in your console

github issues --assigned


In the following, we consider that an issue is identified by its number denoted by <ISSUE>. If this issue corresponds to:

• a bug, the work must typically be situated on a branch named hotfix_<ISSUE> created from the master branch of the repository located on the organization account. Thus, type the following command in your console

github hotfix --issue=<ISSUE>


Yet, if you do not have the necessary permissions to write on the repository located on the organization account, the branch must be created from the master branch of your personal account. To do so, type the following command in your console

github hotfix --issue=<ISSUE> --remote=origin

• an enhancement, the work must typically be situated on a branch named feature_<ISSUE> created from the master branch of the repository located on your personal account. Thus, type the following command in your console

github feature --issue=<ISSUE>


If the enhancement should be assigned to more than one developer (large ones), the branch must be create from the master branch of the organization repository. To do so, type the following command in your console

github feature --issue=<ISSUE> --remote=upstream


Note

If the bug or the feature covers more than one issue, create a new issue referencing all those issues. In all those issues:

• add the Duplicate of #<ISSUE> comment,
• add the duplicate label.

Warning

If the branch name given by the github hotfix or github fixture commands corresponds to a remote branch, the remote will be set to the existing remote branch.

github start hotfix_<ISSUE>


or

github start feature_<ISSUE>


To see all available branches of your local repository, type the following command in your console

git branch


To see all available branches of all repositories, type the following command in your console

git branch -a


An easiest way if you have no concurrent branches is to use the following command line

github start


This command will ensure that you are currently working on the latest branch you edited using these commands.

Warning

If there are untracked files or uncommitted changes on your current local branch, this command will fail.

Similarly, to go back to the local master branch, type the following command

github end


Warning

If there are untracked files or uncommitted changes on your current local branch, this command will fail.

Note

github issue <ISSUE> --browser


github issue --browser


This is particularly helpful if you forgot the meaning of an issue number you were working on.

3. Retrieve the latest code from the repository located on the organization account and push it together with your modifications to the repository located on your personal account.

To do so, type the following commands in your console

git pull
git push
git pull upstream master
git push


Warning

Before using these commands, it is better to make sure that there are no uncommitted changes nor untracked files on your local repository. To do so, type the following command in your console

git status


If you want to suppress (permanently) all uncommitted changes, type the following command in your console

git reset --hard


Moreover; if you want to suppress (permanently) all untracked files, type the following command in your console

git clean -fd

4. Suggest to maintainers to incorporate your modifications into the master branch of the repository located on the organization account. To do so, type the following command in your console

github end --suggest


Warning

If your local branch is at least one commit behind the master branch of the repository located on the organization account or is ahead of the corresponding branch on the repository location on your personal account, this command will fail.