Submission context, or, what to compare?
A file size reading you submit to BundleCop is only useful if we can compare it to a previous reading, and see the changes. But which previous reading?
We can’t just take the most recent one; you might be working on both a large UX revamp, while a the same time preparing a minor patch release for an older version. Thus, it would we helpful to know the name of the branch.
If you are reviewing a pull request, you might mostly be interested in how these changes compare to the current master branch. It would be helpful to know if a file size reading belongs to such a pull request.
Note: This is an advanced discussion, and we’d rather you don’t have to deal with it. The BundleCop submission tools try to colect all the information automatically. See the list of supported tools.
Along with the file size readings, we support the following metadata:
While all of these fields are optional, but the more of them we know, the better we can create a model of how the readings you submit are related.
In git, this is the commit’s sha hash. It allows BundleCop to link the reading to the right commit in your repository. This is necessary for example if you want to integrate with Github, and have the file sizes attached to pull requests.
This field, and the commitId, in combination allow us to know exactly how each reading relates to one another.
If the combination commitId/parentCommitId is not available, BundleCop will use the branch name to find the most recent file reading from that branch, and compare with that.
This is not quite as reliable as using the commit ids, because if you submit readings from development machines, a sngle branch can be diverging. However, it is good enough for almost all use cases.
If this flag is set, you indicate to bundlecop during your submission that you are more interested in comparing this reading with the current master branch, rather than it’s parent commit.
The value of this flag can either be a boolean, or it can be the name of the base branch. In the former case, the name of the base branch needs to be defined in your project settings.
Making the decision
When you submit a new reading, BundleCop picks one previous reading, compares the two, and presents the results to you. It uses the following logic:
If isFeatureBranch is set, and the reading from the base branch can be found, then use the most recent reading from the base branch for the comparision.
Otherwise, if there is a parentCommit and a reading for it can be found, use it for the comparison.
Note that various edge case will be handled fine: If you submit multiple readings for the same commit id (e.g. based on builds with uncommited changes), or you submit multipe children for the same parent commit (e.g. in case of rebasing), BundleCop will pick the most recent suitable reading.
Otherise, if there is only a branchName, find the most recent reading for that branch and use it for the comparison.
Finally, if everything else fails, use the oms recent reading submitted for the comparison.