General Process
===============

There are two official git repos for 'damo' that are hosted on kernel.org[1]
and GitHub[2], respectively.  The two repos are updated and managed directly by
the maintainer.  On the repos, two branches exist: 'master' and 'next'.
Changes first merged in 'next', get tested, and finally merged in 'master', if
the tests show no problem.  So, please base your contributions on 'next' branch
of one of the repos.

For contributions, we support both the email-based workflows like that of Linux
kernel and the GitHub-based workflow.

If you prefer the email-based workflow, send patches, issues, or comments to
sj@kernel.org Cc-ing damon@lists.linux.dev.  It is also recommended to further
Cc linux-mm@kvack.org and/or linux-kernel@vger.kernel.org if you don't mind.
General rules for Linux kernel contribution process[3] are similarly applied.

If you prefer the GitHub workflow, use Pull Requests and Issues features on the
GitHub official repo[2].

The patches and pull requests should have proper 'Signed-off-by:' tags[4] on
the commit messages.  The tag will be considered the same as that of the linux
kernel development process[3].

Note that we had used a GitHub repo under awslabs organization as the official
one[5], but it is no longer the official one[6].

[1] https://https://git.kernel.org/pub/scm/linux/kernel/git/sj/damo.git/
[2] https://github.com/damonitor/damo
[3] https://docs.kernel.org/process/index.html
[4] https://docs.kernel.org/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin
[5] https://github.com/awslabs/damo
[6] https://lore.kernel.org/20240813232158.83903-1-sj@kernel.org


What To Do, First?
==================

Testing First
-------------

If you want to participate in the development but are unsure what to do first,
you could consider running DAMO tests on your system.  It might reveal some
issues in DAMO.  You could also contribute more tests.  You can run the tests
via below command from the root of DAMO.

    $ sudo ./tests/run.sh

If you want to run wider range of tests, or have interests in not only DAMO but
also DAMON, you could also run DAMON tests suite
(https://github.com/damonitor/damon-tests) on your system.  It might reveal some
issues in DAMO or DAMON.

TODO list
---------

There is a list of todo items for DAMO in 'TODO' file of this repo.  If
you don't have specific task to do at the moment, you could consider finding
one from the file.  The list is not well managed at the moment, and the items
may not well explained.  Please feel free to reach out to the original author
of the item for asking details.


Source Files Organiazation
==========================

Source files of the repository is organized in directories as below.

The root of this repository is a place for documents and the executable file,
`damo`.  Users can use `damo` via the executable file.  It is just a symbolic
link to real executable, `src/damon.py`.

`src` directory is for real source files of `damo`.

`tests` directory is for tests of `damo`.  As mentioned on `Testing First`
section above, you can run the tests by running `tests/run.sh` file with `sudo`
permission.  Some tests that not required to run DAMON doesn't really need
`sudo` though.

`packaging` directory contains files for easier PyPI
(https://pypi.org/project/damo/) packaging.  It could contain files for other
packaging systems in future.  If you package `damo` for other packaging systems
and you have your own files for that out of `damo` tree, please feel free to
send PR for maintaining that in the tree, if you prefer to.

`images` directory is for image files that linked on documents.
