Update Upstream Release doc #9952
Conversation
The step was still referring to the stabilization branch. This was the case before the process review. Now the contributors list is updated before the stabilization branch be created.
PRs merged in stabilization branch should also be merged in master branch. Therefore, it is a good practice to set a prefix which makes easier to distinguish stabilization PRs.
marcusburghardt
added
enhancement
|
Start a new ephemeral environment with changes proposed in this pull request: Fedora Environment Oracle Linux 8 Environment |
| It is a good for the community when the packages are also updated and released with the latest | ||
| stable release. In this section there is information about how to update the packages in specific | ||
| distros. | ||
| ## Fedora |
There was a problem hiding this comment.
I'm not sure it makes sense to have a step by step for Fedora here.
Will we add and maintain a "how to" for other distros as well?
And actually, maybe the section about Fedora updates shouldn't be here in the upstream release docs.
There was a problem hiding this comment.
The guide for Fedora builds is very detailed and will definitely help someone with the builds.
But I feel that this makes more sense as a separate doc.
There was a problem hiding this comment.
For me it makes a lot of sense to have this step by step here. In case of Fedora, updating the packages when a new Upstream release is out is directly connected in the process.
Therefore, it is much better to have the relevant steps here than only pointing the users to Fedora documentation where there is indeed a rich documentation but not everything is relevant for the context of scap-security-guide package context. These steps here are handful when updating the packages.
Also, if packages in other distros are also updated based on the latest Upstream Releases, contributions including their steps here are welcome.
There was a problem hiding this comment.
Still, the upstream release is a separate process from Fedora, and other distros downstream builds.
My main suggestion here was to separate the Fedora Guide into a separate doc.
What do you think about moving them to a separate file and just linking them from the upstream release guide?
There was a problem hiding this comment.
I see. This is not a huge doc. I don't see enough value decentralizing the document content now. If we receive more Downstream content from other distros or if this document becomes too big and difficult to be consumed, then I totally agree in assess how to split the content and organize it in a reasonable way. We don't know if more contributions will come from Downstream. If so, what would they look like? Since we don't know this, it is difficult to already create a new file structure which will be useful. It would create an avoidable risk of unnecessary rework in the future. For now, in the current context, if we split and decentralize the content we would only have more small files to maintain in the project without too much value. So, I suggest to keep it simpler now. When the demand appears we can of course rethink the documentation structure.
There was a problem hiding this comment.
I slightly disagree, the consumers for the upstream release and the downstream build docs are different, separating the documents facilitates doc usage for both roles. (The person doing the upstream release is not tied to the Fedora package)
The structure doesn't matter much, but it could be opening up the path for other distro's build guides.
I agree that we may not see guides for other downstream builds, and that is why I also questioned the need for this in the upstream project.
Anyway, I don't feel strongly about this. The detailed guide is a good addition.
These references make it easier and faster for the person who is conducting the process.
This makes the documentation even clearer.
There are plenty of good documentation about Fedora processes. However, the process to update scap-security-guide package happen each two months and should be conducted by different engineers. Therefore, if a person is not so used to the Fedora Package process or did it long time ago, reading the complete documentation to find the proper commands could take some time. This documentation intends to save time and define a standard process applicable for scap-security-guide in Fedora.
marcusburghardt
force-pushed
the
upstream_release_doc
branch
from
aedeb50
to
55ee9a2
Compare
Split the builds section and add a new one about updates.
An alternative to building the package locally is to build it on Koji.
|
Code Climate has analyzed commit 14c0343 and detected 0 issues on this pull request. The test coverage on the diff in this pull request is 100.0% (50% is the threshold). This pull request will bring the total coverage in the repository to 48.8% (0.0% change). View more on Code Climate. |
Description:
I had the opportunity to conduct the
0.1.65release and along the process I reviewed and improved theRelease Processdocumentation.Rationale:
Good and complete documentation saves time for everybody and ensures better quality standards.
Review Hints:
The section related to Fedora Packages is completely new and would be good if an experienced Fedora Packager review it. Nevertheless they are precisely showing the steps I executed during the release process.
Regarding the improvements in already existing sections, it would be good to observe any sentence prone to misinterpretation.