Skip to content

Commit 953764d

Browse files
tarsiustarsius
committed
Add contribution and support guidelines
1 parent aef11e4 commit 953764d

File tree

5 files changed

+136
-0
lines changed

5 files changed

+136
-0
lines changed

‎.github/CONTRIBUTING.md

+53
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
Asking for help
2+
===============
3+
4+
To ask for help please use the **Discussions** feature. To open
5+
a new discussion, click [here][new] and then click on <kbd>Select
6+
Category</kbd>, most likely to select the **Q&A** category.
7+
8+
Alternatively you can ask for help on the Emacs [StackExchange][se]
9+
site (using the `forge` tag) or on the Emacs [subreddit].
10+
11+
Reporting issues and suggesting features
12+
========================================
13+
14+
To report bugs and suggest new feature use the [issue tracker][issues].
15+
16+
Code contributions
17+
==================
18+
19+
If you have some code which you would like to be merged, then open a
20+
[pull request][pulls]. Please create atomic commits with descriptive
21+
commit messages and use a dedicated feature branch (`b s` might help
22+
with the latter).
23+
24+
Documentation contributions
25+
===========================
26+
27+
Improving the documentation is always a good way to get started
28+
contributing to some project.
29+
30+
In the case of Forge this is somewhat complicated by the fact that
31+
we use some custom extensions. Some meta documentation can be found
32+
[here][metadocs].
33+
34+
TL;DR — Edit `forge.org`. Do not edit `forge.texi`. And don't touch
35+
the version numbers. The maintainers will then update `forge.texi`
36+
and the version numbers in `forge.org` and amend those changes to your
37+
commit.
38+
39+
Donations
40+
=========
41+
42+
Please also consider to contribute by making a
43+
[monetary donation][donations].
44+
45+
46+
[discussions]: https://github.com/magit/forge/discussions
47+
[donations]: https://magit.vc/donate/
48+
[issues]: https://github.com/magit/forge/issues
49+
[metadocs]: https://github.com/magit/magit/wiki/Documentation-tools-and-conventions
50+
[new]: https://github.com/magit/forge/discussions/new
51+
[pulls]: https://github.com/magit/forge/pulls
52+
[se]: https://emacs.stackexchange.com
53+
[subreddit]: https://www.reddit.com/r/emacs

‎.github/ISSUE_TEMPLATE/bug_report.md

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
title:
3+
name: Bug report
4+
about: Report a defect.
5+
---
6+
7+
Please explain
8+
(1) what behavior you expected
9+
(2) what behavior you observed
10+
(3) and how we can reproduce the issue.
11+
12+
You don't have to quote the above lines to do that.
13+
14+
Please include a backtrace in your report. In most cases doing:
15+
16+
M-x toggle-debug-on-error RET
17+
18+
and then going through the steps again should result in a backtrace.
19+
20+
---- now delete this line and everything above ----

‎.github/ISSUE_TEMPLATE/config.yml

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: "SUPPORT ☛ The Discussions feature of this repository"
4+
url: https://github.com/magit/forge/discussions
5+
about: Please search, ask and answer questions here.
6+
- name: "SUPPORT ☛ Emacs StackExchange"
7+
url: https://emacs.stackexchange.com/questions/tagged/forge
8+
about: Another place to search, ask and answer questions.
9+
- name: "SUPPORT ☛ Emacs Reddit"
10+
url: https://www.reddit.com/r/emacs
11+
about: Another place to search, ask and answer questions.
12+
- name: "Forge FAQ"
13+
url: https://magit.vc/manual/forge/FAQ.html
14+
about: It might be that many others had the same question.
15+
- name: "Forge Manual"
16+
url: https://magit.vc/manual/forge/#Top
17+
about: The fine manual may also be of use.

‎.github/ISSUE_TEMPLATE/feature_request.md

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
title:
3+
name: Feature request
4+
about: Suggest a new feature. ⚠ PLEASE DO NOT USE THIS FOR SUPPORT REQUESTS. ⚠
5+
---
6+
7+
Before you ask for a new feature to be added to Forge or for an existing feature to be improved, please make sure that what are asking for does not already exist by consulting the documentation [1].
8+
9+
Then describe the feature you would like to see in Forge and why it would be useful to you. You might also want to describe any alternative solutions or features you've considered.
10+
11+
[1]: https://magit.vc/manual/forge/#Top
12+
13+
---- now delete this line and everything above ----

‎.github/PULL_REQUEST_TEMPLATE

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
=================================================================
2+
Use a dedicated feature branch
3+
=================================================================
4+
5+
Please use a dedicated feature branch for your feature request, instead of asking us to merge "your-fork/master" into the "origin/master". The use of dedicated branches makes it much more convenient to deal with pull-requests, especially when using Magit to do so.
6+
7+
If you were about to open a pull-request asking us to merge your version of "master", then see [1] for instructions on how to quickly fix that and some information on why we ask you to do so.
8+
9+
Additionally we ask you to allow us to push to the branch you want us to merge. We might want to push additional commits and/or make minor changes. Please make sure the box next to "Allow edits from maintainers" is checked before creating the pull-request.
10+
11+
[1]: https://github.com/magit/magit/wiki/Dedicated-pull-request-branches
12+
13+
=================================================================
14+
Do NOT use Github to edit files and create commit messages
15+
=================================================================
16+
17+
Unless you are aware of all the pitfalls and take great care to avoid them, the use of Github results in many small defects, including but not limited to trailing whitespace, commit messages containing overlong lines and no newline at the very end, and "GitHub <[email protected]>" being used as the committer. The last one cannot even be avoided, which I consider as an affront.
18+
19+
Github is an insufficient interface for editing files and creating commits. Please don't do it when contributing to Magit.
20+
21+
=================================================================
22+
What you should write here
23+
=================================================================
24+
25+
Please summarize the changes made in the commits. Explain why you are making these changes, not just what changes you are making. This also applies to the commit messages.
26+
27+
=================================================================
28+
How to update the manual
29+
=================================================================
30+
31+
If you make changes to the manual, then edit only "forge.org". Do not manually edit "forge.texi". The latter has to be generated from the former. If you want to do that yourself, then follow the instructions at [2]. Otherwise a maintainer will do it and amend that to your commit.
32+
33+
[2]: https://github.com/magit/magit/wiki/Documentation-tools-and-conventions

0 commit comments

Comments
 (0)