MichaelMure/git-bug
1
1
Fork 0
mirror of https://github.com/MichaelMure/git-bug.git synced 2024-12-13 20:13:15 +03:00
Code Issues Projects Releases Wiki Activity

Merge pull request #762 from MichaelMure/fix-comment

Browse Source 
Fix a bunch of comments and documentations
This commit is contained in:
Michael Muré 2022-03-10 16:37:45 +01:00 committed by GitHub
commit bf9c7e00d0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
17 changed files with 43 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
bug/bug.go
View File

@ -28,7 +28,7 @@ var def = dag.Definition{
var ClockLoader = dag.ClockLoader(def)
// Bug hold the data of a bug thread, organized in a way close to
// Bug holds the data of a bug thread, organized in a way close to
// how it will be persisted inside Git. This is the data structure
// used to merge two different version of the same Bug.
type Bug struct {

10
bug/bug_actions.go
View File

@ -22,13 +22,15 @@ func Push(repo repository.Repo, remote string) (string, error) {
// Pull will do a Fetch + MergeAll
// This function will return an error if a merge fail
func Pull(repo repository.ClockedRepo, remote string, author identity.Interface) error {
// Note: an author is necessary for the case where a merge commit is created, as this commit will
// have an author and may be signed if a signing key is available.
func Pull(repo repository.ClockedRepo, remote string, mergeAuthor identity.Interface) error {
_, err := Fetch(repo, remote)
if err != nil {
return err
}
for merge := range MergeAll(repo, remote, author) {
for merge := range MergeAll(repo, remote, mergeAuthor) {
if merge.Err != nil {
return merge.Err
}
@ -43,7 +45,7 @@ func Pull(repo repository.ClockedRepo, remote string, author identity.Interface)
// MergeAll will merge all the available remote bug
// Note: an author is necessary for the case where a merge commit is created, as this commit will
// have an author and may be signed if a signing key is available.
func MergeAll(repo repository.ClockedRepo, remote string, author identity.Interface) <-chan entity.MergeResult {
func MergeAll(repo repository.ClockedRepo, remote string, mergeAuthor identity.Interface) <-chan entity.MergeResult {
// no caching for the merge, we load everything from git even if that means multiple
// copy of the same entity in memory. The cache layer will intercept the results to
// invalidate entities if necessary.
@ -54,7 +56,7 @@ func MergeAll(repo repository.ClockedRepo, remote string, author identity.Interf
go func() {
defer close(out)
results := dag.MergeAll(def, repo, identityResolver, remote, author)
results := dag.MergeAll(def, repo, identityResolver, remote, mergeAuthor)
// wrap the dag.Entity into a complete Bug
for result := range results {

2
bug/op_add_comment.go
View File

@ -64,7 +64,7 @@ func (op *AddCommentOperation) Validate() error {
return nil
}
// UnmarshalJSON is a two step JSON unmarshalling
// UnmarshalJSON is a two-steps JSON unmarshalling
// This workaround is necessary to avoid the inner OpBase.MarshalJSON
// overriding the outer op's MarshalJSON
func (op *AddCommentOperation) UnmarshalJSON(data []byte) error {

8
bug/op_edit_comment.go
View File

@ -101,7 +101,7 @@ func (op *EditCommentOperation) Validate() error {
return nil
}
// UnmarshalJSON is a two step JSON unmarshalling
// UnmarshalJSON is two steps JSON unmarshalling
// This workaround is necessary to avoid the inner OpBase.MarshalJSON
// overriding the outer op's MarshalJSON
func (op *EditCommentOperation) UnmarshalJSON(data []byte) error {
@ -144,7 +144,7 @@ func NewEditCommentOp(author identity.Interface, unixTime int64, target entity.I
}
}
// Convenience function to apply the operation
// EditComment is a convenience function to apply the operation
func EditComment(b Interface, author identity.Interface, unixTime int64, target entity.Id, message string) (*EditCommentOperation, error) {
return EditCommentWithFiles(b, author, unixTime, target, message, nil)
}
@ -158,13 +158,13 @@ func EditCommentWithFiles(b Interface, author identity.Interface, unixTime int64
return editCommentOp, nil
}
// Convenience function to edit the body of a bug (the first comment)
// EditCreateComment is a convenience function to edit the body of a bug (the first comment)
func EditCreateComment(b Interface, author identity.Interface, unixTime int64, message string) (*EditCommentOperation, error) {
createOp := b.FirstOp().(*CreateOperation)
return EditComment(b, author, unixTime, createOp.Id(), message)
}
// Convenience function to edit the body of a bug (the first comment)
// EditCreateCommentWithFiles is a convenience function to edit the body of a bug (the first comment)
func EditCreateCommentWithFiles(b Interface, author identity.Interface, unixTime int64, message string, files []repository.Hash) (*EditCommentOperation, error) {
createOp := b.FirstOp().(*CreateOperation)
return EditCommentWithFiles(b, author, unixTime, createOp.Id(), message, files)

4
bug/snapshot.go
View File

@ -26,7 +26,7 @@ type Snapshot struct {
Operations []Operation
}
// Return the Bug identifier
// Id returns the Bug identifier
func (snap *Snapshot) Id() entity.Id {
if snap.id == "" {
// simply panic as it would be a coding error (no id provided at construction)
@ -35,7 +35,7 @@ func (snap *Snapshot) Id() entity.Id {
return snap.id
}
// Return the last time a bug was modified
// EditTime returns the last time a bug was modified
func (snap *Snapshot) EditTime() time.Time {
if len(snap.Operations) == 0 {
return time.Unix(0, 0)

2
bug/timeline.go
View File

@ -10,7 +10,7 @@ import (
)
type TimelineItem interface {
// ID return the identifier of the item
// Id return the identifier of the item
Id() entity.Id
}

8
cache/bug_cache.go vendored
View File

@ -12,10 +12,10 @@ import (
var ErrNoMatchingOp = fmt.Errorf("no matching operation found")
// BugCache is a wrapper around a Bug. It provide multiple functions:
// BugCache is a wrapper around a Bug. It provides multiple functions:
//
// 1. Provide a higher level API to use than the raw API from Bug.
// 2. Maintain an up to date Snapshot available.
// 2. Maintain an up-to-date Snapshot available.
// 3. Deal with concurrency.
type BugCache struct {
repoCache *RepoCache
@ -235,7 +235,7 @@ func (c *BugCache) SetTitleRaw(author *IdentityCache, unixTime int64, title stri
return op, c.notifyUpdated()
}
// Convenience function to edit the body of a bug (the first comment)
// EditCreateComment is a convenience function to edit the body of a bug (the first comment)
func (c *BugCache) EditCreateComment(body string) (*bug.EditCommentOperation, error) {
author, err := c.repoCache.GetUserIdentity()
if err != nil {
@ -245,7 +245,7 @@ func (c *BugCache) EditCreateComment(body string) (*bug.EditCommentOperation, er
return c.EditCreateCommentRaw(author, time.Now().Unix(), body, nil)
}
// Convenience function to edit the body of a bug (the first comment)
// EditCreateCommentRaw is a convenience function to edit the body of a bug (the first comment)
func (c *BugCache) EditCreateCommentRaw(author *IdentityCache, unixTime int64, body string, metadata map[string]string) (*bug.EditCommentOperation, error) {
c.mu.Lock()
op, err := bug.EditCreateComment(c.bug, author.Identity, unixTime, body)

2
cache/repo_cache_bug.go vendored
View File

@ -457,7 +457,7 @@ func (c *RepoCache) NewBugWithFiles(title string, message string, files []reposi
return c.NewBugRaw(author, time.Now().Unix(), title, message, files, nil)
}
// NewBugWithFilesMeta create a new bug with attached files for the message, as
// NewBugRaw create a new bug with attached files for the message, as
// well as metadata for the Create operation.
// The new bug is written in the repository (commit)
func (c *RepoCache) NewBugRaw(author *IdentityCache, unixTime int64, title string, message string, files []repository.Hash, metadata map[string]string) (*BugCache, *bug.CreateOperation, error) {

20
doc/queries.md
View File

@ -21,7 +21,7 @@ A few tips:
You can filter bugs based on their status.
| Qualifier | Example |
| --- | --- |
|-----------------|-------------------------------------|
| `status:open` | `status:open` matches open bugs |
| `status:closed` | `status:closed` matches closed bugs |
@ -30,7 +30,7 @@ You can filter bugs based on their status.
You can filter based on the person who opened the bug.
| Qualifier | Example |
| --- | --- |
|----------------|----------------------------------------------------------------------------------|
| `author:QUERY` | `author:descartes` matches bugs opened by `René Descartes` or `Robert Descartes` |
| | `author:"rené descartes"` matches bugs opened by `René Descartes` |
@ -39,7 +39,7 @@ You can filter based on the person who opened the bug.
You can filter based on the person who participated in any activity related to the bug (opened bug or added a comment).
| Qualifier | Example |
| --- | --- |
|---------------------|----------------------------------------------------------------------------------------------------|
| `participant:QUERY` | `participant:descartes` matches bugs opened or commented by `René Descartes` or `Robert Descartes` |
| | `participant:"rené descartes"` matches bugs opened or commented by `René Descartes` |
@ -48,7 +48,7 @@ You can filter based on the person who participated in any activity related to t
You can filter based on the person who interacted with the bug.
| Qualifier | Example |
| --- | --- |
|---------------|---------------------------------------------------------------------------------|
| `actor:QUERY` | `actor:descartes` matches bugs edited by `René Descartes` or `Robert Descartes` |
| | `actor:"rené descartes"` matches bugs edited by `René Descartes` |
@ -59,7 +59,7 @@ You can filter based on the person who interacted with the bug.
You can filter based on the bug's label.
| Qualifier | Example |
| --- | --- |
|---------------|---------------------------------------------------------------------------|
| `label:LABEL` | `label:prod` matches bugs with the label `prod` |
| | `label:"Good first issue"` matches bugs with the label `Good first issue` |
@ -68,7 +68,7 @@ You can filter based on the bug's label.
You can filter based on the bug's title.
| Qualifier | Example |
| --- | --- |
|---------------|--------------------------------------------------------------------------------|
| `title:TITLE` | `title:Critical` matches bugs with a title containing `Critical` |
| | `title:"Typo in string"` matches bugs with a title containing `Typo in string` |
@ -78,7 +78,7 @@ You can filter based on the bug's title.
You can filter bugs based on the absence of something.
| Qualifier | Example |
| --- | --- |
|------------|----------------------------------------|
| `no:label` | `no:label` matches bugs with no labels |
## Sorting
@ -90,7 +90,7 @@ Note: to deal with differently-set clocks on distributed computers, `git-bug` us
### Sort by Id
| Qualifier | Example |
| --- | --- |
|----------------------------|-------------------------------------------------------|
| `sort:id-desc` | `sort:id-desc` will sort bugs by their descending Ids |
| `sort:id` or `sort:id-asc` | `sort:id` will sort bugs by their ascending Ids |
@ -99,7 +99,7 @@ Note: to deal with differently-set clocks on distributed computers, `git-bug` us
You can sort bugs by their creation time.
| Qualifier | Example |
| --- | --- |
|-----------------------------------------|---------------------------------------------------------------------|
| `sort:creation` or `sort:creation-desc` | `sort:creation` will sort bugs by their descending creation time |
| `sort:creation-asc` | `sort:creation-asc` will sort bugs by their ascending creation time |
@ -108,6 +108,6 @@ You can sort bugs by their creation time.
You can sort bugs by their edit time.
| Qualifier | Example |
| --- | --- |
|---------------------------------|---------------------------------------------------------------------|
| `sort:edit` or `sort:edit-desc` | `sort:edit` will sort bugs by their descending last edition time |
| `sort:edit-asc` | `sort:edit-asc` will sort bugs by their ascending last edition time |

6
entity/dag/entity.go
View File

@ -21,9 +21,9 @@ const editClockPattern = "%s-edit"
// Definition hold the details defining one specialization of an Entity.
type Definition struct {
// the name of the entity (bug, pull-request, ...)
// the name of the entity (bug, pull-request, ...), for human consumption
Typename string
// the Namespace in git (bugs, prs, ...)
// the Namespace in git references (bugs, prs, ...)
Namespace string
// a function decoding a JSON message into an Operation
OperationUnmarshaler func(author identity.Interface, raw json.RawMessage) (Operation, error)
@ -121,7 +121,7 @@ func read(def Definition, repo repository.ClockedRepo, resolver identity.Resolve
// Next step is to:
// 1) read the operationPacks
// 2) make sure that the clocks causality respect the DAG topology.
// 2) make sure that clocks causality respect the DAG topology.
oppMap := make(map[repository.Hash]*operationPack)
var opsCount int

2
entity/dag/entity_actions.go
View File

@ -89,7 +89,7 @@ func MergeAll(def Definition, repo repository.ClockedRepo, resolver identity.Res
return out
}
// merge perform a merge to make sure a local Entity is up to date.
// merge perform a merge to make sure a local Entity is up-to-date.
// See MergeAll for more details.
func merge(def Definition, repo repository.ClockedRepo, resolver identity.Resolver, remoteRef string, author identity.Interface) entity.MergeResult {
id := entity.RefToId(remoteRef)

2
entity/dag/operation_pack.go
View File

@ -81,7 +81,7 @@ func (opp *operationPack) Validate() error {
return nil
}
// Write write the OperationPack in git, with zero, one or more parent commits.
// Write writes the OperationPack in git, with zero, one or more parent commits.
// If the repository has a keypair able to sign (that is, with a private key), the resulting commit is signed with that key.
// Return the hash of the created commit.
func (opp *operationPack) Write(def Definition, repo repository.Repo, parentCommit ...repository.Hash) (repository.Hash, error) {

2
entity/id.go
View File

@ -63,7 +63,7 @@ func (i Id) MarshalGQL(w io.Writer) {
_, _ = w.Write([]byte(`"` + i.String() + `"`))
}
// IsValid tell if the Id is valid
// Validate tell if the Id is valid
func (i Id) Validate() error {
// Special case to detect outdated repo
if len(i) == 40 {

2
entity/id_interleaved.go
View File

@ -22,7 +22,7 @@ import (
//
// A complete interleaved Id hold 50 characters for the primary and 14 for the
// secondary, which give a key space of 36^50 for the primary (~6 * 10^77) and
// 36^14 for the secondary (~6 * 10^21). This asymmetry assume a reasonable number
// 36^14 for the secondary (~6 * 10^21). This asymmetry assumes a reasonable number
// of secondary within a primary Entity, while still allowing for a vast key space
// for the primary (that is, a globally merged database) with a low risk of collision.
//

2
entity/refs.go
View File

@ -13,7 +13,7 @@ func RefsToIds(refs []string) []Id {
return ids
}
// RefsToIds parse a git reference and return the corresponding Entity's Id.
// RefToId parse a git reference and return the corresponding Entity's Id.
func RefToId(ref string) Id {
split := strings.Split(ref, "/")
return Id(split[len(split)-1])

8
identity/identity.go
View File

@ -381,9 +381,9 @@ func (i *Identity) NeedCommit() bool {
//
// To make sure that an Identity history can't be altered, a strict fast-forward
// only policy is applied here. As an Identity should be tied to a single user, this
// should work in practice but it does leave a possibility that a user would edit his
// should work in practice, but it does leave a possibility that a user would edit his
// Identity from two different repo concurrently and push the changes in a non-centralized
// network of repositories. In this case, it would result in some of the repo accepting one
// network of repositories. In this case, it would result in some repo accepting one
// version and some other accepting another, preventing the network in general to converge
// to the same result. This would create a sort of partition of the network, and manual
// cleaning would be required.
@ -396,9 +396,9 @@ func (i *Identity) NeedCommit() bool {
// However, this approach leave the possibility, in the case of a compromised crypto keys,
// of forging a new version with a bogus Lamport time to be inserted before a legit version,
// invalidating the correct version and hijacking the Identity. There would only be a short
// period of time where this would be possible (before the network converge) but I'm not
// period of time when this would be possible (before the network converge) but I'm not
// confident enough to implement that. I choose the strict fast-forward only approach,
// despite it's potential problem with two different version as mentioned above.
// despite its potential problem with two different version as mentioned above.
func (i *Identity) Merge(repo repository.Repo, other *Identity) (bool, error) {
if i.Id() != other.Id() {
return false, errors.New("merging unrelated identities is not supported")

2
identity/interface.go
View File

@ -57,6 +57,6 @@ type Interface interface {
// Validate check if the Identity data is valid
Validate() error
// Indicate that the in-memory state changed and need to be commit in the repository
// NeedCommit indicate that the in-memory state changed and need to be committed in the repository
NeedCommit() bool
}