From 07493d5fa6a221c7a80d8518da03b87dcab4bb9e Mon Sep 17 00:00:00 2001 From: "Dustin J. Mitchell" Date: Sat, 5 Mar 2022 22:56:53 +0000 Subject: [PATCH] Bring contributing content from tw.org into dev docs --- DEVELOPER.md | 147 +-------------------- docs/contrib/branching.md | 87 +++++++++++++ docs/contrib/build.md | 104 +++++++++++++++ docs/contrib/coding_style.md | 31 +++++ docs/contrib/contribute.md | 47 +++++++ docs/contrib/development.md | 148 +++++++++++++++++++++ docs/contrib/first_time.md | 244 +++++++++++++++++++++++++++++++++++ docs/index.md | 46 ++----- 8 files changed, 674 insertions(+), 180 deletions(-) create mode 100644 docs/contrib/branching.md create mode 100644 docs/contrib/build.md create mode 100644 docs/contrib/coding_style.md create mode 100644 docs/contrib/contribute.md create mode 100644 docs/contrib/development.md create mode 100644 docs/contrib/first_time.md diff --git a/DEVELOPER.md b/DEVELOPER.md index 8719a0a32..8bc4d432d 100644 --- a/DEVELOPER.md +++ b/DEVELOPER.md @@ -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). diff --git a/docs/contrib/branching.md b/docs/contrib/branching.md new file mode 100644 index 000000000..6cb8d80e9 --- /dev/null +++ b/docs/contrib/branching.md @@ -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. diff --git a/docs/contrib/build.md b/docs/contrib/build.md new file mode 100644 index 000000000..a980674f9 --- /dev/null +++ b/docs/contrib/build.md @@ -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 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. diff --git a/docs/contrib/coding_style.md b/docs/contrib/coding_style.md new file mode 100644 index 000000000..59c510d0d --- /dev/null +++ b/docs/contrib/coding_style.md @@ -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. diff --git a/docs/contrib/contribute.md b/docs/contrib/contribute.md new file mode 100644 index 000000000..bb4852679 --- /dev/null +++ b/docs/contrib/contribute.md @@ -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. diff --git a/docs/contrib/development.md b/docs/contrib/development.md new file mode 100644 index 000000000..f89822dbe --- /dev/null +++ b/docs/contrib/development.md @@ -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. diff --git a/docs/contrib/first_time.md b/docs/contrib/first_time.md new file mode 100644 index 000000000..0cd6b5fee --- /dev/null +++ b/docs/contrib/first_time.md @@ -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 + 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\... diff --git a/docs/index.md b/docs/index.md index 8bbb17d42..e4f92ab76 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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)