# Maintaining

## The basic rules

a Dialect maintainer can do as one's want as far as what one's will do
has no impact on the other dialects.

The following three dialects have ACTIVE maintainers:

FreeBSD

	@lrosenman
	@jiegec

Linux
	
	@dilinger
	@jiegec

NetBSD

	@tnn2
	@jiegec

Darwin

	@jiegec

OpenBSD

	@jiegec

Solaris/OpenIndiana

	@jiegec


If you find a good person who has interested in maintain a dialect
that none maintains, you can invite the person to the lsof-org
organization.

See also https://github.com/lsof-org/lsof/issues/157#issuecomment-941591778 .

## Git

A dialect maintainer must know Git.

### Sophisticated commits

You will change the repository. You will write the code or you will merge
the code submitted by a contributor via pull request.

About your dialect, you can do as you want. However, I recommend you to
accept only SOPHISTICATED commits only. About a change for the common code
between dialect, we accept only sophisticated commits. About a change having
impact on the other dialects, we accept only sophisticated commits.

One sophisticated commit does one thing.
e.g. a commit including a change for adjusting white-spaces and a change for
adding an option is not a sophisticated commit.

* https://github.com/lsof-org/lsof/pull/195#discussion_r825328892
* https://github.com/lsof-org/lsof/pull/208

Sophisticated commits help reviewers.
Understanding sophisticated commits is easy.

https://github.com/lsof-org/lsof/pull/213
This is not a sophisticated commit. Improving the way to hash and fixing
a typo are done in a commit. I didn't have energy to ask the contributor
to split the commit into two.

"Try-and-error" commits should not be merged. It makes the git log of
lsof dirty. Such dirtiness make us hard to read and understand git-log
and to do git-bisect effectively. You can ask the contributor to
squash the commits into one as far as the commits are for doing one
thing; squashed commit should be sophisticated.

### Commit logs

If a change is dialect specific, use `[dialect]` as the prefix of the
header of the commit log like::

   [linux] compile with -Wall option
   [linux] delete unused variables
   [freebsd] cirrus-ci: disabled

We should the force this rule to us and contributors. So we can know
who should review the change/pull request. If no `[dialect]` prefix is
given to a commit, the change may have an impact across dialects; all
we must review the commit.

I have seen contributors write much expiation about their change
at the first comment of their pull request. However, their commit
log is very short. We should ask them to copy the first comment to
the commit log.

## Reviewing and merging

A dialect maintainer has a responsibility to review pull requests that
change the code of one's dialect.

After merging you may have to update two documents:

00DIST

	If a pull request you merged changes user visible aspect of lsof,
	put the change at the end of 00DIST file. You can ask the contributor
	making a pull request to put an entry for the one's change instead.

00CREDITS

	If this is the first time for the contributor to contribute to lsof,
	add one's name to 00CREDITS.

You may have to the contributor to update the lsof.8 man page.
If a pull request fixes the issue already reported, put
`Close #issueNumber` to the first comment of the pull request.

e.g. https://github.com/lsof-org/lsof/pull/199#issue-1193523123

## Testing

Having a test case for a change is nice. The original lsof developed
and maintained by Vic Abell has a test mechanism. However, I started
developing my own test mechanism (the github test mechanism) written
in bash.

About the original test mechanism, see tests/00README.

About the github test mechanism, see tests/case-00-hello.bash .
You can put a test case non-dialect specific, put tests/.
dialects/linux/tests/ is for testing linux specific code.

## Releasing

A dialect maintainer can release a new version of lsof FOR YOUR
DIALECT without getting permission from maintainers of the other
dialects.  So we can work asynchronously.

### Install ksh

The script for making an archive needs ksh.


### Implement "make dist" for your favorite dialect

See https://github.com/lsof-org/lsof/pull/131 how @masatake does for
linux dialect.

Merge the changes.


### Update the version and release date in the source tree if you need

You should update the version and release date in the following files:

- 00DIST
- version
- configure.ac

And then re-generated `docs/manpapage.md` by running `manpage.sh` in `docs` folder.

The version number has following form MAJOR.MINOR.MICRO.  When making a
release, update the version number.  If the change from the last release
is small, increment MICRO. If it is large, increment MINOR.

Merge the changes.

If you just want to make a release for a version already released in
another dialect, you don't need this step. Release the version number.

e.g.

conditions and situations:
@masatake already released 4.94.0 for linux.
No user visible change is committed to our git repo.
You may want to make the same release but for dialect freebsd.

In this case, you can use 4.94.0 as the version number.  If the
condition doesn't meet, use 4.94.1 (or 4.95.0).

### Put a tag with Git

NOTE: this step is an optional if the commit for releasing is already
tagged via another dialect.

The tag you will put should have the same name as the version given in
the step 2.

Do "git tag" like:

  $ git tag 4.95.0-this-is-an-example
  $ git push upstream 4.95.0-this-is-an-example

If you took a mistake, you can delete the tag like:

  $ git tag -d 4.95.0-this-is-an-example
  $ git push upstream :4.95.0-this-is-an-example

### Make the source archive for the release

   $ ./Configure [dialect]
   $ make dist

The archive is put at support/ directory.

Checking whether you can build a lsof executable from the archive is
good idea.

e.g.

   $ cp support/lsof_4.94.0.linux.tar.bz2 /tmp
   $ cd /tmp
   $ tar jxvf lsof_4.94.0.linux.tar.bz2
   $ cd lsof_4.94.0.linux
   $ ./Configure linux
   $ make
   $ make check (if your dialect support the target)

### Visit https://github.com/lsof-org/lsof/releases

1. Click [Draft new release]
2. Choose a tag. Choose with the tag given in the step 3.
3. Fill "Release title". Use the following form lsof-${theVersionNumber}-${dialect}. e.g. lsof-4.94.0-linux
4. Fill "Describe this release". Copy and paste the changes described in 00DIST since the last release in your dialect.
5. Record the release date. Put the date of the release at the end of "Contents" of 00DIST.
	"Contents" is at the beginning of 00DIST.
6. Put the source archive generated step in 4. Click "Attach binaries by dropping them here or selecting them. ", then specify the archive file.
7. Check "This is a pre-release"
8. Click [Publish release]
9. Verify the release

After step 8, the browser may show the page for the release. You can
re-read the description and the source code archives. You can verify
what you did here.

If you find a fault or something, click the [Edit] in the page. You can
update the pre-release.

If you convince it is ready, click the [Edit] in the page, remove the
check at "This is a pre-release", then [Publish release]. The new
version is available at https://github.com/lsof-org/lsof/releases.