Skip to content

Commit ea6fe94

Browse files
lsegallsegal
committed
Add contributing guide, CoC
1 parent 2ea5ebb commit ea6fe94

File tree

2 files changed

+155
-0
lines changed

2 files changed

+155
-0
lines changed

‎CODE_OF_CONDUCT.md

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
This document provides community guidelines for a safe, respectful, productive,
2+
and collaborative place for any person who is willing to contribute to the YARD
3+
project. It applies to all “collaborative space”, which is defined as community
4+
communications channels (such as mailing lists, submitted patches, commit
5+
comments, etc.).
6+
7+
* Participants will be tolerant of opposing views.
8+
9+
* Participants must ensure that their language and actions are free of personal
10+
attacks and disparaging personal remarks.
11+
12+
* When interpreting the words and actions of others, participants should always
13+
assume good intentions.
14+
15+
* Behaviour which can be reasonably considered harassment will not be tolerated.

‎CONTRIBUTING.md

+140
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
# Contributing Guide
2+
3+
## Help YARD Help You!
4+
5+
**YARD thrives off of the contributions of its users**. This project will gladly
6+
review pull requests and issues. This document outlines how to maximize
7+
the chance of a reported issue being resolved or pull request being accepted.
8+
9+
## Code of Conduct
10+
11+
**All reported issues, pull requests, communication, and code related to YARD**
12+
**must follow the [Code of Conduct][code] or they will be moderated immediately**.
13+
Please take time to familiarize yourself with the Code of Conduct before
14+
you get started. Fundamentally, **you are expected to behave with respect** to all
15+
other users.
16+
17+
## Filing a Bug Report
18+
19+
**You can submit bug reports on our [GitHub issue tracker][issues]**.
20+
21+
If you believe you have found a bug, please include a few things in your report:
22+
23+
1. **A minimal reproduction of the issue**. Providing a huge blob of code is
24+
better than nothing, but providing the shortest possible set of instructions
25+
is even better. Take out any instructions or code that, when removed, have
26+
no effect on the problematic behavior. The easier your bug is to triage and
27+
diagnose, the higher up in the priority list it will go. We can do this stuff,
28+
but limited time means this may not happen immediately. Make your bug report
29+
extremely accessible and you will almost guarantee a quick fix.
30+
31+
2. **Your environment and relevant versions**. Please include your Ruby,
32+
YARD, and system versions (including OS) when reporting a bug. This
33+
makes it easier to diagnose problems. If the issue or stack trace
34+
includes another library, consider also listing any dependencies
35+
that may be affecting the issue. This is where a minimal reproduction
36+
case helps a lot.
37+
38+
3. **Your expected result**. Tell us what you think should happen. This
39+
helps us to understand the context of your problem. Many complex features
40+
can contain ambiguous usage, and your use case may differ from the
41+
intended one. If we know your expectations, we can more easily determine
42+
if the behavior is intentional or not.
43+
44+
Finally, please **DO NOT** submit a report that states a feature simply
45+
*"does not work"* without any additional information in the report. Consider
46+
the issue from the maintainer's perspective: in order to fix your bug, we
47+
need to drill down to the broken line of code, and in order to do this,
48+
we must be able to reproduce the issue on our end to find that line of
49+
code. The easier we can do this, the quicker your bug gets fixed. Help
50+
us help you by providing as much information as you possibly can. We may
51+
not have the tools or environment to properly diagnose your issue, so
52+
your help may be required to debug the issue.
53+
54+
Also **consider opening a pull request** to fix the issue yourself if you can.
55+
This will likely speed up the fix time significantly. See below for
56+
information on how to do this.
57+
58+
## Asking a Question
59+
60+
**Questions are accepted on [GitHub issues][issues], but consider signing up**
61+
**for the [YARD mailing list][ml]** and asking it there so that we can organize
62+
issues appropriately. You can also hop onto IRC (irc.freenode.net / #yard)
63+
for quick questions.
64+
65+
## Asking for a Feature
66+
67+
**YARD does not currently accept feature requests filed as GitHub issues**. If
68+
you are looking to have a feature implemented into YARD, consider doing this
69+
yourself and [submitting a pull request][pr] (PR) with your work. If the work
70+
required is involved, consider starting a discussion on the [mailing list][ml]
71+
or opening an issue to ask a question; we will be happy to have a conversation
72+
and let you know if the feature would be considered. They usually are, but
73+
it might be prudent to ask first!
74+
75+
Please do not fret if your feature request gets closed immediately. We do this
76+
to keep our issue tracker clean. **Closing an issue does not mean it would not**
77+
**be accepted as a pull request**. If the feature would not be accepted as a
78+
PR, this will be communicated in the closed issue.
79+
80+
## Making a Change via Pull Request
81+
82+
**You can also submit pull requests on our [GitHub issue tracker][issues]**.
83+
84+
If you've been working on a patch or feature that you want in YARD, here are
85+
some tips to ensure the quickest turnaround time on getting it merged in:
86+
87+
1. **Keep your changes small**. If your feature is large, consider splitting
88+
it up into smaller portions and submit pull requests for each component
89+
individually. Feel free to describe this in your first PR or on the
90+
mailing list, but note that it will be much easier to review changes
91+
if they affect smaller portions of code at a time.
92+
93+
2. **Keep commits brief and clean**: YARD uses Git and tries to maintain a
94+
clean repository. Please ensure that you use [commit conventions][commit]
95+
to make things nice and neat both in the description and commit history.
96+
Specifically, consider squashing commits if you have partial or complete
97+
reverts of code. Each commit should provide an atomic change that moves
98+
the project forwards, not back. Any changes that only fix other parts of
99+
your PR should be hidden from the commit history.
100+
101+
3. **Follow our coding conventions**. YARD uses typical Ruby source formatting,
102+
though it occasionally has minor differences with other projects you may
103+
have seen. Please look through a few files (at least the file you are
104+
editing) to ensure that you are consistent in the formatting your PR is
105+
using.
106+
107+
4. **Make sure you have tests**. Not all changes require tests, but if your
108+
changes involve code, you should consider adding at least one new test
109+
case for your change (and ideally a couple of tests). This will add
110+
confidence when reviewing and will make accepting the change much easier.
111+
112+
5. **Make sure ALL the tests pass**. YARD has a fairly large suite of tests.
113+
Please make sure you can run all of the tests (`bundle exec rake`) prior
114+
to submitting your PR. Please also remember that YARD supports a number
115+
of environments, including OS X, Linux, Windows, and a number of older
116+
Ruby versions (1.8+), so if you can test under these environments, that
117+
helps (but is not required). At the very least, be aware of this fact
118+
when submitting code.
119+
120+
If your change is large, consider starting a discussion on the [mailing list][ml]
121+
or opening an issue to ask a question; we will be happy to have a conversation
122+
and let you know if the feature would be considered. They usually are, but
123+
it might be prudent to ask first!
124+
125+
## Maintainers
126+
127+
**Interested in helping to maintain YARD? Email [lsegal@soen.ca][mail]** for more
128+
information. Offering to be a project maintainer is an important contribution
129+
to open source software, and your work will be highly valued in the community.
130+
If you have been a contributor, consider being a member of the core team to
131+
help handle day-to-day operations, such as releases, bug fixes, and triage.
132+
You can do some of this as a non-maintainer too, but if you like this project,
133+
we can always use more hands on deck!
134+
135+
[code]: https://github.com/lsegal/yard/blob/master/CODE_OF_CONDUCT.md
136+
[issues]: http://github.com/lsegal/yard/issues
137+
[commit]: http://chris.beams.io/posts/git-commit/
138+
[pr]: https://help.github.com/articles/using-pull-requests/
139+
[ml]: https://groups.google.com/forum/#!forum/yardoc
140+
[mail]: mailto:lsegal@soen.ca

0 commit comments

Comments
 (0)