gergely/taskwarrior-2.x
1
0
Fork 0
Code Issues Actions Packages Projects Releases 1 Wiki Activity

reformat to one sentence per line

Browse Source
This commit is contained in:
Dustin J. Mitchell
2022-04-21 01:15:17 +00:00
committed by Tomas Babej
parent ade706a72e
commit b1ca5d4cf8
17 changed files with 842 additions and 1052 deletions
Download Patch File Download Diff File Expand all files Collapse all files

135
docs/contrib/first_time.md
View File

@@ -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\...