Daily pages - February 16, 2022

Last night I had a bit of a brainstorm about the openartifacts.com database.

In the interest of keeping the data openly available and easy to change, my thinking is that the data would be stored in individual files, one for each record. Each file would be something easily edited, like a YAML file, or many a JSON file (though that seems more difficult to learn), and then every 24 hours or so, a process would read in each file and build a database (probably MySQL or MariaDB) from the data. That way, to make changes to the data, you need only edit text files and wait for the next upload.

I’m thinking that the files would just be named in numerical order. The filename would become part of the database record and displayed in the data results so if you saw an error in a particular record, you could track down the file pretty quickly and fix it.

I’m not sure exactly what the fields should be for the database, but it would include these so far:

• project name
• project website
• repository URL (the Github, Gitlab or other system storing the project. This might need to be more complex. For example, there is an HTTPS and a SSH connection available in Github and Gitlab, so we may need multiple fields.)
• maintainer’s name
• maintainer’s contact (again, this might vary, so we might need multiple fields for say, an email address, a twitter handle, a facebook account, and so on.)
• project description
• project image
• help wanted URL (this is a link to a standardized file that lists help that is needed for the project. I’m not 100% sure what that looks like yet, but it would likely be a list of issues that need to be completed (work that needs doing), and people could figure out if they can help as part of the search they’re doing.)
• issues api (this would be an alternative for folks who are using a repository service like Gitlab, where they enter issues into the issues database and we can query that source for work that needs doing.)

The help wanted file should be easy to edit with the idea that if someone completes a task, they can remove it from the list. And if they identified something new that needs to be done, they can add it. I don’t think it should be the responsibility of the project maintainer only.

I feel like issues should be tagged, of Github calls them “labels”. The “good first issue” tag is one that comes to mind, but the more these are tagged, the better we can help people find projects by searching for help wanted rather than project type right away. So, I think we’ll want a taxonomy of sorts to help projects keep a consistent set of tags. With that in mind, the list shouldn’t be too long.

In Github, you have a choice between reporting a bug and making a feature request

Here’s a list I’m pulling from some example projects on Github. In these descriptions, PR means “pull request”:

• abandoned (Author has abandoned this PR or issue.)
• async (Everything related to async rendering)
• breaking (!! BREAKING CHANGES !! All breaking changes go under major release.)
• bug (Bug related to code base, behavior, displaying, etc.)
• dependencies (Pull requests that update a dependency file)
• docs (Issue or PR is related to documentation.)
• frozen (Progress is temporarily frozen until resolving the specific issue.)
• github_actions (Pull requests that update Github_actions code)
• good first issue (Issue or PR is friendly to new contributors: easy and simple.)
• has-pr (This issue already has PR.)
• help-wanted (We need help to resolve this issue or PR.)
• improvement (A PR that make small changes for improving UX, performance, readability, etc)
• needs doc update (Updates to relevant section of documentation is required.)
• new-feature (A PR that implement feature (section, specific behavior, etc).)
• proposal (An issue (rarely PR) for feature-requests, ideas, etc)
• question (Issue is a question, feedback, report or thanksgiving.)
• released (Released issues and PRs)
• review-required (PR needs testing/reviews.)
• submodules (Pull requests that update Submodules code)
• translations (Everything related to translations)
• under-discussion (This issue/PR needs more community discussion.)
• wontfix (Will not be fixed. Current behavior is not going to be changed.)

These labels are clearly for use in open source software projects, and they may not all be appropriate for an open artifacts project. I appears that in Gitlab and Github, you can define the labels that make the most sense for your project. So I think it makes sense that I suggest a basic list of labels for OA projects.

In Gitlab, the default “suggested” list is:

• bug
• confirmed
• critical
• discussion
• documentation
• enhancement
• suggestion
• support

What occurs to me for a OA list of labels is:

• good first issue
• improvement
• translations
• research

I’m not sure, now that I try to make a list. I want to add things like “writing” but that seems too vague. As an OA project, the idea is to help the project grow toward greater complexity, and that might mean really rethinking things. So maybe “rethinking” is a possible label. I could see “editing” as a possible task. So rather than overthink this, I’m going to look at my existing projects and try to add issues to them.