golang/go

all: document the default doc assumptions around concurrency, zero values, interfaces and return values

Open

#30.632 geöffnet am 6. März 2019

Auf GitHub ansehen
 (6 Kommentare) (0 Reaktionen) (0 zugewiesene Personen)Go (19.008 Forks)batch import
DocumentationNeedsInvestigationSuggestedhelp wanted

Repository-Metriken

Stars
 (133.883 Stars)
PR-Merge-Metriken
 (Keine gemergten PRs in 30 T)

Beschreibung

In general, across all go libraries, some documentation rules are implicit. As @bradfitz worded it:

The assumption when unstated is that things are not safe for concurrent use, that zero values are not usable, that implementations implement interfaces faithfully, and that only one return values is non-zero and meaningful.

This is a very important piece of knowledge and I think it should be documented somewhere. I don't know if the right place for it would be "Effective Go" (especially considering #28782) but it feels like newcomers should know this before they start browsing Go docs or writing Go code.

Contributor Guide

Research-Richtung
Identifizieren Sie die geeignete Stelle in der Go Dokumentation (z. B. Effective Go, FAQ oder ein neues Dokument), um einen Abschnitt über Standardannahmen bezüglich Nebenläufigkeitssicherheit, Nullwerten, Implementierungen von Schnittstellen und Rückgabewerten hinzuzufügen. Sammeln Sie Konsens aus der Community über Kommentare im Issue.
Tech Stack
go
Domain
documentation
Issue Type
Dokumentation
SchwierigkeitGeschätzte Implementierungsschwierigkeit für neue Contributors, von 1 für sehr kleine Änderungen bis 5 für Expertenarbeit.
2
Geschätzte ZeitEin grober Zeitrahmen, um zu recherchieren, zu implementieren, zu testen und einen Pull Request vorzubereiten.
1-3 Stunden
AktivitätsstatusWie verfügbar das Issue gerade wirkt: frisch, aktiv, stale, blockiert oder wartet auf Maintainer-Input.
Veraltet
KlarheitWie klar das Issue die erwartete Änderung, Akzeptanzkriterien und den nächsten Schritt erklärt.
Klar
Voraussetzungen
Go
EinsteigerfreundlichkeitEin Score von 1 bis 100, der schätzt, wie zugänglich dieses Issue für First-Time Contributors ist.
65