145 lines
23 KiB
HTML
145 lines
23 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8" />
|
|
<title>Contributing » Guidelines | Taskflow QuickStart</title>
|
|
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600" />
|
|
<link rel="stylesheet" href="m-dark+documentation.compiled.css" />
|
|
<link rel="icon" href="favicon.ico" type="image/vnd.microsoft.icon" />
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
|
<meta name="theme-color" content="#22272e" />
|
|
</head>
|
|
<body>
|
|
<header><nav id="navigation">
|
|
<div class="m-container">
|
|
<div class="m-row">
|
|
<span id="m-navbar-brand" class="m-col-t-8 m-col-m-none m-left-m">
|
|
<a href="https://taskflow.github.io"><img src="taskflow_logo.png" alt="" />Taskflow</a> <span class="m-breadcrumb">|</span> <a href="index.html" class="m-thin">QuickStart</a>
|
|
</span>
|
|
<div class="m-col-t-4 m-hide-m m-text-right m-nopadr">
|
|
<a href="#search" class="m-doc-search-icon" title="Search" onclick="return showSearch()"><svg style="height: 0.9rem;" viewBox="0 0 16 16">
|
|
<path id="m-doc-search-icon-path" d="m6 0c-3.31 0-6 2.69-6 6 0 3.31 2.69 6 6 6 1.49 0 2.85-0.541 3.89-1.44-0.0164 0.338 0.147 0.759 0.5 1.15l3.22 3.79c0.552 0.614 1.45 0.665 2 0.115 0.55-0.55 0.499-1.45-0.115-2l-3.79-3.22c-0.392-0.353-0.812-0.515-1.15-0.5 0.895-1.05 1.44-2.41 1.44-3.89 0-3.31-2.69-6-6-6zm0 1.56a4.44 4.44 0 0 1 4.44 4.44 4.44 4.44 0 0 1-4.44 4.44 4.44 4.44 0 0 1-4.44-4.44 4.44 4.44 0 0 1 4.44-4.44z"/>
|
|
</svg></a>
|
|
<a id="m-navbar-show" href="#navigation" title="Show navigation"></a>
|
|
<a id="m-navbar-hide" href="#" title="Hide navigation"></a>
|
|
</div>
|
|
<div id="m-navbar-collapse" class="m-col-t-12 m-show-m m-col-m-none m-right-m">
|
|
<div class="m-row">
|
|
<ol class="m-col-t-6 m-col-m-none">
|
|
<li><a href="pages.html">Handbook</a></li>
|
|
<li><a href="namespaces.html">Namespaces</a></li>
|
|
</ol>
|
|
<ol class="m-col-t-6 m-col-m-none" start="3">
|
|
<li><a href="annotated.html">Classes</a></li>
|
|
<li><a href="files.html">Files</a></li>
|
|
<li class="m-show-m"><a href="#search" class="m-doc-search-icon" title="Search" onclick="return showSearch()"><svg style="height: 0.9rem;" viewBox="0 0 16 16">
|
|
<use href="#m-doc-search-icon-path" />
|
|
</svg></a></li>
|
|
</ol>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</nav></header>
|
|
<main><article>
|
|
<div class="m-container m-container-inflatable">
|
|
<div class="m-row">
|
|
<div class="m-col-l-10 m-push-l-1">
|
|
<h1>
|
|
<span class="m-breadcrumb"><a href="Contributing.html">Contributing</a> »</span>
|
|
Guidelines
|
|
</h1>
|
|
<nav class="m-block m-default">
|
|
<h3>Contents</h3>
|
|
<ul>
|
|
<li><a href="#HowCanIContribute">How Can I Contribute?</a></li>
|
|
<li><a href="#HowCanIGetCredit">How Can I Get Credit?</a></li>
|
|
<li>
|
|
<a href="#HowCanIGetStarted">How Can I Get Started?</a>
|
|
<ul>
|
|
<li><a href="#Step1LookAround">Step 1: Look around</a></li>
|
|
<li><a href="#Step2WriteATaskflowProgram">Step 2: Write a Taskflow program</a></li>
|
|
<li><a href="#Step3WriteATaskflowProgram">Step 3: Dive in</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#HowCanIReportAnIssue">How Can I Report Issues?</a></li>
|
|
<li><a href="#HowCanIEditTheDocumentation">How Can I Edit the Documentation?</a></li>
|
|
<li><a href="#HowCanISubmitAPatch">How Can I Submit a Patch?</a></li>
|
|
<li><a href="#HowCanILeadAProject">How Can I Lead a Project?</a></li>
|
|
<li><a href="#YourVoiceMatters">Your Voice Matters!</a></li>
|
|
</ul>
|
|
</nav>
|
|
<p>This pages outlines the process that you will need to follow to get a patch merged.</p><section id="HowCanIContribute"><h2><a href="#HowCanIContribute">How Can I Contribute?</a></h2><p>There are multiple ways in which you can contribute to Taskflow:</p><ul><li>Use it! Let us know what you think and how it helps your jobs!</li><li>Catch a typo in documentation or want to make it better to understand? Edit the <a href="https://github.com/taskflow/taskflow/tree/master/doxygen">doc source</a> and visit <a href="install.html#BAIBuildDocumentation" class="m-doc">Build Documentation</a>!</li><li>Ask questions, request new features, and catch bugs? Report it at <a href="https://github.com/taskflow/taskflow/issues">issue tracker</a>!</li><li>Know how to fix an issue, bug, or add new features? Make a <a href="https://github.com/taskflow/taskflow/pulls">pull request</a>!</li><li>Share Taskflow with others. The more people use it, the more solid Taskflow becomes!</li></ul><p>Your contributions are always welcome. Every contribution regardless of its size is significant to keep Taskflow thrive.</p></section><section id="HowCanIGetCredit"><h2><a href="#HowCanIGetCredit">How Can I Get Credit?</a></h2><p>Your contribution is an undeniably important piece of the Taskflow project, and we want to make sure you always get credit for your work. Depending on the technical innovation and engineering effort, we credit your contributions as follows:</p><ul><li>We document your commit or pull request at the <a href="contributors.html" class="m-doc">Contributors</a> page</li><li>We advertise your organization as either users or sponsors at the <a href="https://taskflow.github.io/">Project Website</a></li><li>We highlight your names in our technical presentations (e.g., <a href="https://www.youtube.com/user/CppCon">CppCon</a>) from time to time</li><li>We co-author you in our research publications if you introduce significant innovation (see <a href="References.html" class="m-doc">References</a>)</li></ul><p>Your effort really matters to us and we are eater to acknowledge your contributions! As such, we would welcome any advice and recommendations that can improve our credit system. Please <a href="https://taskflow.github.io/#tag_contact">contact us</a>.</p></section><section id="HowCanIGetStarted"><h2><a href="#HowCanIGetStarted">How Can I Get Started?</a></h2><p>There are no better ways other than trying out Taskflow before you want to contribute. We summarize a few steps below for you to follow.</p><section id="Step1LookAround"><h3><a href="#Step1LookAround">Step 1: Look around</a></h3><p>Visit the <a href="https://taskflow.github.io/">Project Website</a> and get an 1000-feet overview of Taskflow, in which you shall find recent news, releases, use cases, and other useful information of Taskflow. We also provided a <a href="https://taskflow.github.io/showcase/index.html">showcase presentation</a> for you to quickly understand the technical work of Taskflow. Then, check out our <a href="usecases.html" class="m-doc">Real Use Cases</a> and get a sense about the problems Taskflow is good at.</p></section><section id="Step2WriteATaskflowProgram"><h3><a href="#Step2WriteATaskflowProgram">Step 2: Write a Taskflow program</a></h3><p>Taskflow is a programming system. We believe it is impossible to understand what Taskflow is doing without writing real code. Visit the quick-start page and program your first hello-world with Taskflow!</p><pre class="m-code"><span class="cp">#include</span><span class="w"> </span><span class="cpf"><taskflow/taskflow.hpp></span><span class="c1"> // Taskflow is header-only</span>
|
|
|
|
<span class="kt">int</span><span class="w"> </span><span class="nf">main</span><span class="p">(){</span>
|
|
<span class="w"> </span>
|
|
<span class="w"> </span><span class="n">tf</span><span class="o">::</span><span class="n">Executor</span><span class="w"> </span><span class="n">executor</span><span class="p">;</span>
|
|
<span class="w"> </span><span class="n">tf</span><span class="o">::</span><span class="n">Taskflow</span><span class="w"> </span><span class="n">taskflow</span><span class="p">;</span>
|
|
|
|
<span class="w"> </span><span class="k">auto</span><span class="w"> </span><span class="p">[</span><span class="n">A</span><span class="p">,</span><span class="w"> </span><span class="n">B</span><span class="p">,</span><span class="w"> </span><span class="n">C</span><span class="p">,</span><span class="w"> </span><span class="n">D</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">taskflow</span><span class="p">.</span><span class="n">emplace</span><span class="p">(</span>
|
|
<span class="w"> </span><span class="p">[]</span><span class="w"> </span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">std</span><span class="o">::</span><span class="n">cout</span><span class="w"> </span><span class="o"><<</span><span class="w"> </span><span class="s">"TaskA</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span><span class="w"> </span><span class="p">},</span><span class="w"> </span><span class="c1">// task dependency graph</span>
|
|
<span class="w"> </span><span class="p">[]</span><span class="w"> </span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">std</span><span class="o">::</span><span class="n">cout</span><span class="w"> </span><span class="o"><<</span><span class="w"> </span><span class="s">"TaskB</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span><span class="w"> </span><span class="p">},</span><span class="w"> </span><span class="c1">// </span>
|
|
<span class="w"> </span><span class="p">[]</span><span class="w"> </span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">std</span><span class="o">::</span><span class="n">cout</span><span class="w"> </span><span class="o"><<</span><span class="w"> </span><span class="s">"TaskC</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span><span class="w"> </span><span class="p">},</span><span class="w"> </span><span class="c1">// +---+ </span>
|
|
<span class="w"> </span><span class="p">[]</span><span class="w"> </span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">std</span><span class="o">::</span><span class="n">cout</span><span class="w"> </span><span class="o"><<</span><span class="w"> </span><span class="s">"TaskD</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="c1">// +---->| B |-----+ </span>
|
|
<span class="w"> </span><span class="p">);</span><span class="w"> </span><span class="c1">// | +---+ |</span>
|
|
<span class="w"> </span><span class="c1">// +---+ +-v-+ </span>
|
|
<span class="w"> </span><span class="n">A</span><span class="p">.</span><span class="n">precede</span><span class="p">(</span><span class="n">B</span><span class="p">);</span><span class="w"> </span><span class="c1">// A runs before B // | A | | D | </span>
|
|
<span class="w"> </span><span class="n">A</span><span class="p">.</span><span class="n">precede</span><span class="p">(</span><span class="n">C</span><span class="p">);</span><span class="w"> </span><span class="c1">// A runs before C // +---+ +-^-+ </span>
|
|
<span class="w"> </span><span class="n">B</span><span class="p">.</span><span class="n">precede</span><span class="p">(</span><span class="n">D</span><span class="p">);</span><span class="w"> </span><span class="c1">// B runs before D // | +---+ | </span>
|
|
<span class="w"> </span><span class="n">C</span><span class="p">.</span><span class="n">precede</span><span class="p">(</span><span class="n">D</span><span class="p">);</span><span class="w"> </span><span class="c1">// C runs before D // +---->| C |-----+ </span>
|
|
<span class="w"> </span><span class="c1">// +---+ </span>
|
|
<span class="w"> </span><span class="n">executor</span><span class="p">.</span><span class="n">run</span><span class="p">(</span><span class="n">taskflow</span><span class="p">).</span><span class="n">wait</span><span class="p">();</span>
|
|
|
|
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
|
|
<span class="p">}</span></pre><p>The hello-world program creates four tasks, <code>A</code>, <code>B</code>, <code>C</code>, and <code>D</code>, where <code>A</code> runs before <code>B</code> and <code>C</code>, and <code>D</code> runs after <code>B</code> and <code>C</code>. When <code>A</code> finishes, <code>B</code> and <code>C</code> can run in parallel, and then <code>D</code>.</p></section><section id="Step3WriteATaskflowProgram"><h3><a href="#Step3WriteATaskflowProgram">Step 3: Dive in</a></h3><p>After you successfully finish the hello-world example, give a deep dive-in to the technical details by visiting <a href="Cookbook.html" class="m-doc">Cookbook</a>, <a href="Algorithms.html" class="m-doc">Taskflow Algorithms</a>, and <a href="Examples.html" class="m-doc">Learning from Examples</a>. These pages provides you step-by-step tutorials about the fundamental syntaxes and tasking models in Taskflow that you need to fully take advantage of task graph parallelism to boost your application performance.</p><p>At this stage, you may encounter issues, features requests, and questions. Then, start your first contribution by posting them in our <a href="https://github.com/taskflow/taskflow/issues">issue tracker</a>!</p></section></section><section id="HowCanIReportAnIssue"><h2><a href="#HowCanIReportAnIssue">How Can I Report Issues?</a></h2><p>Taskflow is in active development. We are not surprised that you encounter something that needs improvement or fixes to work for your use cases. Or you want to suggest something that can improve Taskflow's functionality. Please do not hesitate to share any of these issues with by by opening an post at our <a href="https://github.com/taskflow/taskflow/issues">issue tracker</a>!</p><p>Please make sure that you provide all the necessary information in the issue body to communicate your problem clearly so we can work on it efficiently.</p></section><section id="HowCanIEditTheDocumentation"><h2><a href="#HowCanIEditTheDocumentation">How Can I Edit the Documentation?</a></h2><p>Documentation is just as important as the codebase! There is always a scope of improvement in documentation to add some missing information or to make it easier to read. We use the famous <a href="https://www.doxygen.nl/index.html">Doxygen</a> to compile our documentation. You can edit the <a href="https://github.com/taskflow/taskflow/tree/master/doxygen">documentation source</a> which is stored as a text file in the <code>doxygen</code> directory of Taskflow. After editing the file locally, you can submit your changes to us by making a patch.</p></section><section id="HowCanISubmitAPatch"><h2><a href="#HowCanISubmitAPatch">How Can I Submit a Patch?</a></h2><p>To contribute your code to Taskflow, you need to make a <a href="https://github.com/taskflow/taskflow/pulls">pull request</a> from your <a href="https://github.com/taskflow/taskflow/network/members">fork of Taskflow</a>. GitHub makes the development flow of <a href="https://docs.github.com/en/enterprise/2.13/user/articles/about-pull-requests">submitting pull requests</a> extremely handy as long as you follow the standard fork process.</p><p>When you make a pull request, please provide all the necessary information requested by prompts in the pull request body. In addition, make sure the code you are submitting always accounts for the following three guidelines:</p><ul><li><strong>Run the tests:</strong> You must pass through our unit tests (see <a href="install.html" class="m-doc">Building and Installing</a>) before submitting the pull request. Our unit tests have accumulated many corner cases over the past years that can detect defects in the newly developed features or bugs when changing the existing functionality.</li></ul><ul><li><strong>Profile the change:</strong> You must inspect any performance hit caused by your changes. There are multiple ways to profile Taskflow but we recommend you try to record the runtime of completing all unit tests <em>before</em> and <em>after</em> your changes.</li></ul><ul><li><strong>Document the code:</strong> You must document the code or provide a clear explanation about your pull request. You may also provide <a href="https://github.com/taskflow/taskflow/tree/master/examples">examples</a> specific to your new changes and include them in our cmake script.</li></ul><p>Please let us know all people who are involved in the pull request so that we can appropriately acknowledge everyone's effort at the <a href="contributors.html" class="m-doc">Contributors</a> page. If there are any issues that you would like to communicate offline, please <a href="https://taskflow.github.io/#tag_contact">contact us</a>.</p></section><section id="HowCanILeadAProject"><h2><a href="#HowCanILeadAProject">How Can I Lead a Project?</a></h2><p>There are many on-going and future projects that interest us and the Taskflow community. Given the tremendous amount of work, we welcome organizations or individuals to take lead on these projects. The table below summarizes a list of projects that need you to either take lead or contribute:</p><table class="m-table"><thead><tr><th>Item</th><th>Status</th><th>Description</th></tr></thead><tbody><tr><td>Visualizing Taskflow</td><td>need contributors</td><td>enhance <a href="https://taskflow.github.io/tfprof/">tfprof</a> in various aspects, including visualizing critical paths along the taskflow graphs, handling large profile data to overcome, improving the user interface, and embedding WebAssembly to speed up the data query</td></tr><tr><td>Binding Python</td><td>need leaders</td><td>provide a python binding with a programming model to allow Taskflow to contribute to the python scientific computing communities</td></tr><tr><td>Adding Benchmarks</td><td>need contributors</td><td>enhance the <a href="https://github.com/taskflow/taskflow/tree/master/benchmarks">benchmark pool</a> to provide more parallel computing instances that can help profile Taskflow</td></tr><tr><td>Developing Algorithms</td><td>need contributors</td><td>enhance our generic <a href="Algorithms.html" class="m-doc">Taskflow Algorithms</a> collection by adding more parallel algorithm skeletons that can help developers quickly describe common parallel workloads (e.g., C++ 17/20 parallel algorithms)</td></tr><tr><td>Developing Kernels Algorithms</td><td>need contributors</td><td>enhance our cudaFlow by providing common GPU kernels (e.g., reduce, sort, scan, prefix_sum, etc.) that developers can quickly leverage when describing GPU work using cudaFlows</td></tr><tr><td>Integrating OpenCL</td><td>need leaders</td><td>design another task type, <em>clFlow</em>, to support OpenCL in a task-graph fashion and schedule OpenCL tasks using graph parallelism</td></tr><tr><td>Supporting pipeline</td><td>need leaders</td><td>design a tasking interface to support pipeline of a data stream over a taskflow graph, where we may resemble <a href="https://www.threadingbuildingblocks.org/docs/help/tbb_userguide/Working_on_the_Assembly_Line_pipeline.html">tbb::<wbr />parallel_pipeline</a></td></tr><tr><td>Diagnosing Taskflow</td><td>need contributors</td><td>devise API and algorithms to diagnose if the given taskflow is properly conditioned under our <a href="ConditionalTasking.html#TaskSchedulingPolicy" class="m-doc">Understand our Task-level Scheduling</a>, for example, tf::Taskflow::diagnose, under two modes, before running and on the running</td></tr></tbody></table><p>If you have identified any other projects that can be included to the list, please make a post at our <a href="https://github.com/taskflow/taskflow/issues">issue tracker</a> or <a href="https://taskflow.github.io/#tag_contact">contact us</a>.</p></section><section id="YourVoiceMatters"><h2><a href="#YourVoiceMatters">Your Voice Matters!</a></h2><p>If you find Taskflow helpful, please share it with your peers, colleagues, and anyone who can benefit from Taskflow. By telling other people about how Taskflow helped you, you will help us in turn and broaden our impact.</p><p>Thank you very much for contributing!</p></section>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</article></main>
|
|
<div class="m-doc-search" id="search">
|
|
<a href="#!" onclick="return hideSearch()"></a>
|
|
<div class="m-container">
|
|
<div class="m-row">
|
|
<div class="m-col-m-8 m-push-m-2">
|
|
<div class="m-doc-search-header m-text m-small">
|
|
<div><span class="m-label m-default">Tab</span> / <span class="m-label m-default">T</span> to search, <span class="m-label m-default">Esc</span> to close</div>
|
|
<div id="search-symbolcount">…</div>
|
|
</div>
|
|
<div class="m-doc-search-content">
|
|
<form>
|
|
<input type="search" name="q" id="search-input" placeholder="Loading …" disabled="disabled" autofocus="autofocus" autocomplete="off" spellcheck="false" />
|
|
</form>
|
|
<noscript class="m-text m-danger m-text-center">Unlike everything else in the docs, the search functionality <em>requires</em> JavaScript.</noscript>
|
|
<div id="search-help" class="m-text m-dim m-text-center">
|
|
<p class="m-noindent">Search for symbols, directories, files, pages or
|
|
modules. You can omit any prefix from the symbol or file path; adding a
|
|
<code>:</code> or <code>/</code> suffix lists all members of given symbol or
|
|
directory.</p>
|
|
<p class="m-noindent">Use <span class="m-label m-dim">↓</span>
|
|
/ <span class="m-label m-dim">↑</span> to navigate through the list,
|
|
<span class="m-label m-dim">Enter</span> to go.
|
|
<span class="m-label m-dim">Tab</span> autocompletes common prefix, you can
|
|
copy a link to the result using <span class="m-label m-dim">⌘</span>
|
|
<span class="m-label m-dim">L</span> while <span class="m-label m-dim">⌘</span>
|
|
<span class="m-label m-dim">M</span> produces a Markdown link.</p>
|
|
</div>
|
|
<div id="search-notfound" class="m-text m-warning m-text-center">Sorry, nothing was found.</div>
|
|
<ul id="search-results"></ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<script src="search-v2.js"></script>
|
|
<script src="searchdata-v2.js" async="async"></script>
|
|
<footer><nav>
|
|
<div class="m-container">
|
|
<div class="m-row">
|
|
<div class="m-col-l-10 m-push-l-1">
|
|
<p>Taskflow handbook is part of the <a href="https://taskflow.github.io">Taskflow project</a>, copyright © <a href="https://tsung-wei-huang.github.io/">Dr. Tsung-Wei Huang</a>, 2018–2024.<br />Generated by <a href="https://doxygen.org/">Doxygen</a> 1.9.1 and <a href="https://mcss.mosra.cz/">m.css</a>.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</nav></footer>
|
|
</body>
|
|
</html>
|