RFC: Improve developer documentation and learning resources

Development RFCs
1

Hello Everyone,

I am curious to know if people feel the need to have better resources and documentation oriented towards developers and contributors for their respective projects. It gives people the opportunity to contribute more easily and quickly refer to the guides for usual things like how to run tests on the project locally etc so the contributor doesn’t get stumped by all the red on the CI. Some things I can think of that would help contributors unfamiliar with projects across the ecosystem are guides on:

1. Setting Up the Development Environment

  • Objective: Provide a step-by-step guide on how to set up the development environment from scratch.
  • Details: Include necessary software installations, configuration settings, and any prerequisites.

2. Repository Layout

  • Objective: Offer a clear overview of the repository structure.
  • Details: Include descriptions of the main code directories and their purposes, along with any relevant files or configurations.

3. Testing Changes

  • Objective: Demonstrate how to effectively test changes before committing them.
  • Details: Include unit tests, integration tests, and any tools or frameworks used.

4. Other Relevant Topics

  • Objective: Any other areas you believe are essential for developers to know.
  • Details: This could include debugging tips, optimizing code performance, or deep-dives into specific libraries or frameworks used in the project.

For example, Katello developer resources would go into things like:

  1. Spinning up a katello-devel or katello-devel-stable box and starting the rails and webpack server, spinning up a content proxy, spinning up hosts and registering them to development server.

  2. Deeper dive on our API integrations like Pulp, Candlepin and testing changes and upgrades including VCR testing.

  3. Understanding our UI development workflow including legacy angular pages as well as React pages, testing changes and writing tests for those.

  4. Understanding the basic organization of the repository like what code goes where ex: controllers, services, tasks, routes, permissions, tests etc.

We can gauge the interest people have for such resources and if someone would like to volunteer to write some helpful developer documentation for projects they are familiar with.

4 Likes
2

For the Foreman, we have developer docs; all contributions are more than welcome!

2 Likes
3

Those developer docs partly duplicate Foreman :: Contribute, which itself is also a bit outdated.

4

Now a longer comment. I deeply agree with you we need to improve here.

During today’s demo this came up. As I said on the demo, I think it needs a multi layered approach. Many things apply project wide. Those are best documented in Foreman :: Contribute. For example, how various components interact. Foreman and Foreman Proxy can be described from a high level. It wouldn’t make sense to repeat those things in every repository.

Someone mentioned the use of yard so I spent a bit of time to improve its output: Improve yardoc tags for better documentation by ekohl · Pull Request #10193 · theforeman/foreman · GitHub

Another aspect is that developers and users can overlap. Very high level documentation can be used by both since they both want to understand the general workflow. Remember that the best developers are also users and vice versa.

1 Like
5

I once made an effort to render the developer docs and planned to deploy them using GitHub Pages: Render developer documentation by maximiliankolb · Pull Request #10112 · theforeman/foreman · GitHub

2 Likes
6

It would be nice to have a portal like developers.theforeman.org with developer docs published from a single source.

7

Do we know what it would take to get such a central portal running? Hosting, project setup etc?

8

In my experience, building a website isn’t the hardest part. It’s the content.

I’d propose we start with updating Foreman :: Contribute (which is theforeman.org/contribute.md at gh-pages · theforeman/theforeman.org · GitHub).

Some obvious updates are replacing the centos7 development VM with a centos 9 one and the supported Ruby & NPM versions. Near the end we also mention Jenkins as our CI, but that is now mostly GitHub Actions based so we don’t need any more sponsoring of Jenkins nodes now.