Artifactspublic-v0

curl

master
ply4 git calls54 ms290 KiB3 cachedprotocol v2
175 lines5.9 KiBRaw

How to do code reviews for curl

Anyone and everyone is encouraged and welcome to review code submissions in curl. This is a guide on what to check for and how to perform a successful code review.

All submissions should get reviewed

All pull requests and patches submitted to the project should be reviewed by at least one experienced curl maintainer before that code is accepted and merged.

Let the tools and tests take the first rounds

On initial pull requests, let the tools and tests do their job first and then start out by helping the submitter understand the test failures and tool alerts.

How to provide feedback to author

Be nice. Ask questions. Provide examples or suggestions of improvements. Assume the best intentions. Remember language barriers.

All first-time contributors can become regulars. Let's help them go there.

Is this a change we want?

If this is not a change that seems to be aligned with the project's path forward and as such cannot be accepted, inform the author about this sooner rather than later. Do it gently and explain why and possibly what could be done to make it more acceptable.

API/ABI stability or changed behavior

Changing the API and the ABI may be fine in a change but it needs to be done deliberately and carefully. If not, a reviewer must help the author to realize the mistake.

curl and libcurl are similarly strict on not modifying existing behavior. API and ABI stability is not enough, the behavior should also remain intact as far as possible.

Code style

Most code style nits are detected by checksrc but not all. Only leave remarks on style deviation once checksrc does not find anymore.

Minor nits from fresh submitters can also be handled by the maintainer when merging, in case it seems like the submitter is not clear on what to do. We want to make the process fun and exciting for new contributors.

Encourage consistency

Make sure new code is written in a similar style as existing code. Naming, logic, conditions, etc.

Are pointers always non-NULL?

If a function or code rely on pointers being non-NULL, take an extra look if that seems to be a fair assessment.

Asserts

Conditions that should never be false can be verified with DEBUGASSERT() calls to get caught in tests and debugging easier, while not having an impact on final or release builds.

Memory allocation

Can the mallocs be avoided? Do not introduce mallocs in any hot paths. If there are (new) mallocs, can they be combined into fewer calls?

Are all allocations handled in error paths to avoid leaks and crashes?

Thread-safety

We do not like static variables as they break thread-safety and prevent functions from being reentrant.

Should features be #ifdefed?

Features and functionality may not be present everywhere and should therefore be #ifdefed. Additionally, some features should be possible to switch on/off in the build.

Write #ifdefs to be as little of a "maze" as possible.

Does it look portable enough?

curl runs "everywhere". Does the code take a reasonable stance and enough precautions to be possible to build and run on most platforms?

Remember that we live by C89 restrictions.

Tests and testability

New features should be added in conjunction with one or more test cases. Ideally, functions should also be written so that unit tests can be done to test individual functions.

Documentation

New features or changes to existing functionality must be accompanied by updated documentation. Submitting that in a separate follow-up pull request is not OK. A code review must also verify that the submitted documentation update matches the code submission.

English is not everyone's first language, be mindful of this and help the submitter improve the text if it needs a rewrite to read better.

Code should not be hard to understand

Source code should be written to maximize readability and be easy to understand.

Functions should not be large

A single function should never be large as that makes it hard to follow and understand all the exit points and state changes. Some existing functions in curl certainly violate this ground rule but when reviewing new code we should propose splitting into smaller functions.

Duplication is evil

Anything that looks like duplicated code is a red flag. Anything that seems to introduce code that we should already have or provide needs a closer check.

Sensitive data

When credentials are involved, take an extra look at what happens with this data. Where it comes from and where it goes.

Variable types differ

size_t is not a fixed size. time_t can be signed or unsigned and have different sizes. Relying on variable sizes is a red flag.

Also remember that endianness and >= 32-bit accesses to unaligned addresses are problematic areas.

Integer overflows

Be careful about integer overflows. Some variable types can be either 32-bit or 64-bit. Integer overflows must be detected and acted on before they happen.

Dangerous use of functions

Maybe use of realloc() should rather use the dynbuf functions?

Do not allow new code that grows buffers without using dynbuf.

Use of C functions that rely on a null-terminator must only be used on data that really do have a null-terminator (\0 byte).

Dangerous "data styles"

Make extra precautions and verify that memory buffers that need null-terminator always have exactly that. Buffers without a null-terminator must not be used as input to string functions.

Commit messages

Tightly coupled with a code review is making sure that the commit message is good. It is the responsibility of the person who merges the code to make sure that the commit message follows our standard (detailed in the CONTRIBUTE document). This includes making sure the PR identifies related issues and giving credit to reporters and helpers.

