mirror of
https://github.com/GothenburgBitFactory/taskwarrior.git
synced 2025-07-07 20:06:36 +02:00
reformat to one sentence per line
This commit is contained in:
Dustin J. Mitchell
Tomas Babej
parent
ade706a72e
commit
b1ca5d4cf8
17 changed files with 842 additions and 1052 deletions
|
|
@ -2,18 +2,16 @@
|
|||
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.
|
||||
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.
|
||||
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.
|
||||
|
||||
[](/docs/images/master.png)
|
||||
|
||||
|
|
@ -22,9 +20,9 @@ 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.
|
||||
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.
|
||||
|
||||
[](/docs/images/dev.png)
|
||||
|
||||
|
|
@ -33,53 +31,47 @@ 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.
|
||||
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.
|
||||
|
||||
[](/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.
|
||||
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.
|
||||
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.
|
||||
|
||||
[](/docs/images/release.png)
|
||||
|
||||
Because only releases are merged back, the `master` branch always represent the
|
||||
stable release.
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
|
||||
[](/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.
|
||||
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.
|
||||
Old branches are not retained, but there are tags marking the beginning and end of development on a branch.
|
||||
|
||||
|
||||
## Rebasing
|
||||
|
|
|
|||
|
|
@ -2,9 +2,9 @@
|
|||
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.
|
||||
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:
|
||||
|
||||
|
|
@ -55,9 +55,8 @@ 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.
|
||||
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
|
||||
|
|
@ -68,9 +67,10 @@ provides blinkenlights for test progress.
|
|||
# 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:
|
||||
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
|
||||
|
||||
|
|
@ -94,11 +94,9 @@ 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.
|
||||
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.
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -2,30 +2,27 @@
|
|||
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.
|
||||
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.
|
||||
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
|
||||
|
||||
- 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 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.
|
||||
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 thi
|
||||
|
|
|
|||
|
|
@ -2,45 +2,62 @@
|
|||
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:
|
||||
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.
|
||||
|
||||
- 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.
|
||||
|
||||
- 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.
|
||||
|
||||
- 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.
|
||||
|
|
|
|||
|
|
@ -28,121 +28,123 @@ title: How to Build Taskwarrior
|
|||
$ ./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.
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
* 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.
|
||||
* 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.
|
||||
* 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.
|
||||
* 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.
|
||||
* 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.
|
||||
* 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.
|
||||
* 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.
|
||||
* 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.
|
||||
* 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:
|
||||
|
||||
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.
|
||||
For example, dependencies.t runs through a long list of commands that test dependencies, but do so by using 'add', 'modify', 'done' and 'delete'.
|
||||
|
||||
The tests are written in Python, Bash and C++, and all use TAP.
|
||||
2. 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.
|
||||
|
||||
3. 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.
|
||||
|
||||
4. 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.
|
||||
* 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.
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -2,48 +2,38 @@
|
|||
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.
|
||||
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.
|
||||
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!
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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:
|
||||
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:
|
||||
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
|
||||
|
|
@ -55,8 +45,8 @@ commands you would use on Debian:
|
|||
|
||||
## [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:
|
||||
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'...
|
||||
|
|
@ -68,12 +58,10 @@ repository using git and looking at the development branch:
|
|||
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 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:
|
||||
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
|
||||
|
|
@ -83,46 +71,41 @@ it\'s a good idea to check anyway, so do this:
|
|||
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:
|
||||
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\...
|
||||
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:
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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:
|
||||
First you have to build the program.
|
||||
Do this:
|
||||
|
||||
$ cd taskwarrior.git
|
||||
$ cmake .
|
||||
|
|
@ -159,7 +142,8 @@ 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:
|
||||
The next step is to build the test suite.
|
||||
Do this:
|
||||
|
||||
$ cd test
|
||||
$ make
|
||||
|
|
@ -176,8 +160,7 @@ The next step is to build the test suite. Do this:
|
|||
[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:
|
||||
Now run the test suite, which can take anywhere from 10 - 500 seconds, depending on your hardware and OS:
|
||||
|
||||
$ ./run_all
|
||||
Passed: 8300
|
||||
|
|
@ -187,14 +170,16 @@ on your hardware and OS:
|
|||
Expected failures: 5
|
||||
Runtime: 32.50 seconds
|
||||
|
||||
We are looking for zero failed tests, as shown. This means all is well.
|
||||
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:
|
||||
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
|
||||
|
|
@ -213,8 +198,7 @@ to see which file you changed, stage that file, then commit it:
|
|||
1 file changed, 1 insertion(+)
|
||||
$
|
||||
|
||||
Notice how the commit message looks like this: `Category: Brief description`,
|
||||
which is how the commit messages should look.
|
||||
Notice how the commit message looks like this: `Category: Brief description`, which is how the commit messages should look.
|
||||
|
||||
|
||||
## [6] Make a Patch
|
||||
|
|
@ -228,17 +212,14 @@ Once the commit is made, making a patch is simple:
|
|||
|
||||
## [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.
|
||||
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.
|
||||
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\...
|
||||
Congratulations! Welcome to the wonderful world of open source involvement.
|
||||
Now do it again\...
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue