Hacktoberfest Week 2

Intro

We're already halfway through October! This week, I focused on finishing up my second issue that I had started working on last week in the Wordpress Openverse Catalog repository.

Using the New Issue Forms Feature

The issue
The pull request

The purpose of this issue was to update two of the issue templates that the repository was using from markdown (.md) to YAML (.yml) by using the new issue forms feature. The new issue forms provide a more user-friendly interface (for those who may not be familiar with markdown syntax) and also allow for form validation. Although the project did not require much setup, it was my first time writing a file in YAML so I first went over the GitHub docs to learn the proper syntax.

Although the issue did not seem too complicated when I first began working on it, I soon encountered a few roadblocks. Thankfully, the code reviewers were all very kind and responded to my commits and questions right away with helpful suggestions and answers.

Roadblock #1

Form fields in issue forms can accept label and description attributes, such as:

 - type: input
    id: source
    attributes:
      label: Source Site
      description: Please provide a link to the Source site that you'd like considered for inclusion on Openverse
    validations:
      required: true

The label (title) and description are styled like the following in issue forms:

However, for the issue I was working on, some "form fields" were more for providing information and did not require user input (they are not really fields, but in the original template, they are styled similar to fields). The only way I could create these fields was by using "type: markdown", which could not accept label or description attributes. Therefore, the code for such a field would look something like:

- type: markdown
    attributes:
      value: |
        ## General Recommendations for implementation
        Modify this section if necessary

        - The script should be in the `openverse_catalog/dags/provider_api_scripts/` directory.

And the output would look like:

As you can see, there is an underline beneath the label and the description also looks different compared to the first example.

Roadblock #2

Another issue I had was that I wanted to combine a form field that wasn't "type: markdown" with markdown text. For example:

In the above, the form field I used was "type: checkboxes". I wanted to style the text that is highlighted using markdown, but I could not find a way to do so unless I used "type: markdown". However, if I did so, then there would be no form validation for the checkboxes, which is a major reason for using the new issue forms feature.

After looking more into the documentation for issue forms and trying different solutions, I asked the code reviewers about this problem. They said that this wasn't a big issue and my code was successfully accepted. In the end, I created two new issue forms, one for Image Provider API Integration Requests and one for New Source Suggestions for Openverse and my work was merged here.

You can see an example of the before and after for the New Source Suggestions form below:

Conclusion

A big takeaway I got from working on this issue was that there are still a lot of limitations in the new issue forms feature. Although markdown issue templates have been around for a while, YAML issue forms are relatively new and still in beta. Personally, I think there could still be some improvements to allow for an easier transition from issue templates to forms and also better support for custom form fields and styling.

In addition, I realized the importance of communicating frequently with the code maintainers. For example, I spent a lot of time researching how to fix the issues I mentioned previously, but it turns out that this was not a big concern for the maintainers.

Overall, I learned a lot from this experience and can't wait to get started on my next pull request.