1<!--
2Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
4SPDX-License-Identifier: curl
5-->
7# How to do code reviews for curl
9Anyone and everyone is encouraged and welcome to review code submissions in
10curl. This is a guide on what to check for and how to perform a successful
11code review.
13## All submissions should get reviewed
15All pull requests and patches submitted to the project should be reviewed by
16at least one experienced curl maintainer before that code is accepted and
17merged.
19## Let the tools and tests take the first rounds
21On initial pull requests, let the tools and tests do their job first and then
22start out by helping the submitter understand the test failures and tool
23alerts.
25## How to provide feedback to author
27Be nice. Ask questions. Provide examples or suggestions of improvements.
28Assume the best intentions. Remember language barriers.
30All first-time contributors can become regulars. Let's help them go there.
32## Is this a change we want?
34If this is not a change that seems to be aligned with the project's path
35forward and as such cannot be accepted, inform the author about this sooner
36rather than later. Do it gently and explain why and possibly what could be
37done to make it more acceptable.
39## API/ABI stability or changed behavior
41Changing the API and the ABI may be fine in a change but it needs to be done
42deliberately and carefully. If not, a reviewer must help the author to realize
43the mistake.
45curl and libcurl are similarly strict on not modifying existing behavior. API
46and ABI stability is not enough, the behavior should also remain intact as far
47as possible.
49## Code style
51Most code style nits are detected by checksrc but not all. Only leave remarks
52on style deviation once checksrc does not find anymore.
54Minor nits from fresh submitters can also be handled by the maintainer when
55merging, in case it seems like the submitter is not clear on what to do. We
56want to make the process fun and exciting for new contributors.
58## Encourage consistency
60Make sure new code is written in a similar style as existing code. Naming,
61logic, conditions, etc.
63## Are pointers always non-NULL?
65If a function or code rely on pointers being non-NULL, take an extra look if
66that seems to be a fair assessment.
68## Asserts
70Conditions that should never be false can be verified with `DEBUGASSERT()`
71calls to get caught in tests and debugging easier, while not having an impact
72on final or release builds.
74## Memory allocation
76Can the mallocs be avoided? Do not introduce mallocs in any hot paths. If
77there are (new) mallocs, can they be combined into fewer calls?
79Are all allocations handled in error paths to avoid leaks and crashes?
81## Thread-safety
83We do not like static variables as they break thread-safety and prevent
84functions from being reentrant.
86## Should features be `#ifdef`ed?
88Features and functionality may not be present everywhere and should therefore
89be `#ifdef`ed. Additionally, some features should be possible to switch on/off
90in the build.
92Write `#ifdef`s to be as little of a "maze" as possible.
94## Does it look portable enough?
96curl runs "everywhere". Does the code take a reasonable stance and enough
97precautions to be possible to build and run on most platforms?
99Remember that we live by C89 restrictions.
101## Tests and testability
103New features should be added in conjunction with one or more test cases.
104Ideally, functions should also be written so that unit tests can be done to
105test individual functions.
107## Documentation
109New features or changes to existing functionality **must** be accompanied by
110updated documentation. Submitting that in a separate follow-up pull request is
111not OK. A code review must also verify that the submitted documentation update
112matches the code submission.
114English is not everyone's first language, be mindful of this and help the
115submitter improve the text if it needs a rewrite to read better.
117## Code should not be hard to understand
119Source code should be written to maximize readability and be easy to
120understand.
122## Functions should not be large
124A single function should never be large as that makes it hard to follow and
125understand all the exit points and state changes. Some existing functions in
126curl certainly violate this ground rule but when reviewing new code we should
127propose splitting into smaller functions.
129## Duplication is evil
131Anything that looks like duplicated code is a red flag. Anything that seems to
132introduce code that we *should* already have or provide needs a closer check.
134## Sensitive data
136When credentials are involved, take an extra look at what happens with this
137data. Where it comes from and where it goes.
139## Variable types differ
141`size_t` is not a fixed size. `time_t` can be signed or unsigned and have
142different sizes. Relying on variable sizes is a red flag.
144Also remember that endianness and >= 32-bit accesses to unaligned addresses
145are problematic areas.
147## Integer overflows
149Be careful about integer overflows. Some variable types can be either 32-bit
150or 64-bit. Integer overflows must be detected and acted on *before* they
151happen.
153## Dangerous use of functions
155Maybe use of `realloc()` should rather use the dynbuf functions?
157Do not allow new code that grows buffers without using dynbuf.
159Use of C functions that rely on a null-terminator must only be used on data
160that really do have a null-terminator (`\0` byte).
162## Dangerous "data styles"
164Make extra precautions and verify that memory buffers that need
165null-terminator always have exactly that. Buffers *without* a null-terminator
166must not be used as input to string functions.
168# Commit messages
170Tightly coupled with a code review is making sure that the commit message is
171good. It is the responsibility of the person who merges the code to make sure
172that the commit message follows our standard (detailed in the
173[CONTRIBUTE](https://curl.se/dev/contribute.html) document). This includes
174making sure the PR identifies related issues and giving credit to reporters
175and helpers.
Diagnostics4 git calls · 54 ms
CallStatusSizeTime054 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200149 B · hit3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=3
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=149
git.pkt.payload.max=78
git.ls_refs.count=2
git.ls_refs.head=refs/heads/master
fetchblob:none · deepen 10200287 KiB · hit25 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=25
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=31c911efe5652725e930f4d2e60c9060e5f6646d
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=10
git.pkt.data=8
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=293470
git.pkt.payload.max=65516
git.sideband.band1.bytes=293354
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=87
git.pack.bytes=293354
git.pack.ofs_delta=0
git.pack.ref_delta=1
git.pack.chain.max=1
git.pack.trailer=6a646bcda6740bab42e321b51998b52ea15146c0
git.pack.full=86
Open pack map
fetch2002.8 KiB · hit26 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=26
git.response.bytes=2873
git.response.cache=HIT
git.response.duration_ms=26
git.fetch.wants=a80d2eec3ce2b5504bd52732cee80adff0c95da0
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=2873
git.pkt.payload.max=2852
git.sideband.band1.bytes=2851
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/curl.git
Ref
refs/heads/master
Commit
31c911efe5652725e930f4d2e60c9060e5f6646d
cf-ray
a5e155ba0b9f90ce
Request
01d9c4cd…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format