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.

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

[docs]: change ideas from md to structure dir tree #4

Closed
wants to merge 4 commits into from
Closed

[docs]: change ideas from md to structure dir tree #4

wants to merge 4 commits into from

Conversation

eldios
Copy link
Contributor

@eldios eldios commented Feb 3, 2024

This PR aims at moving the ideas.md Markdown to a proper dirtree to future
proof it, while also making it clear and easy for new ideas contributors.

Open to improvement, tuning up/down and simplifications.

@eldios eldios mentioned this pull request Feb 3, 2024
ideas/README.md Outdated Show resolved Hide resolved
ideas/README.md Outdated Show resolved Hide resolved
Comment on lines +17 to +20
### ID
The ID is composed by the current year and an incremental 4 digit integer
assigned by one of the repo maintainers and will also be the directory name
that will contain all the artifacts for that idea.
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
### ID
The ID is composed by the current year and an incremental 4 digit integer
assigned by one of the repo maintainers and will also be the directory name
that will contain all the artifacts for that idea.

What would you need that for? The directory can just be named after the title, no need to introduce extra complexity in my opinion. This would also make it harder for people to just PR ideas since they will have to ask for a id.

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 think it's just simpler to use numerical IDs instead of having to remember the exact title.

Maybe we can use the PR number associated with the idea as the ID?

Not a huge deal if they think it's not useful, could be my personal preference.

ideas/README.md Outdated Show resolved Hide resolved
ideas/README.md Outdated Show resolved Hide resolved
ideas/README.md Outdated Show resolved Hide resolved
Comment on lines +92 to +141
## Idea Example

This is an example of a real idea that was submitted https://github.com/NixOS/GSoC2024/pull/3

### Metadata

**ID**: [2024/0001](./ideas/2024/0001)

**Title**: [nixpkgs] nixpkgs library networking functions

**Author**: FREE

**Proposed Menthor**: [@Janik-Haag](https://github.com/Janik-Haag)

**Effort**: SMALL

**Difficulty**: MEDIUM

**Overview/Abstract**: Add a set of built-in networking functions to
`nixpkgs.lib` to improve contributors UX.

### Description

Many things in NixOS use the Internet Protocol and other network related
technologies, thus a lot of modules and service have to deal with them.
Currently this is mostly done just passing strings as arguments, but it would
be a lot more convenient to have things like `lib.types.ipv6`, `lib.types.ipv4`
and other functions to for example convert between cidr notation and the bit
representation of netmasks. This would not just be useful for NixOS it self but
also for its users since a lot of folks use it to power network appliances and
build infrastructure on top of it.

**Skills required/preferred**:
Some prior networking knowledge would be useful but not required.
Prior knowledge of the nix programming language is not required.
Anyone new-comer wanting to pick this up should easily be able to complete a
nix tutorial like [a tour of Nix](https://nixcloud.io/tour/?id=introduction/nix)
in one or two afternoons and be good to go.

**Prior efforts**:
There was some prior efforts in
[nixpkgs#258250](https://github.com/NixOS/nixpkgs/pull/258250) but it is stuck
for a few months now and also only adds function for legacy ip, it's also quite
bare bones and we might want some more advanced things like a function to check
if a ip matches a given subnet.

### Linkography

* [A tour of Nix](https://nixcloud.io/tour/?id=introduction/nix)
* [nixpkgs#258250](https://github.com/NixOS/nixpkgs/pull/258250)
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
## Idea Example
This is an example of a real idea that was submitted https://github.com/NixOS/GSoC2024/pull/3
### Metadata
**ID**: [2024/0001](./ideas/2024/0001)
**Title**: [nixpkgs] nixpkgs library networking functions
**Author**: FREE
**Proposed Menthor**: [@Janik-Haag](https://github.com/Janik-Haag)
**Effort**: SMALL
**Difficulty**: MEDIUM
**Overview/Abstract**: Add a set of built-in networking functions to
`nixpkgs.lib` to improve contributors UX.
### Description
Many things in NixOS use the Internet Protocol and other network related
technologies, thus a lot of modules and service have to deal with them.
Currently this is mostly done just passing strings as arguments, but it would
be a lot more convenient to have things like `lib.types.ipv6`, `lib.types.ipv4`
and other functions to for example convert between cidr notation and the bit
representation of netmasks. This would not just be useful for NixOS it self but
also for its users since a lot of folks use it to power network appliances and
build infrastructure on top of it.
**Skills required/preferred**:
Some prior networking knowledge would be useful but not required.
Prior knowledge of the nix programming language is not required.
Anyone new-comer wanting to pick this up should easily be able to complete a
nix tutorial like [a tour of Nix](https://nixcloud.io/tour/?id=introduction/nix)
in one or two afternoons and be good to go.
**Prior efforts**:
There was some prior efforts in
[nixpkgs#258250](https://github.com/NixOS/nixpkgs/pull/258250) but it is stuck
for a few months now and also only adds function for legacy ip, it's also quite
bare bones and we might want some more advanced things like a function to check
if a ip matches a given subnet.
### Linkography
* [A tour of Nix](https://nixcloud.io/tour/?id=introduction/nix)
* [nixpkgs#258250](https://github.com/NixOS/nixpkgs/pull/258250)

We should just link to a idea list from the year before

Copy link
Contributor Author

Choose a reason for hiding this comment

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

yes but I don't think we have one now... or I couldn't find it.

I think we should links theirs for now ([PR#3]) and then fro next year on, link one from the year before.

Also, if we're going to reuse this repo for all years, it should probably be renamed (GSoC2024 -> GSoC or NixGSoC)

Comment on lines +86 to +90
### Linkography

* [Link1](https://localhost/THIS_IS_CLEARLY_A_BROKEN_LINK): Link1 explanation
* [Link2](https://localhost/THIS_IS_CLEARLY_A_BROKEN_LINK): Link2 explanation
* [Link3](https://localhost/THIS_IS_CLEARLY_A_BROKEN_LINK): Link3 explanation
Copy link
Member

Choose a reason for hiding this comment

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

what is the usecase for "linkography"?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

It's used in case you have links that should to be available at a glance as external reference for the reader (say the project homepage, docs, etc..).

Comment on lines +61 to +64
## Idea Template

This would be a PR aimed at creating a README.md file with the content below
in the directory [ideas/2024/0000](./ideas/2024/0000).
Copy link
Member

Choose a reason for hiding this comment

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

Putting every idea in it's own directory will make it hard to read through all of them at once because you will have to open different pages for each one.
It should be a ideas-list so I think we should just put them in one file and sort them by size.
Please remember that this should be a low level entry point with ideas for newbies.
It should also be easy and minimal effort for mentors to propose ideas, we have the RFC process for complex and large proposals.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

yes but the RFC process is not related t other GSoC initiative.

I agree about the idea list and that's why I wanted to keep the README.md as a "summary"/"index" which then points to the different directories that can contain all the needed data, including additional files, images, source code files, etc..

Maybe I'm over-optimizing :)

ideas/README.md Outdated Show resolved Hide resolved
Co-authored-by: Janik <80165193+Janik-Haag@users.noreply.github.com>
@Janik-Haag Janik-Haag mentioned this pull request Feb 3, 2024
@Janik-Haag
Copy link
Member

Janik-Haag commented Feb 5, 2024

closing in favor of #6
note that I rebased on top of your pull request to keep your contribution ^^

@Janik-Haag Janik-Haag closed this Feb 5, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants