From 62394c219d0dc0ddfe4220468fac6012071035d5 Mon Sep 17 00:00:00 2001 From: Fraser Greenroyd Date: Mon, 12 Feb 2024 16:31:05 +0000 Subject: [PATCH] Fix sidebar --- .../Beta patching procedure.md | 26 ++++++------ .../Beta testing procedure.md | 18 ++++---- .../End of milestone procedure.md | 42 +++++++++---------- .../Preparing a new milestone.md | 26 ++++++------ .../Producing a beta installer.md | 8 ++-- 5 files changed, 60 insertions(+), 60 deletions(-) diff --git a/docs/DevOps/Operating Procedures/Beta patching procedure.md b/docs/DevOps/Operating Procedures/Beta patching procedure.md index 6990b1c7..7a7dbe77 100644 --- a/docs/DevOps/Operating Procedures/Beta patching procedure.md +++ b/docs/DevOps/Operating Procedures/Beta patching procedure.md @@ -1,41 +1,41 @@ -# 1 - Beta Patching +# Beta Patching The contents of this page detail the actions to be undertaken in the event of a desire to provide a patch to a beta release. These procedures may be updated at any point. -# 2 - Related documents +# 1 - Related documents The following documents are not considered part of this procedure, but contain additional information which may be beneficial. It is recommended these are read in conjunction with this document. - [Beta testing procedure](Beta-testing-procedure) - [Producing a beta installer guide](Producing-a-beta-installer) -# 3 - Activation of this procedure +# 2 - Activation of this procedure Activation of this procedure is done by DevOps at any time that a repository included in the beta installer receives a bug fix to its `main` branch outside of the final sprint of a milestone, or where one or more repositories may have not been included in the initial release where more testing may have been required. If the development cycle is currently in the final sprint of a milestone, then a beta patch cannot be produced as a new beta is being created, and the bug fix should be dispatched for that beta instead. -# 4 - Procedure for patching - missing repositories +# 3 - Procedure for patching - missing repositories Where a repository has not made the initial beta due to issues with testing and the pull request from `develop` into `main` has been closed, this pull request will be reopened and undergo the standard testing and review procedure. Once the Pull Request is merged, DevOps will then carry out the following functions. -# 5 - Procedure for patching - bug fixes +# 4 - Procedure for patching - bug fixes A new branch from `main` for the repository to be patched should be made, with code written to resolve the bug and reviewed via a Pull Request in the usual manner without circumventing the standard code review procedures. The Pull Request must be tested thoroughly, ideally against any existing test procedure for that repository where available. Where a test procedure is not available, it is the Discipline Code Lead who is responsible for signing off on the Pull Request. Once the Pull Request is merged, DevOps will then carry out the following functions. -## 5.1 - Patching `develop` +## 4.1 - Patching `develop` The same branch (if not deleted) can be used to patch `develop` as well and ensure the bug fix is in both branches so alphas aren't affected either. Thie pull request can be handled in the usual fashion as it will be going into `develop` as part of that milestone and not need any special support. However, it is important that the bug fix is put into `develop` to prevent the patch being needed again at the end of the milestone when `develop` is merged into `main`. -# 6 - Preparing the patch +# 5 - Preparing the patch The following actions must be undertaken to prepare the beta patch. -## 6.1 - Change log update +## 5.1 - Change log update DevOps responsible for generating an updated change log for the patched beta to include the change being fixed. -## 6.2 - Create the tag on the repository +## 5.2 - Create the tag on the repository DevOps is responsible for tagging the repository with the appropriate patch number. @@ -43,11 +43,11 @@ Should the patch number be required, the patch number should always be 1 greater An important note to make, is the `TargetCommit` must be set to `main` to target the `main` branch - otherwise it will default to target the default branch (which is `develop` for beta repositories). This will cause issues if not set and other work is committed to `develop` before the tags are completed. -## 6.3 - Produce the beta installers +## 5.3 - Produce the beta installers Full details of producing a beta installer can be found in the [Producing a Beta Installer guide](Producing-a-beta-installer). -## 6.4 - Testing the beta installer +## 5.4 - Testing the beta installer DevOps is responsible for deciding the scope of testing the patched beta artefact. Where there is any doubt as to the potential scope of changes produced by the patch, a full beta test should be conducted, as per the guidelines in [this procedure](End-of-Milestone-procedure#release-beta-installer-for-testing). @@ -55,10 +55,10 @@ Where the scope of testing can be clearly defined, the Discipline Lead of the af The testing of the beta patch artefact should be a matter of priority, and the DevOps lead and Discipline Code Lead should remain in regular contact to ensure the results are reported back ASAP. Ideally this should be completed by the end of the next business day at the latest. -## 6.5 - Releasing the beta installer +## 5.5 - Releasing the beta installer This is to be done in line with the release of a standard beta, the procedure for which can be found [here](End-of-Milestone-procedure#release-beta-installer-publicly). -# 7 - External website +# 6 - External website The BHoM.xyz website should be updated as appropriate, including new API updates were applicable. \ No newline at end of file diff --git a/docs/DevOps/Operating Procedures/Beta testing procedure.md b/docs/DevOps/Operating Procedures/Beta testing procedure.md index 31b1d258..81511297 100644 --- a/docs/DevOps/Operating Procedures/Beta testing procedure.md +++ b/docs/DevOps/Operating Procedures/Beta testing procedure.md @@ -1,16 +1,16 @@ -# 1 - Beta Testing +# Beta Testing The contents of this page detail the actions to be undertaken, with approximate timings, at the end of a Milestone to test the Beta installers in the lead up to the release of that Milestones beta. These procedures may be updated at any point. This document forms part of the [End of Milestone Procedure](End-of-Milestone-procedure). -# 2 - Purpose +# 1 - Purpose The purpose of this test procedure is to ensure that all aspects of the Beta installers are checked in the lead up to the production of the Beta installer. The outcome of this procedure is to give confidence to those using the Beta that the toolkits and operations will work as designed. -# 3 - Scope +# 2 - Scope The scope of testing is restricted to elements of the installer most likely to impact use of the installers. It is not designed to sign off as a complete bug-free installer, however, the state of the Beta should not be worse than that of its previous version. This ensures that each Beta trends towards a more positive setting with each release. -# 4 - Running tests +# 3 - Running tests Each discipline lead is responsible for ensuring suitable, adequate, and reasonable tests are conducted on each of the toolkits within their group. These tests should be run as often as possible during a milestone, but are strictly monitored during the final sprint of a milestone. @@ -18,11 +18,11 @@ During the final sprint, a discipline lead must ensure they, or a suitable membe It is advised that testing utilises the formal test procedures where applicable to make the process of testing and verifying the code base easier, as test procedures should capture the core functionality. Where a test procedure does not exist, it is the responsibility of the discipline lead to ensure suitable testing is carried out. -## 4.1 - Test Reports +## 3.1 - Test Reports Each day during the final sprint, the DevOps Lead or their appointed deputy is responsible for collating the test reports. Test reports should confirm what toolkits have been tested, whether any toolkits have been exempted (see below), and any issues that have been found. It is the responsibility of each Discipline Lead to provide accurate information upon request on the state of their testing. -## 4.2 - Fixing issues +## 3.2 - Fixing issues It is the responsibility of each Discipline Lead to triage issues found as a result of testing. Any bug which did not exist in the previous Beta should be prioritised, following standard best practice for issue management generally. Bugs which existed in the previous Beta should not be prioritised during this period (though may be triaged and resolved if there are no other issues). @@ -40,7 +40,7 @@ Discipline leads are responsible for ensuring they have adequate resource to res If an issue is resolved with the approval of DevOps, and merged to the repository's `develop` branch, DevOps will reproduce the Pull Request which merges `develop` into `main` to include this additional fix. -## 4.3 - Exceptions +## 3.3 - Exceptions It may be appropriate for a toolkit to not receive testing every day during the final sprint, providing the following criteria can be met. @@ -50,10 +50,10 @@ It may be appropriate for a toolkit to not receive testing every day during the The Discipline Lead of the toolkits concerned may consult with other relevant stakeholders, including other Discipline Leads, however, the final responsibility for testing, or skipping, a toolkit resides with the Discipline Lead. It is recommended that should any of the criteria above not be met, that the toolkit undergo a subsequent retest. -# 5 - Merging `develop` into `main` +# 4 - Merging `develop` into `main` Once suitable testing has been conducted on the Pull Request which is aimed to be deployed in the Beta, the testers must comment with suitable approving reviews. The Discipline Code Lead must then inform DevOps that the Pull Request is ready to be merged, and DevOps will then merge the Pull Request for deployment if it is deemed appropriate to do so. Instances where it may not be appropriate to merge a Pull Request include if the Pull Request is depending on code in a higher repository (for example BHoM_Engine) that has not yet been merged. In these cases the Pull Request may have to wait, and may risk not being included if the higher repository Pull Request is not subsequently deployed. -# 6 - Final Beta test +# 5 - Final Beta test After the creation of the Beta artefact, the Beta must be signed off by each Discipline Lead. The Beta must be tested against all available Test Procedures for code residing within the installer. Additional tests are allowed, but cannot be used as substitutions to the test procedures. Where a test procedure does not exist, the Discipline Lead is responsible for ensuring adequate and suitable testing is performed for that area of code. \ No newline at end of file diff --git a/docs/DevOps/Operating Procedures/End of milestone procedure.md b/docs/DevOps/Operating Procedures/End of milestone procedure.md index b8f6bc32..88d4d665 100644 --- a/docs/DevOps/Operating Procedures/End of milestone procedure.md +++ b/docs/DevOps/Operating Procedures/End of milestone procedure.md @@ -1,4 +1,4 @@ -# 1 - End of milestone +# End of milestone The contents of this page detail the actions to be undertaken at the end of a given Milestone. These procedures may be updated at any point. @@ -10,15 +10,15 @@ The following documents are considered part of this procedure, and contain more - [Producing a beta installer guide](Producing-a-beta-installer) - [Preparing a new Milestone](Preparing-a-new-Milestone) -# 2 - Scope +# 1 - Scope The scope of this document is restricted to the end of a development Milestone as decided by DevOps. Interpretation of this procedure rests with the DevOps Lead or their nominated individual. -# 3 - Events +# 2 - Events -### 3.1 - Final Sprint Begins +### 2.1 - Final Sprint Begins The final sprint is placed under `feature-freeze` whereby any code which matches the definition of a `feature` is blocked from being merged into the beta code. Clarifications on what constitutes a `feature` can be sought from the DevOps Team. @@ -26,11 +26,11 @@ During the final sprint, all development should be done against the daily test a Development teams are responsible for ensuring their developers undertake this practice, and core users within their teams should also begin moving from the previous beta to new alphas and test artefacts in this sprint to aid the testing process. Discipline leads may be asked to confirm certain progress reports of testing during this phase. -### 3.2 - Beta Test Procedure takes effect +### 2.2 - Beta Test Procedure takes effect The Beta Test Procedure is outlined in [this document](Beta-testing-procedure) and will be followed in accordance with the above statement regarding developing against the Beta installers. The DevOps team will oversee this operation during the lifecycle of the final sprint. -### 3.3 - `develop` into `main` +### 2.3 - `develop` into `main` All repositories which are set to be included in the Beta must have Pull Requests raised to merge the code which has been developed during the milestone from their respective `develop` branches into their `main` branches for deployment. @@ -40,11 +40,11 @@ The branch name must be suitable and unique for the milestone as this will form Each Pull Request must be reviewed and signed off by the relevant testers as determined by each Discipline Code Lead prior to it being merged to `main`. Where a Pull Request is dependant on upstream changes (e.g. a Toolkit depending on a BHoM_Engine change), the upstream changes must be prioritised for testing and review, even if the Toolkit Pull Request does not then get merged. -### 3.4 - Pull Request lock down +### 2.4 - Pull Request lock down Pull Request lock down will be put into effect once the Pull Requests for merging `develop` into `main` have been raised. No Pull Request may be merged into a repository that is included in the Beta without approval from DevOps. -### 3.5 - Final merging of `develop` into `main` +### 2.5 - Final merging of `develop` into `main` The deadline for the final merging of any Pull Request aiming to deploy code to the beta will be announced by DevOps at the start of the final sprint, but will not be later than 9am on the day of the artefact being produced. @@ -52,7 +52,7 @@ Once this deadline has passed, any Pull Requests not yet merged for deployment w If a Toolkit requires alignment updates to compile and deploy, a separate Pull Request will be raised by DevOps which performs this alignment with no further changes incorporated. -### 3.6 - Tagging +### 2.6 - Tagging Each repository included in the beta must be tagged at the commit latest to `main` for the version being produced. @@ -60,7 +60,7 @@ An important note to make, is the `TargetCommit` must be set to `main` to target The installer repository should also be tagged to correspond to the version of the installer at the time the beta was produced. -### 3.7 - Change Log Creation +### 2.7 - Change Log Creation The Change Log is prepared by a member of the DevOps team using the authorised script. The Change Log should encompass every pull request merged during the milestone to the `main` branch for deployment, from every repository included within the installer. @@ -69,7 +69,7 @@ The following checks must be done as part of the Change Log Creation: - That the grouping categories are correctly set - Toolkits are correctly included change logs as appropriate -### 3.8 - Prepare release notes script +### 2.8 - Prepare release notes script The Release Notes script puts a release tag onto the `main` branches of repositories included within the installer. The release notes are prepared by a member of the DevOps team using the authorised script. The release notes should follow the standard for BHoM releases. @@ -80,7 +80,7 @@ The following checks must be done as part of the Release Notes preparation: Authorisation for the execution of the script during this preparation and testing phase resides with the DevOps team. -### 3.9 - Dispatch release notes +### 2.9 - Dispatch release notes A manual release is to be made of the BHoM_Documentation repository. These releases are to contain their correct titles, but their bodies may be left blank while the change log is produced. @@ -92,11 +92,11 @@ Once the appropriate change logs are prepared, these should be edited into the r Authorisation for final execution of the script resides with the Governance team. -### 3.10 - Produce beta installer +### 2.10 - Produce beta installer Full details of producing a beta installer can be found in the [Producing a Beta Installer guide](Producing-a-beta-installer). -### 3.11 - Release beta installer for testing +### 2.11 - Release beta installer for testing The beta installer should be released to the key individuals responsible for toolkits across the organisations for testing. Testing should ensure their toolkits show up correctly, and work as intended for the given release. This testing is a final review, with testing of functionality ideally done during the final sprint using daily alphas. @@ -104,7 +104,7 @@ The discipline team leads are responsible for reporting back to the DevOps team The release should be made public on appropriate collaboration channels. -### 3.12 - Accepting or Rejecting the Beta +### 2.12 - Accepting or Rejecting the Beta Following the final testing and reporting back to the DevOps Team, a final judgement will be made as to whether the beta should be released to the public. If the testing is inadequate, or there are significant issues that may be caused by the release of the beta, then the beta may be rejected. Any person may petition for a beta to be rejected if they feel it would be prudent to do so, however, the final decision to accept or reject the beta resides with the DevOps Team. @@ -125,26 +125,26 @@ It is not appropriate to deliver a partial beta, owing to the interconnected wor Until a beta is released, or the milestone is closed out in the event of abandoning a beta, the pull request freeze remains in effect, unless otherwise decided by the DevOps Team. -### 3.13 - Close milestone +### 2.13 - Close milestone The milestone should be closed and the GitHub milestones updated to reflect the new development periods. -### 3.14 - Prepare next milestone +### 2.14 - Prepare next milestone Following the close out of the milestone, the next milestone should be set up ready to begin as soon as is appropriate. Typically, this might be after a weekend, but should be set up in such a way that the next milestone could begin the next day after release. Full details of actions needed to be undertaken to set up the next milestone can be found in the [Preparing a new Milestone Procedure](Preparing-a-new-Milestone) -# 4 - Communications of the end of the milestone +# 3 - Communications of the end of the milestone -### 4.1 - Release beta installer publicly +### 3.1 - Release beta installer publicly Once the installer has been reviewed, and the discipline leads have reported back to the DevOps team their acceptance of the installer, the installer should be release for general consumption. This should be done in the following ways. -#### 4.2 - Update of external website +#### 3.2 - Update of external website The BHoM.xyz website should be updated by a member of the DevOps team to incorporate the new public installer for the end of the milestone. The website should be updated to highlight this is a new installer, and references changed as appropriate. -# 5 - Lift PR lock down +# 4 - Lift PR lock down The lock down of Pull Request merging can now be lifted, with Pull Requests able to be merged as appropriate as part of the code creation for the next set of alphas and subsequent beta. The lifting of Pull Request lock down must be clearly announced on Teams and other appropriate communication channels. \ No newline at end of file diff --git a/docs/DevOps/Operating Procedures/Preparing a new milestone.md b/docs/DevOps/Operating Procedures/Preparing a new milestone.md index f1bbd65b..5a686368 100644 --- a/docs/DevOps/Operating Procedures/Preparing a new milestone.md +++ b/docs/DevOps/Operating Procedures/Preparing a new milestone.md @@ -1,22 +1,22 @@ -# 1 - Preparing a new milestone +# Preparing a new milestone The contents of this page detail the actions to be undertaken at the beginning of a given Milestone. These procedures may be updated at any point. -# 2 - Related documents +# 1 - Related documents The following documents are considered related to this procedure. It is recommended these are read in conjunction with this document for a full understanding of the procedures being followed. - [End of Milestone procedure](End-of-Milestone-procedure) -# 3 - Purpose +# 2 - Purpose The purpose of this procedure is to outline the steps which are to be taken during the transition period from one milestone to the next. Due to the nature of development, the current development calendar does not provide for hard breaks between development cycles. The release of one beta, and end of that milestone, does not have breathing space to the next milestone. This is afforded by the slick operation in which milestones are turned around, benefited by the experience and skill of the team involved, and the automation of many of the processes involved, requiring only oversight. -# 4 - Halting this procedure +# 3 - Halting this procedure If at any time an event occurs which draws the capability of the new milestone being advanced into doubt, the Governance lead or the CI/CD lead may bring a halt to proceedings. Halting this procedure should be done prior to any irreversible changes being made to the code base as part of this procedure. Should a halting of this procedure be initiated, the Governance and CI/CD teams should meet to discuss the situation and prepare a continuation plan that allows the cause of the halt to be handled. As appropriate, other discipline leads should be updated and included in that process, particularly where a halting of the procedure may cause a delay to development. -# 5 - Tasks +# 4 - Tasks The following tasks should be completed as part of the preparation of a new milestone. Full details of each task are given further below. All of the tasks below are the responsibility of the CI/CD lead to ensure completion, however, many tasks will be delegated to suitable individuals. @@ -29,36 +29,36 @@ The following tasks should be completed as part of the preparation of a new mile - The `PreviousVersionAttribute`s should be removed across all repositories, along with all `Versioning_xy.json` files - Upticking of copyright versions on BHoM repositories only -## 5.1 - Closure of milestones +## 4.1 - Closure of milestones The planning milestones on repositories included within the installer for the milestone just completed should be closed, including both RC and Release milestones. -## 5.2 - Opening of milestones +## 4.2 - Opening of milestones Unless previously done, the milestones for RC and Release, with appropriate deadline dates, should be opened and added to all repositories included within the installer. -## 5.3 - Upticking installers +## 4.3 - Upticking installers The [installer](https://github.com/BHoM/BHoM_Installer) should be upticked within their code base to ensure the latest set of alphas reflect the new milestone. -## 5.4 - Upticking Test Toolkit +## 4.4 - Upticking Test Toolkit [Test_Toolkit](https://github.com/BHoM/Test_Toolkit) also has a reference to the current milestone in development to aid with some compliance checks, and should be updated in the following locations: - CodeComplianceTest_Engine/Query/CurrentVersion.cs -## 5.5 - Assembly File Version updates +## 4.5 - Assembly File Version updates The script to allow BHoMBot to update the Assembly File Versions should be executed. Pull Requests should be merged within 2 days of being raised, as Assembly File Versions have to be accurate to allow versioning to work appropriately. There should be no reason for delay to this task, and the CI/CD lead should work with Discipline leads to ensure timely merging of those Pull Requests. -## 5.6 - New Versioning Upgrader +## 4.6 - New Versioning Upgrader The [Versioning_Toolkit](https://github.com/BHoM/Versioning_Toolkit) needs to have a new upgrader added with the previous upgrader locked for future developments. -## 5.7 - Removal of `PreviousVersion` attributes +## 4.7 - Removal of `PreviousVersion` attributes To keep the code base tidy, the script allowing BHoMBot to remove `PreviousVersion` attributes on code should be executed. Pull Requests should be merged within 5 days of being raised. -## 5.8 - Upticking of copyright +## 4.8 - Upticking of copyright Once per year, in the first sprint of January, all code within the BHoM organisation needs copyrights to be updated to reflect the new year. The script to allow BHoMBot to do this should be executed, and Pull Requests merged within 5 days. BHoMBot copyright compliance checks will be provided to aid checking that the copyright is valid, with Discipline leads then responsible for merging the Pull Requests around other Pull Requests, but no later than 5 days after being raised. diff --git a/docs/DevOps/Operating Procedures/Producing a beta installer.md b/docs/DevOps/Operating Procedures/Producing a beta installer.md index 5e1f0597..7b1ae622 100644 --- a/docs/DevOps/Operating Procedures/Producing a beta installer.md +++ b/docs/DevOps/Operating Procedures/Producing a beta installer.md @@ -1,12 +1,12 @@ -# 1 - Producing a beta installer +# Producing a beta installer This outlines the steps necessary to follow to obtain a beta installer, and make it available for testing and release. This document forms part of the [End of Milestone Procedure](End-of-Milestone-procedure). -# 2 - Scope +# 1 - Scope This procedure/guide is designed for the creation of a beta installer at the end of a milestone, or when a patch is required. -## 2.1 - Pre-information/decisions +## 1.1 - Pre-information/decisions The following information is to be provided and authorised by the DevOps team: @@ -14,7 +14,7 @@ The following information is to be provided and authorised by the DevOps team: - ReleaseType - this should be set to beta for any beta installer - Version - this should be set to the end of milestone version, inclusive of v - e.g. v3.0 v3.1, etc. -## 2.2 - Beta Test Artefacts +# 2 - Beta Test Artefacts Prior to the distribution of the beta, beta test artefacts are to be produced during each day of the final sprint of the milestone. These are generated by BHoMBot at 3am UK time and should be set up by DevOps to trigger nightly.