Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Template for design docs #601

Draft
wants to merge 4 commits into
base: main
Choose a base branch
from
Draft

Template for design docs #601

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
46e89a8
WIP: Initial attempt of a template, plus adapting Ruby design to it
brunoapimentel Aug 15, 2024
eea2b4d
WIP: Getting rid of the Description section
brunoapimentel Aug 15, 2024
ac37672
WIP: Improve the template and adapt the Ruby design to match it
brunoapimentel Aug 20, 2024
6d8d4a9
WIP: Added the Go 1.21 toolchains design as an example
brunoapimentel Aug 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions docs/designs/0000-template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# Title

Updated by: [0000-this-doc-does-not-exist]()
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want to have back links too? I.e. "Updates: 9999-this-doc-does-not-exist"

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, we do.


Obsoleted by: [0000-this-doc-does-not-exist]()

*(these sections should only be added when necessary, and should always include the links to the relevant documents)*

## Introduction

This section should bring a short summary of what this document is covering, the main points it is going to describe, and why it is important. Ideally should be kept under two paragraphs.

## Context [optional]

Explains the context outside the mere technical aspects of the design that existed when it was written. It must make clear what other influences where at play that affected the decisions that were taken. In case there is nothing relevant to mention about the context, this section can be skipped.

## [Free-form sections]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I responded to the Go sample, I don't think this main H2 section should be free-form, its subsections sure can be.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's concentrate this discussion in this thread.


The actual content of the design should be placed under one or more sections that can be named freely. Note that they should be level 2 headings (H2), but each section can also be subdivided by nested headings (H3, H4, H5 or H6) if needed. Only a single level 1 heading (H1) should exist, and it is strictly reserved for the title.
Comment on lines +18 to +19
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not convinced there should be 1+ H2 headings for this, the design should be covered by a single H2 section and N subsections, otherwise we'll break the structure which we're trying to standardize somewhat I think.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree this looks good on the template, as it is more standardized, but having a large document with many subsections forced into a H2 brings a horrible result, at least IMO. As an example, check the Ruby design in this commit, and how I changed it in the following ones. For smaller docs, I believe a single H2 works perfectly.

I am not sure what's the best option here. If nobody minds the excessive nesting (and the hard limit on the H5), then let's just make it a single H2.

(I even considered a separate template for new package manager designs, although I think I still prefer to keep things simple).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

with many subsections forced into a H2 brings a horrible result

We can agree that it's a matter of taste. On the other hand...

If nobody minds the excessive nesting (and the hard limit on the H5)

... if we ever need to go past H5 then I guess we need to rethink whether a given design really needs it, I don't expect that to be a regular thing, but I might be wrong here.


## Decision/Outcome [pick one]

Document here what decision was made, or what outcome is expected out of the design that was created. In case several options were presented in the design, this section must clearly state which one was chosen and the reasons for it. In case of a new package manager design, or a completely new feature to an existing package manager, this section can only include a brief summary of what the implementation will cover, since it is implied that the decision.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nitpick: Is the description of the intended content for these sections being purposefully done so that it can be rendered online? I mean, the only thing I expect from a template is to be copy-pasted, renamed, filled out and proposed. So, if we make these description commentaries, people can even keep those comments in their proposed doc and that information won't be rendered, just a bit of thinking out loud.

35 changes: 16 additions & 19 deletions docs/designs/rubygems-001.md → docs/designs/0002-rubygems-initial-design.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,26 +1,25 @@
# Initial Design for the Rubygems Package Manager

- [Overview](#overview)
- [Introduction](#introduction)
- [Context](#context)
- [Ruby ecosystem overview](#i-ruby-ecosystem-overview)
- [Current implementation overview (Cachito)](#ii-overview-of-the-current-implementation-in-cachito)
- [Design for the Cachi2 implementation](#iii-design-for-the-implementation-in-cachi2)
- [Decision](#decision)
- [Ruby ecosystem overview](#ruby-ecosystem-overview)
- [Current implementation overview (Cachito)](#overview-of-the-current-implementation-in-cachito)
- [Design for the Cachi2 implementation](#design-for-the-implementation-in-cachi2)
- [Outcomes](#outcomes)

## Overview
## Introduction

Design that covers the initial implementation of the Rubygem/Bundler package manager in Cachi2. It takes inspiration from the original implementation done in [Cachito](https://github.com/containerbuildsystem/cachito).
Design that covers the initial implementation of the Rubygem/Bundler package manager in Cachi2. It takes inspiration from the original implementation done in [Cachito](https://github.com/containerbuildsystem/cachito).

| | |
|---------|---------|
|Author |[Michal Šoltis]([email protected]) |
|Co-author |[Bruno Pimentel]([email protected]) |
|Proposed on |August 01, 2024 |
This document has three main parts:
- An overview on how the Ruby ecosystem works, touching only the parts that are relevant to the Cachi2 implementation
- A quick overview on how the implementation was done in Cachito
- The actual design for the implementation in Cachi2

## Context
In the effort to evolve Cachi2 to be a full solution for the prefetching feature of Cachito, we have decided to implement support to the currently missing package managers: Rubygems and Yarn v1. This design covers only the implementation of Rubygems, and the Yarn v1 design will follow.

## I. Ruby ecosystem overview
## Ruby ecosystem overview

### Development prerequisites
In order to execute the commands in the examples below, make sure you have the following packages installed in your
Expand Down Expand Up @@ -240,7 +239,7 @@ CHECKSUMS
This feature is available since Bundler [v2.5.0](https://github.com/rubygems/rubygems/blob/master/bundler/lib/bundler/lockfile_parser.rb#L55),
from this [PR](https://github.com/rubygems/rubygems/pull/6374) being merged on Oct 21, 2023.

## II. Overview of the current implementation in Cachito
## Overview of the current implementation in Cachito

[cachito/workers/pkg_mangers/rubygems.py](https://github.com/containerbuildsystem/cachito/blob/master/cachito/workers/pkg_managers/rubygems.py)

Expand All @@ -258,7 +257,7 @@ which is vendored from
Source code for "official" Bundler lockfile parsing in Ruby:
<https://github.com/rubygems/rubygems/blob/master/bundler/lib/bundler/lockfile_parser.rb>

## III. Design for the implementation in Cachi2
## Design for the implementation in Cachi2

### Prefetching

Expand Down Expand Up @@ -517,9 +516,7 @@ PATH
my-path-dependency (1.0.0)
```

## Decision

The support for Rubygems will be implemented as currently described in this design document.
## Outcomes

### Scoping of the initial implementation
- design high-level code structure into multiple modules
Expand All @@ -535,7 +532,7 @@ The support for Rubygems will be implemented as currently described in this desi
- add integration and e2e tests
- add documentation

### Potential follow-up features
### Out of scope
- implement checksum parsing and validation when prefetching from the registry
- downloading the Bundler version specified in the `Gemfile.lock`
- support for pre-compiled binaries (platforms other than `ruby`)
Expand Down
9 changes: 0 additions & 9 deletions docs/designs/template-000.md
View file
Open in desktop
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Filenames in the draft imply naming scheme with shared counter. This should probably be documented somewhere.

This file was deleted.