-
Notifications
You must be signed in to change notification settings - Fork 9
Draft of CONTRIBUTING.md
This file will contain a draft of the taskw-dart project's CONTRIBUTING.md.
Once the information here is improved, and I am working on the main repo's layout of documentation, I will try to move sections of these notes there.
We plan to point the project's CONTRIBUTING.md to this wiki page.
There is currently no intention to review, accept, or merge pull requests. There are several factors obstructing this, and considering those factors is not scheduled.
Please try to limit issue threads to one topic.
When appropriate, please indicate actual behavior and expected behavior.
Yes please, I want to know about bugs. All I have in return is karma and gratitude, please disregard the grumpiness if you catch me in a grumpy mood.
Okay, it's good to get feature requests, but keep all of the following in mind.
First, a few quotes from the project I am not affiliated with: https://taskwarrior.org/docs/advice.html.
There is a fine line between "richly-featured" and "bloated". There may not be a line at all.
What you keep out of a project is just as important as what you allow in to a project.
- 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.
- 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.
At any rate, the above quotes helped me to construct a note about feature requests for the current project.
A feature request is sometimes associated with an underlying workflow, or something like an "XY problem". If the feature request is possibly very particular to the user's workflow, or even just seems to be non-trivial to design, implement and maintain, we may want to look for solutions that are easier to add to the project, or lend themselves to being general in a way that solves many problems at once.
So I do want to hear feature requests, it could be exactly what we need, or it may motivate another solution that solves many problems.
It's possible I've had the same problem as you, and did not think of that feature request, or the discussion could help in getting the problem solved sooner.
I understand there is some notion of "bisect" in programming, I think CS students learn about this. You may have seen the idea applied in the notion of "git bisect". In general, I think it means to recursively cut a problem in half. It has some mathematical properties like being tied to the logarithm function, which grows very slowly, and <waves hand> therefore bisecting is very fast.
In our context, of long task lists, I think even the Taskwarrior project may in some issues suggest users bisect their task data to find where it is broken. Just chop your data in two, see which one is still broken, and recurse. Potentially this leads to a single task that breaks. And because of those nice mathematical properties, it takes very few iterations to get there.
However. This doesn't have a direct translation in this app.
One application would be if you were having an issue with data coming from a self-hosted server, you could bisect the server's tx.data file.
The export feature was recently added to the project. Once an
import feature is added, potentially that could help with bisecting
a list of tasks that the app is having an issue with.
One almost imagines the app should know how to bisect for the user. But I think the real issue there is, as soon as the app encounters a task that is going to cause an error, it should present the error in a useful way to the user. Unfortunately, this is not yet done, but is prioritized, though I don't have an estimate on how much effort it will be.
Although I am not accepting PRs at this time, you may want to interact with the code base anyways, to more quickly find the cause of a problem, or research why some feature requests would be easier, etc.
I really hope to improve the project and app so that users are less likely to consider debugging when they run into a bug. Ideally, more bugs are caught in more obvious ways, and displayed in some straight-forward way to user, or even logged, additionally.
If you want to run the app interactively, either in a connected mobile device, or an emulator, or even as a desktop app, please see the brief notes at https://github.com/bradyt/taskw-dart/blob/main/task/README.md#install-or-run-app-from-source-code.
If you are trying to debug the iOS app, and you are not running macOS, I expect most features are the same if you debug instead with Android, Windows or Linux.
When I am doing interactive debugging, I usually use my live list of tasks, at a self-hosted Taskserver. If I am actually trying to deal with something that is broken, I also have a testing account at that same Taskserver.
You can also debug a Taskserver on localhost. Please see the fixture/ directory. Note that localhost may not be visible to connected devices.
EDIT: New notes at https://github.com/bradyt/taskw-dart/wiki/Running-Taskserver-locally.
The localhost fixture is used in some of the Github Action CI unit tests.
I've been looking at refactoring those localhost scripts so that they can be imported as a Dart library, possibly making tests for some syncing-related issues easier to write.