Difference between revisions of "Get involved"

From D Wiki
Jump to: navigation, search
(See also: add links to contribution guides)
 
(24 intermediate revisions by 6 users not shown)
Line 1: Line 1:
 
== File a bug report ==
 
== File a bug report ==
  
The simplest way to participate is to [https://issues.dlang.org/enter_bug.cgi?product=D file bug reports] at the [http://issues.dlang.org/ bug tracker].
+
The simplest way to participate is to [https://issues.dlang.org/enter_bug.cgi?product=D file bug reports] on [[Bugzilla]].
  
 
If you find any problems with the D language, please file a bug report. Problems that are not filed will not get fixed, because the developers wouldn't know the problem existed. If you're not sure if something is a bug or by design, please ask in the forums (see below).
 
If you find any problems with the D language, please file a bug report. Problems that are not filed will not get fixed, because the developers wouldn't know the problem existed. If you're not sure if something is a bug or by design, please ask in the forums (see below).
Line 7: Line 7:
 
Ideally, bug reports should be accompanied by a [http://sscce.org/ small, self-contained example] which demonstrates the problem, and makes it easy to reproduce it. If you find it difficult to manually extract a small example from your source code, [https://github.com/CyberShadow/DustMite DustMite] can help with automatically extracting one. See [https://github.com/CyberShadow/DustMite/wiki the project wiki] for more information.
 
Ideally, bug reports should be accompanied by a [http://sscce.org/ small, self-contained example] which demonstrates the problem, and makes it easy to reproduce it. If you find it difficult to manually extract a small example from your source code, [https://github.com/CyberShadow/DustMite DustMite] can help with automatically extracting one. See [https://github.com/CyberShadow/DustMite/wiki the project wiki] for more information.
  
If a piece of code worked in an older version of a compiler but no longer works in a newer version, please file a regression (by setting the "Severity" field to "Regression"). Regression bugs are examined before all others. You can use [https://github.com/CyberShadow/Digger Digger] to find the pull request that introduced the change which broke your code. [https://github.com/CyberShadow/DustMite/wiki/Reducing-a-regression-between-two-D-versions DustMite can also be helpful] in creating a minimal example.
+
If a piece of code worked in an older version of a compiler but no longer works in a newer version, please file a regression (by setting the "Severity" field to "Regression"). Regression bugs are examined before all others. The simplest way to determine whether an issue is a regression or not is to go to [https://run.dlang.io/ run.dlang.io], paste your sample code and select "All dmd compilers" in the scrollbar next to the "Run" button. Ideally, regression reports contain the PR that introduced the regression. [https://github.com/CyberShadow/Digger Digger] is a great tool to find the pull request that introduced the change which broke your code. [https://github.com/CyberShadow/DustMite/wiki/Reducing-a-regression-between-two-D-versions DustMite can also be helpful] in creating a minimal example.
  
 
Note that compiler internal errors (crashes, assertion failures, etc.) should ''always'' be filed. No matter how wrong your input is, the compiler should give an appropriate error message and abort compilation; it should ''never'' crash. Such crashes are ''always'' bugs.
 
Note that compiler internal errors (crashes, assertion failures, etc.) should ''always'' be filed. No matter how wrong your input is, the compiler should give an appropriate error message and abort compilation; it should ''never'' crash. Such crashes are ''always'' bugs.
Line 16: Line 16:
  
 
The main D forum is for general discussion on the D language, feature requests and discussions, etc.. Newcomers should start with the [http://forum.dlang.org/group/digitalmars.D.learn D.learn] forum, which is intended for learners to ask more basic questions about programming in D.
 
The main D forum is for general discussion on the D language, feature requests and discussions, etc.. Newcomers should start with the [http://forum.dlang.org/group/digitalmars.D.learn D.learn] forum, which is intended for learners to ask more basic questions about programming in D.
 +
 +
== Write blog posts, articles and documentation ==
 +
 +
D doesn't have a dedicated outreach team. All blog posts about the language's awesome features, standard library, or a third-party DUB packages are very welcome.
 +
If you have an idea for a post on [http://blog.dlang.org D's official blog], please give [https://github.com/mdparker @mdparker] a ping.
 +
You may also consider improving the [https://tour.dlang.org DLang Tour], or [https://tour.dlang.org/tour/en/welcome/languages work on a translation].
 +
The source code for the DTour repos can be found [https://github.com/dlang-tour on GitHub].
  
 
== Alpha-test the development version of D ==
 
== Alpha-test the development version of D ==
  
If you're feeling adventurous, or crave the bleeding-edge features of D, you may want to learn [[Building DMD|how to build git master]].
+
If you're feeling adventurous, or crave the bleeding-edge features of D, you may want to try a [https://nightlies.dlang.org/dmd-nightly/ nightly build of DMD], or learn [[Building DMD|how to build git master]].
 +
 
 +
== Task List ==
 +
A list of tasked relevant to the community is kept [https://github.com/dlang/projects/issues  here]
  
 
== Contribute to the source code  ==
 
== Contribute to the source code  ==
  
=== Fix Bugzilla issues ===
+
=== Contributing to the Phobos source code ===
  
The source code for the D website, compiler, runtime library, and Phobos (the standard library), are all available on [https://github.com/dlang GitHub]. Contributions to the source code are done via [[Pull Requests|pull requests]]. Please note that contributions to DMD source code will only be accepted if the author agrees to have the copyright of the code assigned to the D Language Foundation.
+
==== Easy tasks ====
 +
 
 +
* Make sure every function in Phobos has an example -> <code>has_public_example</code> DScanner check (see [https://github.com/dlang/phobos/pull/5581 phobos/5581] for an example)
 +
* Make sure every function in Phobos has Params: and Returns: sections -> <code>properly_documented_public_functions</code> DScanner check
 +
* Improve code coverage
 +
** CodeCov provides an [https://codecov.io/gh/dlang/phobos/tree/master/std excellent overview]
 +
** e.g. <code>make -f std/ascii.test</code> yields a <code>std-ascii.lst</code> with the coverage information
 +
* Fix [https://issues.dlang.org/buglist.cgi?component=phobos&keywords=trivial%2C%20&keywords_type=anywords&list_id=215848&product=D&query_format=advanced&resolution=--- trivial issues at Phobos]
 +
 
 +
==== More tricky tasks ====
 +
 
 +
* Make more functions/module <code>@safe</code>
 +
** grep for <code>@system unittest</code>)
 +
** Guide: http://dlang.org/blog/2016/09/28/how-to-write-trusted-code-in-d
 +
** Another good resource for finding instances that could be <code>@safe</code> is grepping [https://github.com/rejectedsoftware/vibe.d vibe.d] for <code>@trusted</code> (or see [https://github.com/rejectedsoftware/vibe.d/pull/1618 vibe.d/1618])
 +
* Eliminate all gratuitous use of gc
 +
* Review all Phobos modules for compatibility with ranges  (std.zip, for example, was done before ranges and does not work with them)
 +
* [https://issues.dlang.org/buglist.cgi?component=phobos&keywords=bootcamp%2C%20preapproved&keywords_type=anywords&list_id=215846&product=D&query_format=advanced&resolution=--- Fix preapproved or bootcamp issues at Phobos]
 +
 
 +
==== Hard tasks ====
  
To find something to work on, you can [http://d.puremagic.com/issues/query.cgi search] the bug list for issues that you can help fix, or on one [https://issues.dlang.org/buglist.cgi?columnlist=votes%2Cbug_severity%2Cpriority%2Cop_sys%2Cassigned_to_realname%2Cbug_status%2Cshort_desc&field0-0-0=votes&order=votes%20DESC&resolution=--- that has been voted for a lot] or [https://issues.dlang.org/buglist.cgi?keywords=preapproved&resolution=--- preapproved].
+
* [https://issues.dlang.org/buglist.cgi?component=phobos&list_id=215849&product=D&resolution=--- Fix open issues at Phobos]
 +
* Remove autodecode from Phobos ([https://github.com/dlang/phobos/pull/5513 #5513 could help])
 +
* [[Wish_list|Add a new module]]
  
There is a pre-filtered list of [https://issues.dlang.org/buglist.cgi?bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=VERIFIED&component=dlang.org&component=dmd&component=druntime&component=installer&component=phobos&component=tools&component=visuald&keywords=trivial%2C%20&keywords_type=allwords&list_id=213785&product=D&query_format=advanced&resolution=---&version=D2 trivial] issues which might be good starting points for beginners.
+
=== Contribute to the DMD and DRuntime  ===
Help to maintain this pre-filtered list of trivial issues is welcome as well.
 
  
=== Simple tasks for Phobos ===
+
The source code for the D website, compiler, runtime library, and Phobos (the standard library), are all available on [https://github.com/dlang GitHub]. Contributions to the source code are done via [[Pull Requests|pull requests]]. Please note that contributions to DMD source code will only be accepted if the author agrees to have the copyright of the code assigned to the D Language Foundation.
  
The [[Vision/2016H2|high-level vision document]] lists many projects that one can start to change the status quo.
+
To find something to work on, you can [http://d.puremagic.com/issues/query.cgi search] the bug list for issues that you can help fix, or on one [https://issues.dlang.org/buglist.cgi?columnlist=votes%2Cbug_severity%2Cpriority%2Cop_sys%2Cassigned_to_realname%2Cbug_status%2Cshort_desc&field0-0-0=votes&order=votes%20DESC&resolution=--- that has been voted for a lot] or [https://issues.dlang.org/buglist.cgi?keywords=preapproved&resolution=--- preapproved].
However, as most of them might require a lot of time or expertise, here are a couple of ideas from the high-level vision that have been semi-automated and could be a good start to get involved:
 
  
* Improve code coverage [https://codecov.io/gh/dlang/phobos CodeCov report]
+
There is a pre-filtered list of [https://issues.dlang.org/buglist.cgi?keywords=trivial&resolution=--- trivial] issues which is a good starting points for beginners.
* Make sure every function in Phobos has an example [https://github.com/wilzbach/style-checkers/blob/master/has_public_example.d script],[https://github.com/dlang/phobos/pull/4973 example]
+
Improving [https://issues.dlang.org/buglist.cgi?keywords=diagnostic&resolution=--- compiler error messages] is also often easy and a good way to become familiar with the DMD source code.
* Make sure every function in Phobos has Params: and Returns: [https://github.com/Hackerpilot/Dscanner/pull/390 script]
 
* Review `@safe` usage in Phobos (or `@system` -> `@safe`) [http://dlang.org/safed.html guide], [https://github.com/dlang/phobos/pull/4690 example]
 
* Enable more Dscanner plugins/automation for Phobos [https://github.com/dlang/phobos/blob/master/.dscanner.ini config]
 
  
 
=== Contribute to the documentation and dlang.org ===
 
=== Contribute to the documentation and dlang.org ===
Line 49: Line 75:
 
== Review pull requests ==
 
== Review pull requests ==
  
The sheer amount of code being written for the D compiler, standard library and related project is often too great for the core developers to keep up. Even if you're not a "hardcore" D developer you can help lessen this load by reviewing the changes in pull requests at GitHub for [https://github.com/dlang/dmd/pulls DMD], [https://github.com/dlang/phobos/pulls Phobos], [https://github.com/dlang/druntime/pulls DRuntime] and the [https://github.com/dlang/dlang.org/pulls D website].
+
The sheer amount of code being written for the D compiler, standard library and related project is often too great for the core developers to keep up. Even if you're not a "hardcore" D developer you can help lessen this load by reviewing the changes in pull requests at GitHub for [https://github.com/dlang/dmd/pulls DMD], [https://github.com/dlang/phobos/pulls Phobos], [https://github.com/dlang/druntime/pulls DRuntime], the [https://github.com/dlang/dlang.org/pulls D website], and the [https://github.com/dlang/dub/pulls dub package manager].
  
 
Various "easy" things to look for:  
 
Various "easy" things to look for:  
Line 59: Line 85:
 
* API inconvenient for use cases the author didn't think of
 
* API inconvenient for use cases the author didn't think of
 
* Missing/inadequate unittests
 
* Missing/inadequate unittests
* Unittests should be annotated @safe. If @safe is not possible, it [https://forum.dlang.org/post/nkn25t$btk$1@digitalmars.com shall] be @system.
+
* Poor code coverage (install the [https://github.com/codecov/browser-extension CodeCov browser extension] or check <code>dmd -cov -unittest -main std/filename.d</code>)
* Poor code coverage (install the [https://github.com/codecov/browser-extension CodeCov browser extension] or check `dmd -cov -unittest -main std/filename.d`)
 
 
* More/better code examples in documentation. Look at answers in [http://forum.dlang.org/group/digitalmars.D.learn D.learn] and [http://stackoverflow.com/questions/tagged/d stack overflow] for ideas.
 
* More/better code examples in documentation. Look at answers in [http://forum.dlang.org/group/digitalmars.D.learn D.learn] and [http://stackoverflow.com/questions/tagged/d stack overflow] for ideas.
 
* Missing overflow checks when calculating storage sizes
 
* Missing overflow checks when calculating storage sizes
Line 68: Line 93:
 
* Drifting off topic, i.e. anything other than the PR being reviewed.
 
* Drifting off topic, i.e. anything other than the PR being reviewed.
  
To run the unittests of a single file on posix:
+
To run the unittests of a single file on Posix:
 
<syntaxhighlight lang=bash>
 
<syntaxhighlight lang=bash>
make -f posix.mak DMD=../dmd/src/dmd std/*.test  
+
make -f posix.mak std/file.test  
 
</syntaxhighlight>
 
</syntaxhighlight>
Adding "-cov" to the "%.test" target inside posix.mak will generate a coverage analysis.
 
  
 
Also, it is often helpful to review old pull requests (e.g. sort by least recently updated on GitHub). Commenting on an old pull request that seems OK but was for some reason forgotten may bring some attention to it. If you think a pull request is OK to be merged, write "LGTM" (looks good to merge) in your comment.
 
Also, it is often helpful to review old pull requests (e.g. sort by least recently updated on GitHub). Commenting on an old pull request that seems OK but was for some reason forgotten may bring some attention to it. If you think a pull request is OK to be merged, write "LGTM" (looks good to merge) in your comment.
Line 81: Line 105:
  
 
:"If you see [Pull request] you care about, review it even if you don't have rights yet. A simple message such as "I reviewed this and LGTM, any holdup?" would be sufficient to attract attention."
 
:"If you see [Pull request] you care about, review it even if you don't have rights yet. A simple message such as "I reviewed this and LGTM, any holdup?" would be sufficient to attract attention."
 +
 +
== Write a DIP about a language change ==
 +
 +
A [https://github.com/dlang/DIPs D Improvement Proposal (DIP)] is a formal document that details a potential feature or enhancement to the language, or the official tooling, and the rationale behind it.
 +
If you feel strongly about missing feature or would like to change a behavior, you should consider writing a [https://github.com/dlang/DIPs DIP].
  
 
== Google Summer of Code ideas ==
 
== Google Summer of Code ideas ==
Line 98: Line 127:
 
* [http://wiki.dlang.org/LDC_project_ideas LDC project ideas]
 
* [http://wiki.dlang.org/LDC_project_ideas LDC project ideas]
 
* [http://wiki.dlang.org/GDC/ProjectIdeas GDC project ideas]
 
* [http://wiki.dlang.org/GDC/ProjectIdeas GDC project ideas]
* [http://stackoverflow.com/documentation/d Extend the Stackoverflow D documentation]
 
  
 
== How to better promote your own D projects ==
 
== How to better promote your own D projects ==
Line 147: Line 175:
 
* [[Bugzilla]]
 
* [[Bugzilla]]
 
* [[Pull Requests]], [[Review process]], [http://dlang.org/dstyle.html Phobos style guidelines]
 
* [[Pull Requests]], [[Review process]], [http://dlang.org/dstyle.html Phobos style guidelines]
* [[Building DMD]], [[Build DMD for Android]]
+
* [[Build DMD for Android]]
 
* [[DMD Source Guide]]
 
* [[DMD Source Guide]]
 
* [[Release Process]]
 
* [[Release Process]]
* [[History Of Development Model For D]]
 
* [[Phobos]]
 
 
* [[Git Commit Tester]]
 
* [[Git Commit Tester]]
 
* [[Using Git on Windows]]
 
* [[Using Git on Windows]]
* [[Container Ideas]]
 
  
 
[[Category: Contribution Guidelines]]
 
[[Category: Contribution Guidelines]]

Latest revision as of 12:48, 11 March 2021

File a bug report

The simplest way to participate is to file bug reports on Bugzilla.

If you find any problems with the D language, please file a bug report. Problems that are not filed will not get fixed, because the developers wouldn't know the problem existed. If you're not sure if something is a bug or by design, please ask in the forums (see below).

Ideally, bug reports should be accompanied by a small, self-contained example which demonstrates the problem, and makes it easy to reproduce it. If you find it difficult to manually extract a small example from your source code, DustMite can help with automatically extracting one. See the project wiki for more information.

If a piece of code worked in an older version of a compiler but no longer works in a newer version, please file a regression (by setting the "Severity" field to "Regression"). Regression bugs are examined before all others. The simplest way to determine whether an issue is a regression or not is to go to run.dlang.io, paste your sample code and select "All dmd compilers" in the scrollbar next to the "Run" button. Ideally, regression reports contain the PR that introduced the regression. Digger is a great tool to find the pull request that introduced the change which broke your code. DustMite can also be helpful in creating a minimal example.

Note that compiler internal errors (crashes, assertion failures, etc.) should always be filed. No matter how wrong your input is, the compiler should give an appropriate error message and abort compilation; it should never crash. Such crashes are always bugs.

Discuss in the forums

You can also join in the discussion at the D forums, which can be accessed via the web interface, the mailing list interface, or the NNTP server.

The main D forum is for general discussion on the D language, feature requests and discussions, etc.. Newcomers should start with the D.learn forum, which is intended for learners to ask more basic questions about programming in D.

Write blog posts, articles and documentation

D doesn't have a dedicated outreach team. All blog posts about the language's awesome features, standard library, or a third-party DUB packages are very welcome. If you have an idea for a post on D's official blog, please give @mdparker a ping. You may also consider improving the DLang Tour, or work on a translation. The source code for the DTour repos can be found on GitHub.

Alpha-test the development version of D

If you're feeling adventurous, or crave the bleeding-edge features of D, you may want to try a nightly build of DMD, or learn how to build git master.

Task List

A list of tasked relevant to the community is kept here

Contribute to the source code

Contributing to the Phobos source code

Easy tasks

  • Make sure every function in Phobos has an example -> has_public_example DScanner check (see phobos/5581 for an example)
  • Make sure every function in Phobos has Params: and Returns: sections -> properly_documented_public_functions DScanner check
  • Improve code coverage
    • CodeCov provides an excellent overview
    • e.g. make -f std/ascii.test yields a std-ascii.lst with the coverage information
  • Fix trivial issues at Phobos

More tricky tasks

Hard tasks

Contribute to the DMD and DRuntime

The source code for the D website, compiler, runtime library, and Phobos (the standard library), are all available on GitHub. Contributions to the source code are done via pull requests. Please note that contributions to DMD source code will only be accepted if the author agrees to have the copyright of the code assigned to the D Language Foundation.

To find something to work on, you can search the bug list for issues that you can help fix, or on one that has been voted for a lot or preapproved.

There is a pre-filtered list of trivial issues which is a good starting points for beginners. Improving compiler error messages is also often easy and a good way to become familiar with the DMD source code.

Contribute to the documentation and dlang.org

To contribute to the documentation, start by reading How to Fork and Build dlang.org. Additional information on improving the documentation can be found in this thread started by Walter Bright.

Review pull requests

The sheer amount of code being written for the D compiler, standard library and related project is often too great for the core developers to keep up. Even if you're not a "hardcore" D developer you can help lessen this load by reviewing the changes in pull requests at GitHub for DMD, Phobos, DRuntime, the D website, and the dub package manager.

Various "easy" things to look for:

  • Missing or hard to understand comments
  • Unintuitive documentation
  • Unchecked edge cases in the code (missing assert, enforce, template constraints)
  • Inconsistencies with the D style
  • API inconvenient for use cases the author didn't think of
  • Missing/inadequate unittests
  • Poor code coverage (install the CodeCov browser extension or check dmd -cov -unittest -main std/filename.d)
  • More/better code examples in documentation. Look at answers in D.learn and stack overflow for ideas.
  • Missing overflow checks when calculating storage sizes

Please avoid:

  • Drifting off topic, i.e. anything other than the PR being reviewed.

To run the unittests of a single file on Posix:

make -f posix.mak std/file.test

Also, it is often helpful to review old pull requests (e.g. sort by least recently updated on GitHub). Commenting on an old pull request that seems OK but was for some reason forgotten may bring some attention to it. If you think a pull request is OK to be merged, write "LGTM" (looks good to merge) in your comment.

If a pull you're interested in has been languishing in the queue for a long time with no attention, commenting "ping" may help prod things along. Especially if the author needs to rebase the pull due to a merge conflict, autotester failure, or other such maintenance problem.

Citing Andrei Alexandrescu:

"If you see [Pull request] you care about, review it even if you don't have rights yet. A simple message such as "I reviewed this and LGTM, any holdup?" would be sufficient to attract attention."

Write a DIP about a language change

A D Improvement Proposal (DIP) is a formal document that details a potential feature or enhancement to the language, or the official tooling, and the rationale behind it. If you feel strongly about missing feature or would like to change a behavior, you should consider writing a DIP.

Google Summer of Code ideas

Some of the past ideas may still be interesting:

Other D-related projects

How to better promote your own D projects

I hate the movie "Field of Dreams" where they push the idiotic idea of "Build it and they will come." No, they won't. There's a blizzard of stuff competing for their attention out there, why should they invest the time looking at your stuff? You need to tell them why!

Here's the frustrating typical pattern I've seen here for years:

  1. spend hundreds if not thousands of hours developing something really cool
  2. spend 2 minutes posting a link to the repository on D.announce
  3. someone posts it to reddit. Ignore it
  4. get frustrated that nobody looks at it
  5. get bitter and quit

Here's the pattern that works a lot better:

  1. spend hundreds if not thousands of hours developing something really cool
  2. spend 10 minutes writing the announcement to D.announce. Be sure to include:
    who, what, where, when, why, and how
  3. someone posts it to reddit
  4. post the who, what, where, when, why and how on reddit AS SOON AS POSSIBLE after the reddit link appears. Stuff on reddit has a VERY SHORT shelf life. If it doesn't get action within a couple hours, it fades into oblivion. Identify yourself as the author, say AMA. The first one to post a comment tends to spark and set the tone for the discussion.
  5. check back on reddit once an hour or so for the next day, answer questions
  6. *****
  7. profit!

Walter Bright

Contribute to this wiki

  • D as a second language sections should be completed
  • add more examples of how to shift idiom to speak fluent D
  • flesh out the Python page
  • review empty sections
  • update C and C++ transition guides

One note about Walter's older C/C++ transition articles. They have good information on transition technicalities (e.g. "how do I do this thing in D that I used to do in C++?") but not a lot about the changes in coding style - making object copying not arbitrarily expensive, choosing struct vs. class, preferring pipelines and lazy to eager computation, etc. From what I see some folks come from C++, write their first D program in a stilted C++ idiom, and are left with the impression that the work is not worth the trouble.

Andrei

See also