File: CONTRIBUTING.md

package info (click to toggle)
gap 4r8p6-2
  • links: PTS
  • area: main
  • in suites: stretch
  • size: 33,476 kB
  • ctags: 7,663
  • sloc: ansic: 108,841; xml: 47,807; sh: 3,628; perl: 2,342; makefile: 796; asm: 62; awk: 6
file content (157 lines) | stat: -rw-r--r-- 6,774 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
# Contributing to GAP

We invite everyone to contribute by submitting patches, pull requests, and
bug reports. We would like to make the contributing process as easy as
possible.

## Packages versus contributions to the "core" system

One way of contributing to GAP is to write a GAP package (see
<http://www.gap-system.org/Packages/packages.html>) and send it to us to
consider for redistribution with GAP.  This is appropriate if your
contribution adds a body of functionality for some area of mathematics (or
some coherent batch of system functionality). A package is also appropriate
if you plan to continue to develop your code in the future. You will retain
control of your code and be recorded as author and maintainer of it.

Packages are not an appropriate way to release fixes or extremely small
changes, or to impose your own preferences for, for instance, how things
should be printed.

## Issue reporting and code contributions

* Before you report an issue, or wish to add functionality, please try
  and check to see if there are existing
  [issues](https://github.com/gap-system/gap/issues) or
  [pull requests](https://github.com/gap-system/gap/pulls).
  We do not want you wasting your time duplicating somebody else's work.
* For substantial changes it is also advisable to contact us before
  you start work to discuss your ideas.
* You should be prepared to wait until your pull request or patch
  has been discussed and authorized prior to its inclusion. We might
  also ask for you to adapt your changes to make them suitable for
  inclusion.
* To help increase the chance of your pull request being accepted:
  * Run the tests.
  * Update the documentation, tests, examples, guides, and whatever
    else is affected by your contribution.
  * Use appropriate code formatting for both C and GAP.
* *The Campsite Rule*
  A basic rule when contributing to GAP is the **campsite rule**:
  leave the codebase in better condition than you found it.
  Please clean up any messes that you find, and don't
  leave behind new messes for the next contributor.

## Making Changes

GAP development follows a straightforward branching model. We prefer using
the GitHub infrastructure. If you would like to contribute, but do not want
to create a GitHub account, see below for an alternative.

* Make sure you are familiar with [Git](http://git-scm.com/book)
  * see for example the [Atlassian Git Tutorials](https://www.atlassian.com/git/tutorials/)
    for an excellent introduction to Git.
* Make sure you have a [GitHub account](https://github.com/signup/free).
* Make sure you are familiar with [GAP](http://www.gap-system.org/).
* Fork our [main development repository](https://github.com/gap-system/gap) on github
* Clone your fork to a chosen directory on your local machine using HTTPS:

        $ git clone https://github.com/<your github user name>/gap.git

* This will create a folder called `gap` (in the location where you ran `git
  clone`) containing the source files, folders and the Git repository.  The
  clone automatically sets up a remote alias named `origin` pointing to your
  fork on GitHub, which you can verify with:

        $ git remote -v

* Add `gap-system/gap` as a remote upstream

        $ git remote add upstream https://github.com/gap-system/gap.git

* Ensure your existing clone is up-to-date with current `HEAD` e.g.

        $ git fetch upstream
        $ git merge upstream/master

* Create and checkout onto a topic (or feature) branch on which to base your work.
  * This is typically done from the local `master` branch.
  * For your own sanity, please avoid working on the local `master` branch.
    Instead, create a new branch for your work:

        $ git branch fix/master/my_contrib master
        $ git checkout fix/master/my_contrib

    A shorter way of doing the above is

        $ git checkout -b fix/master/my_contrib master

    which creates the topic branch and checks out that branch immediately after.
* Make commits of logical units.
* Check for unnecessary whitespace with

        $ git diff --check

* Make sure your commit messages are along the lines of:

        Short (50 chars or less) summary of changes

        More detailed explanatory text, if necessary.  Wrap it to about 72
        characters or so.  In some contexts, the first line is treated as the
        subject of an email and the rest of the text as the body.  The blank
        line separating the summary from the body is critical (unless you omit
        the body entirely); tools like rebase can get confused if you run the
        two together.

        Further paragraphs come after blank lines.

        - Bullet points are okay, too

        - Typically a hyphen or asterisk is used for the bullet, preceded by a
          single space, with blank lines in between, but conventions vary here

* Make sure you have added any necessary tests for your changes.
* Run all the tests to assure nothing else was accidentally broken.

        $ make testinstall
        $ make teststandard

* Push your changes to a topic branch in your fork of the repository.

        $ git push origin fix/master/my_contrib

* Go to GitHub and submit a pull request to GAP.

From there you will have to wait on one of the GAP committers to respond to
the request. This response might be an accept or some
changes/improvements/alternatives will be suggested.  We do not guarantee
that all requests will be accepted.

## Making changes without Github account

If you do not want to open a GitHub account you can still clone the GAP
repository like so:

    git clone https://github.com/gap-system/gap.git


Make your changes and commits, create a patch containing the commits you
want to send, and use git's [`send-email` feature](http://git-scm.com/docs/git-send-email)
to email the patch to <gap@gap-system.org>.  You can refer to
[this tutorial](https://burzalodowa.wordpress.com/2013/10/05/how-to-send-patches-with-git-send-email/)
on how to do this.

## Additional Resources

* [GAP Tutorial](http://gap-system.org/Manuals/doc/tut/chap0.html)
* [GAP Manual](http://gap-system.org/Manuals/doc/ref/chap0.html)
* [GAP Homepage](http://www.gap-system.org/)
* [GAP on GitHub: Quickstart](https://github.com/gap-system/gap-git-cheat-sheet/raw/master/gap-git-cheat-sheet.pdf)
* [Atlassian Git Tutorials](https://www.atlassian.com/git/tutorials/)
* [Using Pull Requests](https://help.github.com/articles/using-pull-requests)
* [General GitHub Documentation](https://help.github.com/)

Heavily adapted from the contributing files from the
[Puppet project](https://github.com/puppetlabs/puppet),
[Factory Girl Rails](https://github.com/thoughtbot/factory_girl_rails/blob/master/CONTRIBUTING.md),
and [Idris](https://github.com/idris-lang/Idris-dev).