|
1 | | -# Contributing to Rubberduck |
| 1 | + |
2 | 2 |
|
3 | | -Thank you very much for taking the time to contribute! |
| 3 | +Thank you for your interest in contributing to improve Rubberduck! |
4 | 4 |
|
5 | | -The following is a set of guidelines and links to helpful resources to get you started. |
| 5 | +Below should be everything you need to know to get started with contributing to this project. |
6 | 6 |
|
7 | | -## Code of Conduct |
| 7 | +--- |
8 | 8 |
|
9 | | -Rubberduck as of now has no formalized Code of Conduct. |
10 | | -Yet the following guidelines apply in no particular order: |
| 9 | +## GitHub |
11 | 10 |
|
12 | | -- Apply common sense?! |
13 | | -- Show and deserve respect |
14 | | -- Be nice |
15 | | -- We don't bite :) |
16 | | -- Assume people's best intentions unless proven otherwise |
| 11 | +[Get started with GitHub](https://docs.github.com/en/github/getting-started-with-github) first, star ⭐ us if you haven't already (it helps boosting the project's visibility on the GitHub platform!), and you'll hit the ground running in no time. |
17 | 12 |
|
18 | | -## How can I contribute? |
| 13 | +## Non-Code Contributions |
19 | 14 |
|
20 | | -### Bug Reports |
| 15 | +Don't know any C#? No problem, there is still plenty you can do to help! |
21 | 16 |
|
22 | | -The development team is always happy to hear about bugs. Reported bugs and other issues are opportunities to make Rubberduck even better. |
| 17 | +### Issues |
23 | 18 |
|
24 | | -Before you report your bug, please check the [GitHub Issues](https://github.com/rubberduck-vba/Rubberduck/issues). |
25 | | -The team spends quite some time to label the issues nicely so that you can find already known problems. |
| 19 | +This project uses the GitHub issue tracker to document ideas and suggest enhancements, as well as bugs. Because this creates _lots_ of issues, we take the time to carefully label each one, to facilitate searching and browsing. |
26 | 20 |
|
27 | | -To enable the fastest response possible, please include the following information in your Bug report wherever applicable: |
| 21 | +Please review the existing open [](https://github.com/rubberduck-vba/Rubberduck/issues?q=is%3Aissue+is%3Aopen+label%3Abug) issues (search filter `is:issue is:open label:bug`) to avoid duplicating a known issue. |
| 22 | + - 👍 upvote existing issues and ideas you'd wish were fixed or implemented. |
| 23 | + - 💬 share your feedback and ideas, even (especially!) if it's "just a small thing". |
| 24 | + - ✔️ submitting a bug? Please provide _and test_ clear steps to reproduce the problem, upload screenshots and/or include the logged exception stack trace(s), as applicable: the quicker we can track down a bug, the quicker we can fix it! |
| 25 | + - ❌ some excellent ideas are out-of-scope for this project; don't fret a rejected idea for an enhancement that is deemed too large or too complex to maintain. *It's not you, it's us!* |
| 26 | + - ❌ when posting a CLR/JIT stack trace, please avoid cluttering the issue with the "loaded assemblies" part; that (very) long list of loaded DLLs is not relevant. |
28 | 27 |
|
29 | | -- The Version of Rubberduck you are running. |
30 | | -- Steps to reproduce the issue (Code?). |
31 | | -- A **full and complete** logfile, preferrably at TRACE-level |
32 | | -- Screenshots? |
33 | | -- ... |
| 28 | +### Wiki |
34 | 29 |
|
35 | | -When posting a CLR/JIT stack trace, please avoid cluttering the issue with the "loaded assemblies" part; that (very) long list of loaded DLL's isn't relevant. |
| 30 | +The [wiki](https://github.com/rubberduck-vba/Rubberduck/wiki) is open for editing, and contributions are welcome. |
36 | 31 |
|
37 | | -### Suggesting Enhancements |
| 32 | + - ✏️ edit existing content to fix typos, update screenshots. |
| 33 | + - 📄 add new pages to document the source code and internal API. |
38 | 34 |
|
39 | | -The team is always happy to hear your ideas. Please do make sure you checked, whether someone else already requested something similar. |
40 | | -The label [enhancement] will be a good guide. |
| 35 | +### XML Documentation |
41 | 36 |
|
42 | | -Do note that despite the rather large scope of Rubberduck, some things are just **too large** or **too complex** for Rubberduck to effectively support. |
43 | | -Please don't be discouraged if your idea gets declined, your feedback is very valuable. |
| 37 | +The source code contains XML documentation that is compiled as an asset and that is ultimately used to generate content (English only) that is rendered on the website and sometimes accessible as an online resource from within Rubberduck. |
44 | 38 |
|
45 | | -As with Bug Reports the more exact you define what's your gripe, the quicker we can get back to you. |
| 39 | +Each page on the website generated from XML documentation in the source code, includes a link to 'edit this page' that points to the corresponding C# source file. With a GitHub login, it is easy to contribute enhancements to the documentation and content presented on the project's website. |
46 | 40 |
|
47 | | -### The Wiki |
| 41 | +You will find the XML documentation in the following folders/namespaces: |
48 | 42 |
|
49 | | -The Rubberduck Wiki is open for editing to everybody that has a Github account. |
50 | | -This is very much intentional. |
51 | | -Everybody is welcome to improve and expand the wiki. |
| 43 | + - [Rubberduck.CodeAnalysis.Inspections.Concrete](https://github.com/rubberduck-vba/Rubberduck/blob/next/Rubberduck.CodeAnalysis/Inspections/Concrete/README.md) |
| 44 | + - [Rubberduck.CodeAnalysis.QuickFixes.Concrete](https://github.com/rubberduck-vba/Rubberduck/blob/next/Rubberduck.CodeAnalysis/QuickFixes/Concrete/README.md) |
| 45 | + - [Rubberduck.Parsing.Annotations.Concrete](https://github.com/rubberduck-vba/Rubberduck/tree/next/Rubberduck.Parsing/Annotations/Concrete) |
52 | 46 |
|
53 | | -### Coding and Related |
| 47 | +### Just Saying Thanks |
54 | 48 |
|
55 | | -So you want to get your hands dirty and fix that obnoxious bug in the last release? |
56 | | -Well **great**, we like seeing new faces in the fray :) |
57 | | -Or you just want to find something that you can contribute to to learn C#? Or ... |
58 | | -Well whatever your motivation is, we recommend taking a look at issues that are labeled [\[up-for-grabs\]](https://github.com/rubberduck-vba/Rubberduck/issues?q=is%3Aissue+is%3Aopen+label%3Aup-for-grabs). |
| 49 | +Maintaining open-source software is often a thankless, selfless activity that involves a small and volunteering contributor force. If you ❤️ what we're doing here, we want to hear from you! Sure every ⭐ star gives us a warm fuzzy feeling of making a bit of a difference somewhere, but reading how our work impacts yours beats everything else. |
59 | 50 |
|
60 | | -Our Ducky has come quite the long way and is intimidatingly large for a first-time (or even long-time) contributor. |
61 | | -To make it easier to find something you can do, all issues with that label are additionally labelled with a difficulty. |
62 | | -That difficulty level is a best-guess by the dev-team how complex or evil an issue will be. |
| 51 | +[Tell us](https://github.com/rubberduck-vba/Rubberduck/issues/new?assignees=&labels=thanks&template=thanks-.md&title=) how you found out about Rubberduck, share that story about an obscure bug you'd been chasing for years that a Rubberduck inspection just single-handedly pointed out in a minute. |
63 | 52 |
|
64 | | -If you're new to C#, we recommend you start with \[difficulty-01-duckling\]. The next step \[difficulty-02-ducky\] requires some knowledge about C#, but not so much about how Rubberduck works - 02/ducky issues usually make a good introduction to using Rubberduck's internal API. |
| 53 | +We don't do any telemetry, so we don't know how our users are using Rubberduck. Tell us what your favorite features are, what features you're perhaps not using but wish you'd be able to find more information about. |
65 | 54 |
|
66 | | -Then there's \[difficulty-03-duck\] which requires a good handle on C# and how the components of Rubberduck play toghether. |
67 | | -And finally there's \[difficulty-04-quackhead\] for when you really want to bang your head against the wall. |
68 | | -They require both good knowledge of C# and a deep understanding of how not only Rubberduck, but also COM and well, the VBE, works. |
| 55 | +--- |
69 | 56 |
|
70 | | -In addition to this, a few people have put together some helpful resources about how Rubberduck works internally and help contributors tell left from right in the ~250k Lines of Code. |
| 57 | +## Code Contributions |
71 | 58 |
|
72 | | -You can find their work in the [GitHub wiki](https://github.com/rubberduck-vba/Rubberduck/wiki). If something in there doesn't quite seem to match, it's probably because nobody got around to updating it yet. You're very welcome to **improve** the wiki by adding and correcting information. (see right above) |
| 59 | +So you want to get your hands dirty and fix that obnoxious bug in the last release? Well that's great, we like seeing new faces in the fray 😄 Or you just want to find something that you can contribute to to learn C#? Or... Whatever your motivation is, if you're looking to add something new we recommend taking a look at issues that are labeled ; if you're looking to take down a known bug, you will want to pick from issues that are labeled with [](https://github.com/rubberduck-vba/Rubberduck/issues?q=is%3Aissue+is%3Aopen+label%3Abug). |
73 | 60 |
|
74 | | -In case this doesn't quite help you or the information you need hasn't been added to the wiki, you can **always** ask questions. |
75 | | -Please do so in the ["War room"](https://chat.stackexchange.com/rooms/14929). |
76 | | -Note that you will need an account on any of the Stack Exchange sites with at least 20 reputation points to ask questions there. |
77 | | -Other than that, you can also open an issue with the label \[support\], but it may take longer to get back to that. |
| 61 | +Rubberduck is intimidatingly large project, even for long-time contributors. When an issue is deemed fairly simple to fix or implement, we label it with , ...or with increasing but always very subjective difficulty/complexity levels up to |
| 62 | + if you dare. |
78 | 63 |
|
79 | | -In that room the core team talks about the duck and whatever else comes up. |
80 | | -N.B.: The rules of the Stack Exchange Network apply to everything you say in that room. But basically those are the same rules as those in the [CoC](#Code_of_Conduct). |
| 64 | +Level 3 and above demand a deeper knowledge of the inner workings of VBA (or VB6), the VBIDE, and Rubberduck's internal APIs - and we're always happy to help a contributor gain that knowledge! |
81 | 65 |
|
82 | | -Whether you create an issue or a pull request, please avoid using `[` square brackets `]` in the title, and try to be as descriptive (but succinct) as possible. Square brackets in titles confuse our chat-bot, and end up rendering in weird broken ways in SE chat. Avoid riddles, bad puns and other would-be funny (or NSFW) titles that don't really *describe the issue or PR*. |
| 66 | +We use GitHub's _Pull Request_ (PR) mechanism to share our work, so the first thing to do is to [fork the repository](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-forks) and then [cloning](https://docs.github.com/en/github/getting-started-with-github/about-remote-repositories#cloning-with-https-urls) it to your local machine. |
83 | 67 |
|
84 | | -### Translations |
| 68 | +Once you have a local copy of the repository, use Git commands (or GitHub tooling in Visual Studio) to [commit](https://docs.github.com/en/github/getting-started-with-github/github-glossary#commit) your local changes, then [push](https://docs.github.com/en/github/getting-started-with-github/github-glossary#push) your local branch to your GitHub fork, and from there you can use GitHub to create your PR. |
85 | 69 |
|
86 | | -Rubberduck is localized in multiple languages. |
87 | | -All these translations have been provided by volunteers. |
88 | | -We welcome both new translations as well as improvements to current translations very much. |
| 70 | +When you start work on an existing issue, comment on that issue to let us know you're on it and a pull request will be incoming as a result: don't hesitate to ask any questions you need answered to keep progressing, "issue" pages _exist_ for that type of discussion! |
89 | 71 |
|
90 | | -The resource files are RESX/XML files easily editable in any text editor, but our recommendation goes to the [ResXManager](https://marketplace.visualstudio.com/items?itemName=TomEnglert.ResXManager) Visual Studio plug-in: |
| 72 | +### Translations & Resources |
91 | 73 |
|
92 | | - |
| 74 | +Rubberduck doesn't speak your language? Get [ResX Manager](https://marketplace.visualstudio.com/items?itemName=TomEnglert.ResXManager) (available both as a Visual Studio plug-in and as a standalone application) and have it create all the necessary resource keys and help you navigate and track the many .resx files in the solution. |
93 | 75 |
|
94 | | -If you contribute a translation for a brand new previously unsupported language, please keep in touch with the dev team so that new resource keys can be translated when a new release is coming up; abandoned languages/translations will end up getting dropped. |
| 76 | +> ⚠️ If you contribute a translation for a brand new previously unsupported language, please **keep in touch** with the dev team so that new resource keys can be translated when a new release is coming up; abandoned languages/translations **will** end up getting dropped. |
95 | 77 |
|
96 | | -## What comes out of it for me? |
97 | | - |
98 | | -Well... the eternal gratitude of all Rubberduck users for one :wink: |
99 | | -Aside from that, all contributors are explicitly listed by name (or alias) in the "About Rubberduck" window. |
| 78 | +Pull requests that improve wordings and translations are always welcome, too! |
0 commit comments