Skip to content

Home

Jump to bottom
Alexander Konovalov edited this page Apr 10, 2020 · 5 revisions

Welcome to the wedderga wiki!

How to write good commit messages

https://chris.beams.io/posts/git-commit/

How to generate test files

Test files named weddergaXX.tst are generated automatically. Do not edit them! Instead, call gap makedoc.g.

How to contribute

Initial Git setup (once per user)

  1. Install Git: we suggest to follow Software Carpentry instructions for your operating system. You can find them at any of the recent workshops teaching Git, for example at https://ccp-codima.github.io/2020-02-20-lancaster/#setup

  2. Set up Git: we suggest to follow instructions from the Software Carpentry lesson on Git at https://swcarpentry.github.io/git-novice/02-setup/index.html. You need to specify your name and email address to sign your commit messages, specify how to handle line endings to avoid mixing Windows and UNIX style line ending in the code, and set up an editor to compose commit messages (we recommend to use nano).

  3. Login into GitHub: create a free GitHub account at https://github.com/join and log in at https://github.com/login

Initial repository setup (once per repository)

  1. Clone this repository: Decide in which directory you will keep the clone of this repository. Navigate to that directory in the terminal, and then call
   git clone https://github.com/gap-packages/wedderga.git

Remark: One of approaches could be to put the clone into ~/.gap/pkg/ directory (On Windows, _gap\pkg in your home directory). This way, it will be loadable by any version of GAP running on your machine, unless you start GAP with -r command line option. Another approach could be to go to the pkg directory your GAP installation, remove the directory with an official Wedderga release, and put a clone there. The latter approach may seem simpler, but your setup will need an upgrade after you install a new GAP release.

  1. Fork this repository: follow instructions at https://help.github.com/en/github/getting-started-with-github/fork-a-repo. We will assume that the URL of your fork will be https://github.com/your-username/wedderga.git, where your-username is the name of your GitHub account.

  2. Configure remote repositories for your local clone: in the terminal, navigate to the directory with the clone of this repository and call git remote -v. You should see the following:

$ git remote -v
origin	https://github.com/gap-packages/wedderga.git (fetch)
origin	https://github.com/gap-packages/wedderga.git (push)

Call git remote add your-username https://github.com/your-username/wedderga.git (replace your-username by your actual GitHub username twice). Now call git remote -v again; you should see an output like this:

$ git remote -v
origin	git@github.com:gap-packages/wedderga.git (fetch)
origin	git@github.com:gap-packages/wedderga.git (push)
your-username	https://github.com/your-username/wedderga.git (fetch)
your-username	https://github.com/your-username/wedderga.git (push)

which means that now your repository "knows" two remotes; the main one having an alias "origin", and your fork, having an alias "your-username" (you can use a different alias, e.g. "myfork" if you wish; an alias coinciding with a username makes more obvious who is the owner of the remote, especially if you collaborate with multiple remotes). See more about remote repositories at https://swcarpentry.github.io/git-novice/07-github/index.html

The steps above are needed only for the initials setup. Upon their completion, you will be ready to propose changes, following the workflow below.

Contributing workflow

  1. Checkout an appropriate branch: this should be the branch to which your will be submitting your modifications. For example, if you are going to work with the master branch, call
git checkout master

If you are going to contribute to a feature branch, for example, the divalg branch on which we work in PR https://github.com/gap-packages/wedderga/pull/58, you need to fetch this branch first:

git fetch origin divalg

and then call

git checkout divalg

to checkout this branch (next time, you can skip git fetch step, as it will be already fetched).

  1. Check that your branch is up to date: pull the latest changes from the remote repository:
git pull
  1. Explore latest changes: You can call explorative commands to check what's the current state of you clone, for example:
  • git branch to indicate the current branch
  • git log to display the history of commits
  • git show to display changes in the latest commit
  1. Create a new branch off the current branch:
git checkout -b feature-name

where feature-name should be replaced by some meaningful and distinguishing name related to your intended changes.

You can call git branch afterwards to see that you have switched to the feature-name branch.

  1. Make and commit changes: use git add and git commit to commit individual files, or git commit -a to commit all modified files at once.

  2. Push feature-name branch with new changes to your fork:

git push your-username

where your-username is an alias for your fork previously set up using git remote.

  1. Submit pull request via GitHub web interface: go to https://github.com/gap-packages/wedderga, then you will see the yellow notification about a recently pushed branch and a green button "Compare & pull request". Click on that button to the the pull request form. Pay attention to the base branch (i.e. the branch which you suggest to modify) - for example, for PR #58 you need to select divalg instead of master. Write the title of the PR and a short description, and click on "Create pull request".

  2. Revising and updating pull requests: you should not merge pull request until automated tests will finish and you will check that it passes the tests and achieves acceptable code coverage standard. If you need to modify pull request, you can make further commits, and push them to your fork with git push your-username. You can also modify the last commit, and then amend it using the following:

git add name-of-amended-file
git commit --amend
git push your-username --force

Any change will automatically update pull request and trigger a new round of CI testing.

Clone this wiki locally