GothenburgBitFactory/taskwarrior
1
0
Fork 0
mirror of https://github.com/GothenburgBitFactory/taskwarrior.git synced 2025-06-26 10:54:26 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Bring contributing content from tw.org into dev docs

Browse source
This commit is contained in:
Dustin J. Mitchell 2022-03-05 22:56:53 +00:00 • committed by Tomas Babej
parent 377f517154
commit 07493d5fa6
8 changed files with 674 additions and 180 deletions
Download patch file Download diff file Expand all files Collapse all files

147
DEVELOPER.md
View file

@ -1,146 +1 @@
# How to Build Taskwarrior
## Satisfy the Requirements:
* CMake 3.0 or later
* gcc 7.0 or later, clang 6.0 or later, or a compiler with full C++17 support
* libuuid (if not on macOS)
* gnutls (optional)
* python 3 (optional, for running the test suite)
## Obtain and build code:
```
$ git clone --recursive https://github.com/GothenburgBitFactory/taskwarrior taskwarrior.git
$ cd taskwarrior.git
$ git checkout develop # Latest dev branch
$ git submodule init # This is now done by cmake as a test
$ git submodule update # Update the libhsared.git submodule
$ cmake -DCMAKE_BUILD_TYPE=debug . # debug or release. Default: neither
$ make VERBOSE=1 -j4 # Shows details, builds using 4 jobs
# Alternately 'export MAKEFLAGS=-j 4'
```
## Running Test Suite:
```
$ cd test
$ make VERBOSE=1 # Shows details
$ ./run_all # Runs all tests silently > all.log
$ ./problems # Enumerate test failures in all.log
```
Note that any development should be performed using a git clone, and the
current development branch. The source tarballs do not reflect HEAD, and do
not contain the test suite.
If you send a patch (support@gothenburgbitfactory.org), make sure that patch is made
against git HEAD on the development branch. We cannot apply patches made
against the tarball source, or master.
# General Statement
This file is intended to convey the current efforts, priorities and needs of
the code base. It is for anyone looking for a way to start contributing.
Here are many ways to contribute that may not be obvious:
* Use Taskwarrior, become familiar with it, and make suggestions. There are
always ongoing discussions about new features and changes to existing
features.
* Join us in the #taskwarrior IRC channel on freenode.net or libera.chat.
Many great ideas, suggestions, testing and discussions have taken place
there. It is also the quickest way to get help, or confirm a bug.
* Review documentation: there are man pages, online articles, tutorials and
so on, and these may contain errors, or they may not convey ideas in the
best way. Perhaps you can help improve it. Contact us - documentation is
a separate effort from the code base, and includes all web sites, and all
are available as git repositories.
* Take a look at the bug database, and help triage the bug list. This is a
review process that involves confirming bugs, providing additional data,
information or analysis. Bug triage is very useful and much needed. You
could check to see that an old bug is still relevant - sometimes they are
not.
* Review the source code, and point out inefficiencies, problems, unreadable
functions, bugs and assumptions.
* Fix a bug. For this you'll need C++ and Git skills. We welcome all bug
fixes, provided the work is done well and doesn't create other problems or
introduce new dependencies. We recommend talking to us before starting.
Seriously.
* Add unit tests. Unit tests are possibly the most useful contributions of
all, because they not only improve the quality of the code, but prevent
future regressions, therefore maintaining quality of subsequent releases.
Plus, broken tests are a great motivator for us to fix the causal defect.
You'll need Python skills.
* Add a feature. Well, let's be very clear about this: adding a feature is
not usually well-received, and if you add a feature and send a patch, it
will most likely be rejected. The reason for this is that there are many
efforts under way, in various code branches. There is a very good chance
that the feature you add is either already in progress, or being done in a
way that is more fitting when considering other work in progress. So if
you want to add a feature, please don't. Start by talking to us, and find
out what is currently under way or planned. You might find that we've
already rejected such a feature for some very good reasons. So please
check first, so we don't duplicate effort or waste anyone's time.
* Spread the word. Help others become more effective at managing tasks.
* Encouragement. Tell us what works for you, and what doesn't. Tell us about
your methodology for managing tasks. It's all useful information.
* Request a feature. This not only tells us that you think something is
missing from the software, but gives us insights into how you use it.
Plus, you might get your feature implemented.
# Unit Tests Needed
There are always more unit tests needed. More specifically, better unit tests
are always needed. The convention is that there are four types of unit test:
1. High level tests that exercise large features, or combinations of commands.
For example, dependencies.t runs through a long list of commands that test
dependencies, but do so by using 'add', 'modify', 'done' and 'delete'.
1. Regression tests that ensure certain bugs are fixed and stay fixed. These
tests are named tw-NNNN.t where NNNN refers to the bug number. While it is
not worth creating tests for small fixes like typos, it is for logic
changes.
1. Small feature tests. When small features are added, we would like small,
low-level feature tests named feature.t, with a descriptive name and
focused tests.
1. Code tests. These are tests written in C++ that exercise C++ objects, or
function calls. These are the lowest level tests. It is important that
these kind of tests be extensive and thorough, because the software depends
on this code the most.
The tests are written in Python, Bash and C++, and all use TAP.
## Tests needed
* Take a look at the bug database (https://github.com/GothenburgBitFactory/taskwarrior/issues)
and notice that many issues, open and closed, have the "needsTest" label.
These are things that we would like to see in the test suite, as regression
tests.
All new unit tests should follow the test/template.t standard.
# Patches
Patches are encouraged and welcomed. Either send a pull request on Github or
email a patch to support@taskwarrior.org. A good patch:
* Maintains the MIT license, and does not contain code lifted from other
sources. You will have written 100% of the code in the patch, otherwise
we cannot maintain the license.
* Precisely addresses one issue only.
* Doesn't break unit tests. This means yes, run the unit tests.
* Doesn't introduce dependencies.
* Is accompanied by new or updated unit tests, where appropriate.
* Is accompanied by documentation changes, where appropriate.
* Conforms to the prevailing coding standards - in other words, it should
fit in with the existing code.
A patch may be rejected for violating any of the above rules, and more.
Bad patches may be accepted and modified depending on work load and mood. It
is possible that a patch may be rejected because it conflicts in some way with
plans or upcoming changes. Check with us first, before sinking time and effort
into a patch.
See [Developing Taskwarrior](./docs/contrib).

87
docs/contrib/branching.md Normal file
View file

@ -0,0 +1,87 @@
---
title: Branching Model
---
Software development typically requires a standardized branching model, to
manage complexity and parallel efforts. The branching model can be a source of
confusion for developers, so this document describes how branching is used.
Taskwarrior and Taskserver use the same branching model.
## Git Branching
Git allows arbitrary and low-cost branching, which means that any branching
model can be used. A new Git repository has one branch, the default branch,
named `master`, but even this is not required.
[![master](/docs/images/master.png)](/docs/images/master.png)
No development occurs on the `master` branch.
## Development Branch
A development branch is created from the `master` branch, and work proceeds on
the development branch. Development branches are pushed to the server. Note that
there are no changes on `master` - all work is done on dev branches.
[![dev](/docs/images/dev.png)](/docs/images/dev.png)
All work on dev branches is pushed to the server.
## Topic Branch
A topic branch is created from a dev branch. This can be a useful way to manage
parallel efforts on a single development machine. Topic branches are also useful
for merging in submitted patches, because the patch can be merged, tested and
corrected independently of other efforts before being merged and pushed. A topic
branch is ideal for storage of changes before an eventual merge back to the
development branch.
[![topic](/docs/images/topic.png)](/docs/images/topic.png)
No topic branches are pushed to the server, they are kept local to the
development machine. They are private, and therefore hidden from the server.
## Release
When a release is made, the development branch is merged back to the `master`
branch, and a tag is applied that indicates which commit represents the release.
[![release](/docs/images/release.png)](/docs/images/release.png)
Because only releases are merged back, the `master` branch always represent the
stable release.
## New Development Branches
Immediately after a release, one or more new branches are created. Typically
after a major \'1.0.0\' release, there will be two branches created. First the
\'1.0.1\' branch is a patch development branch, intended to be used if an
emergency patch is required. It therefore sits unused until an emergency arises.
No work is performed on a patch development branch.
The second branch, with the higher release number is the development branch for
fixes and features. This is where all the work occurs. Any fix made on the
development branch can be cherry-picked onto the patch branch, if necessary.
[![dev2](/docs/images/dev2.png)](/docs/images/dev2.png)
To address the confusion around branching, namely determining which branch is
active. the answer is that the highest numbered branch is the one that patches
should be applied to.
## Old Branches
Old branches are not retained, but there are tags marking the beginning and end
of development on a branch.
## Rebasing
No.

104
docs/contrib/build.md Normal file
View file

@ -0,0 +1,104 @@
---
title: How To Build Taskwarrior
---
This is for developers. Specifically those who know how to use tools, satisfy
dependencies, and want to set up a development environment. It is not
user-friendly.
You\'ll need these tools:
- [git](https://git-scm.com/)
- [cmake](https://cmake.org)
- make
- C++ compiler, currently gcc 4.7+ or clang 3.3+ for full C++11 support
- Python 2.7 or later (for tests)
- Bash (for tests)
You\'ll need these libraries:
- [GnuTLS](https://www.gnutls.org/)
- libuuid (unless on Darwin/BSD)
Specifically the development versions, `uuid-dev` on Debian, for example.
# Cloning the Repo
$ git clone https://github.com/GothenburgBitFactory/taskwarrior.git taskwarrior.git
# Building the Stable Version
The master always represents the more recently released version, and should be
your preferred choice.
$ cd taskwarrior.git
$ git checkout master # Master is the stable branch.
$ cmake -DCMAKE_BUILD_TYPE=release . # 'release' for performance.
$ make # Just build it.
# Building the Dev Branch
The dev branch is always the highest numbered branch, in this example, `2.6.0`.
$ cd taskwarrior.git
$ git checkout 2.6.0 # Dev branch
$ git submodule init # Register submodule
$ git submodule update # Get the submodule
$ cmake -DCMAKE_BUILD_TYPE=debug . # debug or release, default: neither
$ make VERBOSE=1 # Shows details
Build the debug type if you want symbols in the binary.
# Running the Test Suite
There are scripts to facilitate running the test suite. In particular, the
[vramsteg](https://gothenburgbitfactory.org/projects/vramsteg) utility
provides blinkenlights for test progress.
$ cd taskwarrior.git/test
$ make VERBOSE=1 # Shows details
$ ./run_all # Runs all tests silently > all.log
$ ./problems # Find errors in all.log
# Submitting a Patch
Talk to us first - make sure you are working on something that is wanted.
Patches will not be applied simply because you did the work. Remember the
various forms of documentation involved, and the test suite. Work on the dev
branch, not `master`. When you are are ready to submit, do this:
$ git commit
Follow the standard form for commit messages, which looks like this:
Category: Short message
- Details
- Details
Here is a good example:
TW-1636: UUID with numeric-only first segment is not parsed properly
- Switched Nibbler::getUUID to Nibbler::getPartialUUID, which caused partial
UUID matching to fail sometimes.
- Changed precedence to search for UUID before ID, which solves the numeric
UUID problem.
Create the patch using this:
$ git format-patch HEAD^
Mail the patch to <taskwarrior-dev@googlegroups.com> or attach it to the
appropriate ticket in the [bug
tracker](https://github.com/GothenburgBitFactory/taskwarrior/issues). If you do
the latter, make sure someone knows about it, or it could go unnoticed.
Expect feedback. It is unlikely your patch will be accepted unmodified. Usually
this is because you violated the coding style, worked in the wrong branch, or
*forgot* about documentation and unit tests.

31
docs/contrib/coding_style.md Normal file
View file

@ -0,0 +1,31 @@
---
title: Coding Style
---
The coding style used for the Taskwarrior, Taskserver, and other codebases is
deliberately kept simple and a little vague. This is because there are many
languages involved (C++, C, Python, sh, bash, HTML, troff and more), and
specіfying those would be a major effort that detracts from the main focus which
is improving the software.
Instead, the general guideline is simply this:
Make all changes and additions such that they blend in perfectly with the
surrounding code, so it looks like only one person worked on the source, and
that person is rigidly consistent.
To be a little more explicit, the common elements across the languages are:
- Indent code using two spaces, no tabs
- With Python, follow [PEP8](https://www.python.org/dev/peps/pep-0008/) as
much as possible
- Surround operators and expression terms with a space
- No cuddled braces
- Class names are capitalized, variable names are not
We target Python 2.7 so that our test suite runs on the broadest set of
platforms. This will likely change in the future and 2.7 will be dropped.
We can safely target C++11 because all the default compilers on our supported
platforms are ready. Feel free to use C++14 and C++17 provided that all build
platforms support this.

47
docs/contrib/contribute.md Normal file
View file

@ -0,0 +1,47 @@
---
title: Contributing to Taskwarrior
---
Help is needed in all areas of Taskwarrior development - design, coding,
testing, support and marketing. Applicants must be friendly. Perhaps you are
looking to help, but don\'t know where to start. You can of course [email
us](mailto:taskwarrior-dev@googlegroups.com) but take a look at this list.
Perhaps you have skills we are looking for, here are ways you may be able to
help:
- Use Taskwarrior, become familiar with it, and make suggestions. We get great
feedback from both new users and veteran users. New users have a fresh
approach that we can no longer achieve, while veteran users develop clever
and crafty ways to use the product.
- Report bugs and odd behavior when you see it. We don\'t necessarily know
it\'s broken, unless you tell us.
- Suggest enhancements. We get lots of these, and it\'s great. Some really
good ideas have been suggested and implemented. Sure, some are out of scope,
or plain crazy, but the stream of suggestions is fascinating to think about.
- Participate in the [bug
tracking](https://github.com/GothenburgBitFactory/taskwarrior/issues)
database, to help others and maybe learn something yourself.
- Help [triage](/docs/triage) the issues list.
- Join the IRC channel \#taskwarrior on freenode.net and help answer some
questions.
- Join either the
[developer-mailinglist](https://groups.google.com/forum/#!forum/taskwarrior-dev)
or
[user-mailinglist](https://groups.google.com/forum/#!forum/taskwarrior-user)
(or both) and participate.
- Proofread the documentation and man pages.
- Improve the documentation.
- Improve the man pages.
- Help improve the tutorials. Make your own tutorial.
- Confirm a bug. Nothing gets fixed without confirmation.
- Refine a bug. Provide relevant details, elaborate on the behavior.
- Fix a bug. Send a patch. You\'ll need C++ skills for this.
- Write a unit test. Improve an existing unit test.
- Spread the word. Help others become more effective at managing tasks. Share
your methodology, to inspire others.
- Encouragement. Tell us what works for you, and what doesn\'t. It\'s all
good.
- Donate! Help offset costs.
Please remember that we need contributions from all skillsets, however small.
Every contribution helps.

148
docs/contrib/development.md Normal file
View file

@ -0,0 +1,148 @@
---
title: How to Build Taskwarrior
---
## Satisfy the Requirements:
* CMake 3.0 or later
* gcc 7.0 or later, clang 6.0 or later, or a compiler with full C++17 support
* libuuid (if not on macOS)
* gnutls (optional)
* python 3 (optional, for running the test suite)
## Obtain and build code:
```
$ git clone --recursive https://github.com/GothenburgBitFactory/taskwarrior taskwarrior.git
$ cd taskwarrior.git
$ git checkout develop # Latest dev branch
$ git submodule init # This is now done by cmake as a test
$ git submodule update # Update the libhsared.git submodule
$ cmake -DCMAKE_BUILD_TYPE=debug . # debug or release. Default: neither
$ make VERBOSE=1 -j4 # Shows details, builds using 4 jobs
# Alternately 'export MAKEFLAGS=-j 4'
```
## Running Test Suite:
```
$ cd test
$ make VERBOSE=1 # Shows details
$ ./run_all # Runs all tests silently > all.log
$ ./problems # Enumerate test failures in all.log
```
Note that any development should be performed using a git clone, and the
current development branch. The source tarballs do not reflect HEAD, and do
not contain the test suite.
If you send a patch (support@gothenburgbitfactory.org), make sure that patch is made
against git HEAD on the development branch. We cannot apply patches made
against the tarball source, or master.
# General Statement
This file is intended to convey the current efforts, priorities and needs of
the code base. It is for anyone looking for a way to start contributing.
Here are many ways to contribute that may not be obvious:
* Use Taskwarrior, become familiar with it, and make suggestions. There are
always ongoing discussions about new features and changes to existing
features.
* Join us in the #taskwarrior IRC channel on freenode.net or libera.chat.
Many great ideas, suggestions, testing and discussions have taken place
there. It is also the quickest way to get help, or confirm a bug.
* Review documentation: there are man pages, online articles, tutorials and
so on, and these may contain errors, or they may not convey ideas in the
best way. Perhaps you can help improve it. Contact us - documentation is
a separate effort from the code base, and includes all web sites, and all
are available as git repositories.
* Take a look at the bug database, and help triage the bug list. This is a
review process that involves confirming bugs, providing additional data,
information or analysis. Bug triage is very useful and much needed. You
could check to see that an old bug is still relevant - sometimes they are
not.
* Review the source code, and point out inefficiencies, problems, unreadable
functions, bugs and assumptions.
* Fix a bug. For this you'll need C++ and Git skills. We welcome all bug
fixes, provided the work is done well and doesn't create other problems or
introduce new dependencies. We recommend talking to us before starting.
Seriously.
* Add unit tests. Unit tests are possibly the most useful contributions of
all, because they not only improve the quality of the code, but prevent
future regressions, therefore maintaining quality of subsequent releases.
Plus, broken tests are a great motivator for us to fix the causal defect.
You'll need Python skills.
* Add a feature. Well, let's be very clear about this: adding a feature is
not usually well-received, and if you add a feature and send a patch, it
will most likely be rejected. The reason for this is that there are many
efforts under way, in various code branches. There is a very good chance
that the feature you add is either already in progress, or being done in a
way that is more fitting when considering other work in progress. So if
you want to add a feature, please don't. Start by talking to us, and find
out what is currently under way or planned. You might find that we've
already rejected such a feature for some very good reasons. So please
check first, so we don't duplicate effort or waste anyone's time.
* Spread the word. Help others become more effective at managing tasks.
* Encouragement. Tell us what works for you, and what doesn't. Tell us about
your methodology for managing tasks. It's all useful information.
* Request a feature. This not only tells us that you think something is
missing from the software, but gives us insights into how you use it.
Plus, you might get your feature implemented.
# Unit Tests Needed
There are always more unit tests needed. More specifically, better unit tests
are always needed. The convention is that there are four types of unit test:
1. High level tests that exercise large features, or combinations of commands.
For example, dependencies.t runs through a long list of commands that test
dependencies, but do so by using 'add', 'modify', 'done' and 'delete'.
1. Regression tests that ensure certain bugs are fixed and stay fixed. These
tests are named tw-NNNN.t where NNNN refers to the bug number. While it is
not worth creating tests for small fixes like typos, it is for logic
changes.
1. Small feature tests. When small features are added, we would like small,
low-level feature tests named feature.t, with a descriptive name and
focused tests.
1. Code tests. These are tests written in C++ that exercise C++ objects, or
function calls. These are the lowest level tests. It is important that
these kind of tests be extensive and thorough, because the software depends
on this code the most.
The tests are written in Python, Bash and C++, and all use TAP.
## Tests needed
* Take a look at the bug database (https://github.com/GothenburgBitFactory/taskwarrior/issues)
and notice that many issues, open and closed, have the "needsTest" label.
These are things that we would like to see in the test suite, as regression
tests.
All new unit tests should follow the test/template.t standard.
# Patches
Patches are encouraged and welcomed. Either send a pull request on Github or
email a patch to support@taskwarrior.org. A good patch:
* Maintains the MIT license, and does not contain code lifted from other
sources. You will have written 100% of the code in the patch, otherwise
we cannot maintain the license.
* Precisely addresses one issue only.
* Doesn't break unit tests. This means yes, run the unit tests.
* Doesn't introduce dependencies.
* Is accompanied by new or updated unit tests, where appropriate.
* Is accompanied by documentation changes, where appropriate.
* Conforms to the prevailing coding standards - in other words, it should
fit in with the existing code.
A patch may be rejected for violating any of the above rules, and more.
Bad patches may be accepted and modified depending on work load and mood. It
is possible that a patch may be rejected because it conflicts in some way with
plans or upcoming changes. Check with us first, before sinking time and effort
into a patch.

244
docs/contrib/first_time.md Normal file
View file

@ -0,0 +1,244 @@
---
title: How to become an Open Source Contributor
---
Welcome, potential new Open Source contributor! This is a guide to show you
exactly how to make a contribution, and will lead you through the entire
process.
There are many people who wish to start contributing, but don\'t know how or
where to start. If this might be the case, then please read on, this guide is
for you. Because we want you to join in the fun with Open Source - it can be fun
and rewarding, improve your skills, or just give you a way to contribute back to
a project.
Where else can you combine the thrill of typing in a darkened room with the
kindhearted love of an internet forum? Just kidding!
The goal of this document is to give you the ability to make your first
contribution, and encourage you to make a second, by showing you how simple it
is. Perhaps confidence and a little familiarity with the process are all you
need to get started.
We\'re going to pick the smallest contribution of all - a typo fix. While this
may be a very small improvement, it is nevertheless a wanted improvement, and
will be welcomed. Fixes such as this happen many times a day. Similar work on
new features, new documents, rewriting help, refactoring code, fixing bugs and
improving performance all combine to make a project grow and improve.
Making a bigger change also is certainly an option, but the focus here is on
going through the procedure, which is somewhat independent from the nature of
the change. The steps are numbered, and it all fits on this one page. Get all
the way to the end, and you will be an open source contributor.
## [1] Development Environment Setup
In order to build and test software, you need a development environment. That\'s
just a term that means you need certain tools installed before proceeding. Here
are the tools that Taskwarrior needs:
- Compiler: GCC 4.7 or newer, or Clang 3.4 or newer.
- Libraries: GnuTLS, and libuuid
- Tools: Git, CMake, make, Python
The procedure for installing this software is OS-dependent, but here are the
commands you would use on Debian:
$ sudo apt-get install gcc
$ sudo apt-get install libgnutls28-dev
$ sudo apt-get install uuid-dev
$ sudo apt-get install git
$ sudo apt-get install cmake
$ sudo apt-get install make
## [2] Get the Code
Now you have the tools, next you need the code. This involves cloning the
repository using git and looking at the development branch:
$ git clone --recursive -b 2.6.0 https://github.com/GothenburgBitFactory/taskwarrior.git taskwarrior.git
Cloning into 'taskwarrior.git'...
remote: Counting objects: 55345, done.
remote: Compressing objects: 100% (12655/12655), done.
remote: Total 55345 (delta 44868), reused 52340 (delta 42437)
Receiving objects: 100% (55345/55345), 25.04 MiB | 7.80 MiB/s, done.
Resolving deltas: 100% (44868/44868), done.
Checking connectivity... done.
$
The URL for the repository was obtained from looking around on
<https://github.com/GothenburgBitFactory> where several repositories are public,
including the one for this web site.
The clone command above puts you on the right branch, so no need to switch. But
it\'s a good idea to check anyway, so do this:
$ cd taskwarrior.git
$ git branch -a
* 2.6.0
remotes/origin/2.6.0
remotes/origin/HEAD -> origin/2.6.0
remotes/origin/master
$
Here we see that 2.6.0 is the highest-numbered branch, and therefore the current
development branch. If there were a higher numbered branch, you would want to
use that by doing this:
$ git checkout 2.7.0
Here\'s a thought - if this page does not show the latest branch names, then,
you know, you could fix that\...
## [3] Fix Something
Now that you have the code, find something to fix. This may be the hardest step,
but knowing how many typos there are in the source code and docs, it shouldn\'t
take long to find one. Try looking in the files in these directories:
- `taskwarrior.git/doc/man`
- `taskwarrior.git/scripts`
- `taskwarrior.git/src`
- `taskwarrior.git/test`
It also doesn\'t need to be a typo, it can instead be a poorly-worded sentence,
or one that could be more clear. You\'ll find something, whether it is jargon,
mixed tenses, mistakes, or just plain wrong.
Then fix it, using a text editor. Try to make the smallest possible change to
achieve what you want, because smaller changeѕ are easier to verify and approve,
and no reviewer wants to receive a large change to approve.
## [4] Run the Test Suite
Taskwarrior has an extensive test suite to prove that things are still working
as expected. You\'ll need to build the program and run this test suite in order
to prove to yourself that your fix is good. It may seem like building the
program is overkill, if you only make a small change, but no, it is not. The
test suite is there to save you from submitting a bad change, and to save
Taskwarrior from any mistakes you make.
First you have to build the program. Do this:
$ cd taskwarrior.git
$ cmake .
-- The C compiler identification is ...
-- The CXX compiler identification is ...
-- Check for working C compiler: ...
...
-- Configuring done
-- Generating done
-- Build files have been written to: /home/user/taskwarrior.git
$
$ make
Scanning dependencies of target columns
Scanning dependencies of target task
Scanning dependencies of target commands
[ 2%] Building CXX object src/columns/CMakeFiles/columns.dir/ColDepends.cpp.o
[ 2%] Building CXX object src/columns/CMakeFiles/columns.dir/Column.cpp.o
[ 2%] Building CXX object src/CMakeFiles/task.dir/CLI2.cpp.o
...
[100%] Linking CXX executable task
[100%] Linking CXX executable lex
[100%] Linking CXX executable calc
[100%] Built target lex_executable
[100%] Built target task_executable
[100%] Built target calc_executable
$
If the above commands worked, there will be a binary, which you can find:
$ ls -l src/task
-rwxr-xr-x 1 user group Mar 25 18:43 src/task
The next step is to build the test suite. Do this:
$ cd test
$ make
[ 14%] Built target task
[ 25%] Built target columns
[ 45%] Built target commands
Scanning dependencies of target variant_subtract.t
Scanning dependencies of target variant_partial.t
Scanning dependencies of target variant_or.t
...
[ 98%] Built target i18n.t
[100%] Linking CXX executable view.t
[100%] Built target view.t
Now run the test suite, which can take anywhere from 10 - 500 seconds, depending
on your hardware and OS:
$ ./run_all
Passed: 8300
Failed: 0
Unexpected successes: 0
Skipped: 3
Expected failures: 5
Runtime: 32.50 seconds
We are looking for zero failed tests, as shown. This means all is well.
## [5] Commit the Change
Now you\'ve made a change, built and tested the code. The next step is to commit
the change locally. This example assumes you fixed a typo in the man page. Check
to see which file you changed, stage that file, then commit it:
$ cd taskwarrior.git
$ git status
On branch 2.6.0
Your branch is up-to-date with 'origin/2.6.0'.
Changes not staged for commit:
(use "git add ..." to update what will be committed)
(use "git checkout -- ..." to discard changes in working directory)
modified: doc/man/task.1.in
no changes added to commit (use "git add" and/or "git commit -a")
$ git add doc/man/task.1.in
$ git commit -m 'Docs: corrected typo in the main man page'
[2.6.0 ddbb07e] Docs: corrected typo in the main man page
1 file changed, 1 insertion(+)
$
Notice how the commit message looks like this: `Category: Brief description`,
which is how the commit messages should look.
## [6] Make a Patch
Once the commit is made, making a patch is simple:
$ git format-patch HEAD^
0001-Docs-corrected-typo-in-the-main-man-page.patch
$
## [7] Submit the Patch
Finally you just need to email that patch file to
`taskwarrior-dev@googlegroups.com`. You will need to attach it to an email, and
not just paste it in, because the mail client will probably mess with the
contents, wrapping lines etc, which can make it unusable.
What happens next is that a developer will take your patch and study it, to
ascertain whether it really does fix something that is broken. If there is a
problem, you\'ll hear back with some gentle, constructive criticism. If the
problem is small, it might just get fixed. Then your patch is applied, tested,
and if all looks well, pushed to the public repository, and included in the the
next release. Your name will go into the AUTHORS file, and you will be thanked.
Congratulations! Welcome to the wonderful world of open source involvement. Now
do it again\...

46
docs/index.md
View file

@ -1,37 +1,15 @@
## Welcome to GitHub Pages
---
title: Taskwarrior Development Documentation
---
You can use the [editor on GitHub](https://github.com/djmitche/taskwarrior/edit/dev-docs/docs/index.md) to maintain and preview the content for your website in Markdown files.
This site contains the _development_ documentation for Taskwarrior.
For all other documenation, see https://taskwarrior.org.
Whenever you commit to this repository, GitHub Pages will run [Jekyll](https://jekyllrb.com/) to rebuild the pages in your site, from the content in your Markdown files.
## Contributing to Taskwarrior
### Markdown
Markdown is a lightweight and easy-to-use syntax for styling your writing. It includes conventions for
```markdown
Syntax highlighted code block
# Header 1
## Header 2
### Header 3
- Bulleted
- List
1. Numbered
2. List
**Bold** and _Italic_ and `Code` text
[Link](url) and ![Image](src)
```
For more details see [Basic writing and formatting syntax](https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax).
### Jekyll Themes
Your Pages site will use the layout and styles from the Jekyll theme you have selected in your [repository settings](https://github.com/djmitche/taskwarrior/settings/pages). The name of this theme is saved in the Jekyll `_config.yml` configuration file.
### Support or Contact
Having trouble with Pages? Check out our [documentation](https://docs.github.com/categories/github-pages-basics/) or [contact support](https://support.github.com/contact) and we’ll help you sort it out.
* [How to become an Open Source Contributor](./contrib/first_time)
* [Contributing to Taskwarrior](./contrib/contribute)
* [Developing Taskwarrior](./contrib/development)
* [Building Taskwarrior](./contrib/build)
* [Coding Style](./contrib/coding_style)
* [Branching Model](./contrib/branching)